Sqlite-utils

- The `--load-extension=spatialite` option and [find_spatialite()](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-gis-find-spatialite) utility function now both work correctly on `arm64` Linux. Thanks, [Mike Coats](https://github.com/MikeCoats). ([#599](https://github.com/simonw/sqlite-utils/issues/599))
- Fix for bug where `sqlite-utils insert` could cause your terminal cursor to disappear. Thanks, [Luke Plant](https://github.com/spookylukey). ([#433](https://github.com/simonw/sqlite-utils/issues/433))
- `datetime.timedelta` values are now stored as `TEXT` columns. Thanks, [Harald Nezbeda](https://github.com/nezhar). ([#522](https://github.com/simonw/sqlite-utils/issues/522))
- Test suite is now also run against Python 3.12.

- Fixed a bug where [table.transform()](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-transform) would sometimes re-assign the `rowid` values for a table rather than keeping them consistent across the operation. ([592](https://github.com/simonw/sqlite-utils/issues/592))

Adding foreign keys to a table no longer uses `PRAGMA writable_schema = 1` to directly manipulate the `sqlite_master` table. This was resulting in errors in some Python installations where the SQLite library was compiled in a way that prevented this from working, in particular on macOS. Foreign keys are now added using the [table transformation](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-transform) mechanism instead. ([577](https://github.com/simonw/sqlite-utils/issues/577))

This new mechanism creates a full copy of the table, so it is likely to be significantly slower for large tables, but will no longer trigger table `sqlite_master may not be modified` errors on platforms that do not support `PRAGMA writable_schema = 1`.

A new plugin, [sqlite-utils-fast-fks](https://github.com/simonw/sqlite-utils-fast-fks), is now available for developers who still want to use that faster but riskier implementation.

Other changes:

- The [table.transform() method](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-transform) has two new parameters: `foreign_keys=` allows you to replace the foreign key constraints defined on a table, and `add_foreign_keys=` lets you specify new foreign keys to add. These complement the existing `drop_foreign_keys=` parameter. ([577](https://github.com/simonw/sqlite-utils/issues/577))
- The [sqlite-utils transform](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-transform-table) command has a new `--add-foreign-key` option which can be called multiple times to add foreign keys to a table that is being transformed. ([585](https://github.com/simonw/sqlite-utils/issues/585))
- [sqlite-utils convert](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-convert) now has a `--pdb` option for opening a debugger on the first encountered error in your conversion script. ([581](https://github.com/simonw/sqlite-utils/issues/581))
- Fixed a bug where `sqlite-utils install -e '.[test]'` option did not work correctly.

This release introduces a new [plugin system](https://sqlite-utils.datasette.io/en/stable/plugins.html#plugins). ([567](https://github.com/simonw/sqlite-utils/issues/567))

- Documentation describing [how to build a plugin](https://sqlite-utils.datasette.io/en/stable/plugins.html#plugins-building).
- Plugin hook: [register_commands(cli)](https://sqlite-utils.datasette.io/en/stable/plugins.html#plugins-hooks-register-commands), for plugins to add extra commands to `sqlite-utils`. ([569](https://github.com/simonw/sqlite-utils/issues/569))
- Plugin hook: [prepare_connection(conn)](https://sqlite-utils.datasette.io/en/stable/plugins.html#plugins-hooks-prepare-connection). Plugins can use this to help prepare the SQLite connection to do things like registering custom SQL functions. Thanks, [Alex Garcia](https://github.com/asg017). ([#574](https://github.com/simonw/sqlite-utils/issues/574))
- `sqlite_utils.Database(..., execute_plugins=False)` option for disabling plugin execution. ([575](https://github.com/simonw/sqlite-utils/issues/575))
- `sqlite-utils install -e path-to-directory` option for installing editable code. This option is useful during the development of a plugin. ([570](https://github.com/simonw/sqlite-utils/issues/570))
- `table.create(...)` method now accepts `replace=True` to drop and replace an existing table with the same name, or `ignore=True` to silently do nothing if a table already exists with the same name. ([568](https://github.com/simonw/sqlite-utils/issues/568))
- `sqlite-utils insert ... --stop-after 10` option for stopping the insert after a specified number of records. Works for the `upsert` command as well. ([561](https://github.com/simonw/sqlite-utils/issues/561))
- The `--csv` and `--tsv` modes for `insert` now accept a `--empty-null` option, which cases empty strings in the CSV file to be stored as `null` in the database. ([563](https://github.com/simonw/sqlite-utils/issues/563))
- New `db.rename_table(table_name, new_name)` method for renaming tables. ([565](https://github.com/simonw/sqlite-utils/issues/565))
- `sqlite-utils rename-table my.db table_name new_name` command for renaming tables. ([565](https://github.com/simonw/sqlite-utils/issues/565))
- The `table.transform(...)` method now takes an optional `keep_table=new_table_name` parameter, which will cause the original table to be renamed to `new_table_name` rather than being dropped at the end of the transformation. ([571](https://github.com/simonw/sqlite-utils/issues/571))
- Documentation now notes that calling `table.transform()` without any arguments will reformat the SQL schema stored by SQLite to be more aesthetically pleasing. ([564](https://github.com/simonw/sqlite-utils/issues/564))

- `sqlite-utils` will now use [sqlean.py](https://github.com/nalgeon/sqlean.py) in place of `sqlite3` if it is installed in the same virtual environment. This is useful for Python environments with either an outdated version of SQLite or with restrictions on SQLite such as disabled extension loading or restrictions resulting in the `sqlite3.OperationalError: table sqlite_master may not be modified` error. ([#559](https://github.com/simonw/sqlite-utils/issues/559))
- New `with db.ensure_autocommit_off()` context manager, which ensures that the database is in autocommit mode for the duration of a block of code. This is used by `db.enable_wal()` and `db.disable_wal()` to ensure they work correctly with `pysqlite3` and `sqlean.py`.
- New `db.iterdump()` method, providing an iterator over SQL strings representing a dump of the database. This uses `sqlite-dump` if it is available, otherwise falling back on the `conn.iterdump()` method from `sqlite3`. Both `pysqlite3` and `sqlean.py` omit support for `iterdump()` - this method helps paper over that difference.

- Examples in the [CLI documentation](https://sqlite-utils.datasette.io/en/stable/cli.html) can now all be copied and pasted without needing to remove a leading `$`. ([#551](https://github.com/simonw/sqlite-utils/issues/551))
- Documentation now covers [Setting up shell completion](https://sqlite-utils.datasette.io/en/stable//installation.html#installation-completion) for `bash` and `zsh`. ([552](https://github.com/simonw/sqlite-utils/issues/552))