3.34
2023-07-22T23:25:14Z
This release introduces a new plugin system. (#567)
- Documentation describing how to build a plugin.
- Plugin hook: register_commands(cli), for plugins to add extra commands to
sqlite-utils
. (#569) - Plugin hook: prepare_connection(conn). Plugins can use this to help prepare the SQLite connection to do things like registering custom SQL functions. Thanks, Alex Garcia. (#574)
sqlite_utils.Database(..., execute_plugins=False)
option for disabling plugin execution. (#575)sqlite-utils install -e path-to-directory
option for installing editable code. This option is useful during the development of a plugin. (#570)table.create(...)
method now acceptsreplace=True
to drop and replace an existing table with the same name, orignore=True
to silently do nothing if a table already exists with the same name. (#568)sqlite-utils insert ... --stop-after 10
option for stopping the insert after a specified number of records. Works for theupsert
command as well. (#561)- The
--csv
and--tsv
modes forinsert
now accept a--empty-null
option, which cases empty strings in the CSV file to be stored asnull
in the database. (#563) - New
db.rename_table(table_name, new_name)
method for renaming tables. (#565) sqlite-utils rename-table my.db table_name new_name
command for renaming tables. (#565)- The
table.transform(...)
method now takes an optionalkeep_table=new_table_name
parameter, which will cause the original table to be renamed tonew_table_name
rather than being dropped at the end of the transformation. (#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)
3.33
2023-06-26T01:31:22Z
sqlite-utils
will now use sqlean.py in place ofsqlite3
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 thesqlite3.OperationalError: table sqlite_master may not be modified
error. (#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 bydb.enable_wal()
anddb.disable_wal()
to ensure they work correctly withpysqlite3
andsqlean.py
. - New
db.iterdump()
method, providing an iterator over SQL strings representing a dump of the database. This usessqlite-dump
if it is available, otherwise falling back on theconn.iterdump()
method fromsqlite3
. Bothpysqlite3
andsqlean.py
omit support foriterdump()
- this method helps paper over that difference.
3.32.1
2023-05-21T21:11:54Z
- Examples in the CLI documentation can now all be copied and pasted without needing to remove a leading
$
. (#551) - Documentation now covers Setting up shell completion for
bash
andzsh
. (#552)
3.32
2023-05-21T18:53:44Z
- New experimental
sqlite-utils tui
interface for interactively building command-line invocations, powered by Trogon. This requires an optional dependency, installed usingsqlite-utils install trogon
. There is a screenshot in the documentation. (#545) sqlite-utils analyze-tables
command (documentation) now has a--common-limit 20
option for changing the number of common/least-common values shown for each column. (#544)sqlite-utils analyze-tables --no-most
and--no-least
options for disabling calculation of most-common and least-common values.- If a column contains only
null
values,analyze-tables
will no longer attempt to calculate the most common and least common values for that column. (#547) - Calling
sqlite-utils analyze-tables
with non-existent columns in the-c/--column
option now results in an error message. (#548) - The
table.analyze_column()
method (documented here) now acceptsmost_common=False
andleast_common=False
options for disabling calculation of those values.
3.31
2023-05-08T22:33:57Z
- Dropped support for Python 3.6. Tests now ensure compatibility with Python 3.11. (#517)
- Automatically locates the SpatiaLite extension on Apple Silicon. Thanks, Chris Amico. (#536)
- New
--raw-lines
option for thesqlite-utils query
andsqlite-utils memory
commands, which outputs just the raw value of the first column of evy row. (#539) - Fixed a bug where
table.upsert_all()
failed if thenot_null=
option was passed. (#538) - Fixed a
ResourceWarning
when usingsqlite-utils insert
. (#534) - Now shows a more detailed error message when
sqlite-utils insert
is called with invalid JSON. (#532) table.convert(..., skip_false=False)
andsqlite-utils convert --no-skip-false
options, for avoiding a misfeature where the convert() mechanism skips rows in the database with a falsey value for the specified column. Fixing this by default would be a backwards-incompatible change and is under consideration for a 4.0 release in the future. (#527)- Tables can now be created with self-referential foreign keys. Thanks, Scott Perry. (#537)
sqlite-utils transform
no longer breaks if a table defines default values for columns. Thanks, Kenny Song. (#509)- Fixed a bug where repeated calls to
table.transform()
did not work correctly. Thanks, Martin Carpenter. (#525) - Improved error message if
rows_from_file()
is passed a non-binary-mode file-like object. (#520)
3.30
2022-10-25T22:34:30Z
- Now tested against Python 3.11. (#502)
- New
table.search_sql(include_rank=True)
option, which adds arank
column to the generated SQL. Thanks, Jacob Chapman. (#480) - Progress bars now display for newline-delimited JSON files using the
--nl
option. Thanks, Mischa Untaga. (#485) - New
db.close()
method. (#504) - Conversion functions passed to table.convert(...) can now return lists or dictionaries, which will be inserted into the database as JSON strings. (#495)
sqlite-utils install
andsqlite-utils uninstall
commands for installing packages into the same virtual environment assqlite-utils
, described here. (#483)- New sqlite_utils.utils.flatten() utility function. (#500)
- Documentation on using Just to run tests, linters and build documentation.
- Documentation now covers the Release process for this package.
3.29
2022-08-28T03:48:36Z
- The
sqlite-utils query
,memory
andbulk
commands now all accept a new--functions
option. This can be passed a string of Python code, and any callable objects defined in that code will be made available to SQL queries as custom SQL functions. See Defining custom SQL functions for details. (#471) db[table].create(...)
method now accepts a newtransform=True
parameter. If the table already exists it will be transform to match the schema configuration options passed to the function. This may result in columns being added or dropped, column types being changed, column order being updated or not null and default values for columns being set. (#467)- Related to the above, the
sqlite-utils create-table
command now accepts a--transform
option. - New introspection property:
table.default_values
returns a dictionary mapping each column name with a default value to the configured default value. (#475) - The
--load-extension
option can now be provided a path to a compiled SQLite extension module accompanied by the name of an entrypoint, separated by a colon - for example--load-extension ./lines0:sqlite3_lines0_noread_init
. This feature is modelled on code first contributed to Datasette by Alex Garcia. (#470) - Functions registered using the db.register_function() method can now have a custom name specified using the new
db.register_function(fn, name=...)
parameter. (#458) - sqlite-utils rows has a new
--order
option for specifying the sort order for the returned rows. (#469) - All of the CLI options that accept Python code blocks can now all be used to define functions that can access modules imported in that same block of code without needing to use the
global
keyword. (#472) - Fixed bug where
table.extract()
would not behave correctly for columns containing null values. Thanks, Forest Gregg. (#423) - New tutorial: Cleaning data with sqlite-utils and Datasette shows how to use
sqlite-utils
to import and clean an example CSV file. - Datasette and
sqlite-utils
now have a Discord community. Join the Discord here.
3.28
2022-07-15T22:56:01Z
- New table.duplicate(new_name) method for creating a copy of a table with a matching schema and row contents. Thanks, David. (#449)
- New
sqlite-utils duplicate data.db table_name new_name
CLI command for Duplicating tables. (#454) sqlite_utils.utils.rows_from_file()
is now a documented API. It can be used to read a sequence of dictionaries from a file-like object containing CSV, TSV, JSON or newline-delimited JSON. It can be passed an explicit format or can attempt to detect the format automatically. (#443)sqlite_utils.utils.TypeTracker
is now a documented API for detecting the likely column types for a sequence of string rows, see Detecting column types using TypeTracker. (#445)sqlite_utils.utils.chunks()
is now a documented API for splitting an iterator into chunks. (#451)sqlite-utils enable-fts
now has a--replace
option for replacing the existing FTS configuration for a table. (#450)- The
create-index
,add-column
andduplicate
commands all now take a--ignore
option for ignoring errors should the database not be in the right state for them to operate. (#450)
3.27
2022-06-15T04:30:47Z
See also the annotated release notes for this release.
- Documentation now uses the Furo Sphinx theme. (#435)
- Code examples in documentation now have a "copy to clipboard" button. (#436)
sqlite_utils.utils.utils.rows_from_file()
is now a documented API, see Reading rows from a file. (#443)rows_from_file()
has two new parameters to help handle CSV files with rows that contain more values than are listed in that CSV file's headings:ignore_extras=True
andextras_key="name-of-key"
. (#440)sqlite_utils.utils.maximize_csv_field_size_limit()
helper function for increasing the field size limit for reading CSV files to its maximum, see Setting the maximum CSV field size limit. (#442)table.search(where=, where_args=)
parameters for adding additionalWHERE
clauses to a search query. Thewhere=
parameter is available ontable.search_sql(...)
as well. See Searching with table.search(). (#441)- Fixed bug where
table.detect_fts()
and other search-related functions could fail if two FTS-enabled tables had names that were prefixes of each other. (#434)
3.26.1
2022-05-02T18:17:19Z
-
Now depends on click-default-group-wheel, a pure Python wheel package. This means you can install and use this package with Pyodide, which can run Python entirely in your browser using WebAssembly. (#429)
Try that out using the Pyodide REPL:
>>> import micropip >>> await micropip.install("sqlite-utils") >>> import sqlite_utils >>> db = sqlite_utils.Database(memory=True) >>> list(db.query("select 3 * 5")) [{'3 * 5': 15}]
3.26
2022-04-13T22:51:48Z
- New
errors=r.IGNORE/r.SET_NULL
parameter for ther.parsedatetime()
andr.parsedate()
convert recipes. (#416) - Fixed a bug where
--multi
could not be used in combination with--dry-run
for the convert command. (#415) - New documentation: Using a convert() function to execute initialization. (#420)
- More robust detection for whether or not
deterministic=True
is supported. (#425)
3.25.1
2022-03-11T18:34:44Z
- Improved display of type information and parameters in the API reference documentation. #413
3.25
2022-03-02T06:34:46Z
- New
hash_id_columns=
parameter for creating a primary key that's a hash of the content of specific columns - see Setting an ID based on the hash of the row contents for details. (#343) - New db.sqlite_version property, returning a tuple of integers representing the version of SQLite, for example
(3, 38, 0)
. - Fixed a bug where register_function(deterministic=True) caused errors on versions of SQLite prior to 3.8.3. (#408)
- New documented hash_record(record, keys=...) function.
3.24
2022-02-16T01:39:13Z
- SpatiaLite helpers for the
sqlite-utils
command-line tool - thanks, Chris Amico. (#398)- sqlite-utils create-database
--init-spatialite
option for initializing SpatiaLite on a newly created database. - sqlite-utils add-geometry-column command for adding geometry columns.
- sqlite-utils create-spatial-index command for adding spatial indexes.
- sqlite-utils create-database
db[table].create(..., if_not_exists=True)
option for creating a table only if it does not already exist. (#397)Database(memory_name="my_shared_database")
parameter for creating a named in-memory database that can be shared between multiple connections. (#405)- Documentation now describes how to add a primary key to a rowid table using
sqlite-utils transform
. (#403)
3.23
2022-02-04T06:41:46Z
This release introduces four new utility methods for working with SpatiaLite. Thanks, Chris Amico. (#330)
sqlite_utils.utils.find_spatialite()
finds the location of the SpatiaLite module on disk.db.init_spatialite()
initializes SpatiaLite for the given database.table.add_geometry_column(...)
adds a geometry column to an existing table.table.create_spatial_index(...)
creates a spatial index for a column.sqlite-utils batch
now accepts a--batch-size
option. (#392)
3.22.1
2022-01-26T03:28:30Z
- All commands now include example usage in their
--help
- see CLI reference. (#384) - Python library documentation has a new Getting started section. (#387)
- Documentation now uses Plausible analytics. (#389)
3.22
2022-01-11T23:44:48Z
- New CLI reference documentation page, listing the output of
--help
for every one of the CLI commands. (#383) sqlite-utils rows
now has--limit
and--offset
options for paginating through data. (#381)sqlite-utils rows
now has--where
and-p
options for filtering the table using aWHERE
query, see Returning all rows in a table. (#382)
3.21
2022-01-11T02:34:21Z
CLI and Python library improvements to help run ANALYZE after creating indexes or inserting rows, to gain better performance from the SQLite query planner when it runs against indexes.
Three new CLI commands: create-database
, analyze
and bulk
.
More details and examples can be found in the annotated release notes.
- New
sqlite-utils create-database
command for creating new empty database files. (#348) - New Python methods for running
ANALYZE
against a database, table or index:db.analyze()
andtable.analyze()
, see Optimizing index usage with ANALYZE. (#366) - New sqlite-utils analyze command for running
ANALYZE
using the CLI. (#379) - The
create-index
,insert
andupsert
commands now have a new--analyze
option for runningANALYZE
after the command has completed. (#379) - New sqlite-utils bulk command which can import records in the same way as
sqlite-utils insert
(from JSON, CSV or TSV) and use them to bulk execute a parametrized SQL query. (#375) - The CLI tool can now also be run using
python -m sqlite_utils
. (#368) - Using
--fmt
now implies--table
, so you don't need to pass both options. (#374) - The
--convert
function applied to rows can now modify the row in place. (#371) - The insert-files command supports two new columns:
stem
andsuffix
. (#372) - The
--nl
import option now ignores blank lines in the input. (#376) - Fixed bug where streaming input to the
insert
command with--batch-size 1
would appear to only commit after several rows had been ingested, due to unnecessary input buffering. (#364)
3.20
2022-01-06T06:55:35Z
sqlite-utils insert ... --lines
to insert the lines from a file into a table with a singleline
column, see Inserting unstructured data with --lines and --text.sqlite-utils insert ... --text
to insert the contents of the file into a table with a singletext
column and a single row.sqlite-utils insert ... --convert
allows a Python function to be provided that will be used to convert each row that is being inserted into the database. See Applying conversions while inserting data, including details on special behavior when combined with--lines
and--text
. (#356)sqlite-utils convert
now accepts a code value of-
to read code from standard input. (#353)sqlite-utils convert
also now accepts code that defines a namedconvert(value)
function, see Converting data in columns.db.supports_strict
property showing if the database connection supports SQLite strict tables.table.strict
property (see .strict) indicating if the table uses strict mode. (#344)- Fixed bug where
sqlite-utils upsert ... --detect-types
ignored the--detect-types
option. (#362)
3.19
2021-11-21T04:41:56Z
- The table.lookup() method now accepts keyword arguments that match those on the underlying
table.insert()
method:foreign_keys=
,column_order=
,not_null=
,defaults=
,extracts=
,conversions=
andcolumns=
. You can also now passpk=
to specify a different column name to use for the primary key. (#342)
3.19a0
2021-11-19T07:27:41Z
- Extra keyword arguments for
table.lookup()
which are passed through to.insert()
. #342
3.18
2021-11-15T03:15:23Z
- The
table.lookup()
method now has an optional second argument which can be used to populate columns only the first time the record is created, see Working with lookup tables. (#339) sqlite-utils memory
now has a--flatten
option for flattening nested JSON objects into separate columns, consistent withsqlite-utils insert
. (#332)table.create_index(..., find_unique_name=True)
parameter, which finds an available name for the created index even if the default name has already been taken. This means thatindex-foreign-keys
will work even if one of the indexes it tries to create clashes with an existing index name. (#335)- Added
py.typed
to the module, so mypy should now correctly pick up the type annotations. Thanks, Andreas Longo. (#331) - Now depends on
python-dateutil
instead of depending ondateutils
. Thanks, Denys Pavlov. (#324) table.create()
(see Explicitly creating a table) now handlesdict
,list
andtuple
types, mapping them toTEXT
columns in SQLite so that they can be stored encoded as JSON. (#338)- Inserted data with square braces in the column names (for example a CSV file containing a
item[price]
) column now have the braces converted to underscores:item_price_
. Previously such columns would be rejected with an error. (#329) - Now also tested against Python 3.10. (#330)
3.17.1
2021-09-22T20:49:36Z
- sqlite-utils memory now works if files passed to it share the same file name. (#325)
- sqlite-utils query now returns
[]
in JSON mode if no rows are returned. (#328)
3.17
2021-08-24T23:40:18Z
- The sqlite-utils memory command has a new
--analyze
option, which runs the equivalent of the analyze-tables command directly against the in-memory database created from the incoming CSV or JSON data. (#320) - sqlite-utils insert-files now has the ability to insert file contents in to
TEXT
columns in addition to the defaultBLOB
. Pass the--text
option or usecontent_text
as a column specifier. (#319)
3.16
2021-08-18T22:36:32Z
- Type signatures added to more methods, including
table.resolve_foreign_keys()
,db.create_table_sql()
,db.create_table()
andtable.create()
. (#314) - New
db.quote_fts(value)
method, see Quoting characters for use in search - thanks, Mark Neumann. (#246) table.search()
now accepts an optionalquote=True
parameter. (#296)- CLI command
sqlite-utils search
now accepts a--quote
option. (#296) - Fixed bug where
--no-headers
and--tsv
options to sqlite-utils insert could not be used together. (#295) - Various small improvements to API reference documentation.
3.15.1
2021-08-10T23:55:12Z
- Python library now includes type annotations on almost all of the methods, plus detailed docstrings describing each one. (#311)
- New API Reference documentation page, powered by those docstrings.
- Fixed bug where
.add_foreign_keys()
failed to raise an error if called against aView
. (#313) - Fixed bug where
.delete_where()
returned a[]
instead of returningself
if called against a non-existant table. (#315)
3.15
2021-08-09T22:42:06Z
sqlite-utils insert --flatten
option for flattening nested JSON objects to create tables with column names liketopkey_nestedkey
. (#310)- Fixed several spelling mistakes in the documentation, spotted using codespell.
- Errors that occur while using the
sqlite-utils
CLI tool now show the responsible SQL and query parameters, if possible. (#309)
3.14
2021-08-02T21:29:16Z
This release introduces the new sqlite-utils convert command (#251) and corresponding table.convert(...) Python method (#302). These tools can be used to apply a Python conversion function to one or more columns of a table, either updating the column in place or using transformed data from that column to populate one or more other columns.
This command-line example uses the Python standard library textwrap module to wrap the content of the content
column in the articles
table to 100 characters:
$ sqlite-utils convert content.db articles content\
'"\n".join(textwrap.wrap(value, 100))'\
--import=textwrap
The same operation in Python code looks like this:
import sqlite_utils, textwrap
db = sqlite_utils.Database("content.db")
db["articles"].convert("content", lambda v: "\n".join(textwrap.wrap(v, 100)))
See the full documentation for the sqlite-utils convert command and the table.convert(...) Python method for more details.
Also in this release:
- The new
table.count_where(...)
method, for counting rows in a table that match a specific SQLWHERE
clause. (#305) - New
--silent
option for the sqlite-utils insert-files command to hide the terminal progress bar, consistent with the--silent
option forsqlite-utils convert
. (#301)
3.13
2021-07-24T22:15:27Z
sqlite-utils schema my.db table1 table2
command now accepts optional table names. (#299)sqlite-utils memory --help
now describes the--schema
option.
3.12
2021-06-25T17:59:05Z
- New db.query(sql, params) method, which executes a SQL query and returns the results as an iterator over Python dictionaries. (#290)
- This project now uses
flake8
and has started to usemypy
. (#291) - New documentation on contributing to this project. (#292)
3.11
2021-06-20T18:52:15Z
- New
sqlite-utils memory data.csv --schema
option, for outputting the schema of the in-memory database generated from one or more files. See --schema, --dump and --save. (#288) - Added installation instructions. (#286)
3.10
2021-06-19T16:09:29Z
This release introduces the sqlite-utils memory
command, which can be used to load CSV or JSON data into a temporary in-memory database and run SQL queries (including joins across multiple files) directly against that data.
Also new: sqlite-utils insert --detect-types
, sqlite-utils dump
, table.use_rowid
plus some smaller fixes.
sqlite-utils memory
This example of sqlite-utils memory
retrieves information about the all of the repositories in the Dogsheep organization on GitHub using this JSON API, sorts them by their number of stars and outputs a table of the top five (using -t
):
$ curl -s 'https://api.github.com/users/dogsheep/repos'\
| sqlite-utils memory - '
select full_name, forks_count, stargazers_count
from stdin order by stargazers_count desc limit 5
' -t
full_name forks_count stargazers_count
--------------------------------- ------------- ------------------
dogsheep/twitter-to-sqlite 12 225
dogsheep/github-to-sqlite 14 139
dogsheep/dogsheep-photos 5 116
dogsheep/dogsheep.github.io 7 90
dogsheep/healthkit-to-sqlite 4 85
The tool works against files on disk as well. This example joins data from two CSV files:
$ cat creatures.csv
species_id,name
1,Cleo
2,Bants
2,Dori
2,Azi
$ cat species.csv
id,species_name
1,Dog
2,Chicken
$ sqlite-utils memory species.csv creatures.csv '
select * from creatures join species on creatures.species_id = species.id
'
[{"species_id": 1, "name": "Cleo", "id": 1, "species_name": "Dog"},
{"species_id": 2, "name": "Bants", "id": 2, "species_name": "Chicken"},
{"species_id": 2, "name": "Dori", "id": 2, "species_name": "Chicken"},
{"species_id": 2, "name": "Azi", "id": 2, "species_name": "Chicken"}]
Here the species.csv
file becomes the species
table, the creatures.csv
file becomes the creatures
table and the output is JSON, the default output format.
You can also use the --attach
option to attach existing SQLite database files to the in-memory database, in order to join data from CSV or JSON directly against your existing tables.
Full documentation of this new feature is available in Querying data directly using an in-memory database. (#272)
sqlite-utils insert --detect-types
The sqlite-utils insert command can be used to insert data from JSON, CSV or TSV files into a SQLite database file. The new --detect-types
option (shortcut -d
), when used in conjunction with a CSV or TSV import, will automatically detect if columns in the file are integers or floating point numbers as opposed to treating everything as a text column and create the new table with the corresponding schema. See Inserting CSV or TSV data for details. (#282)
Other changes
- Bug fix:
table.transform()
, when run against a table without explicit primary keys, would incorrectly create a new version of the table with an explicit primary key column calledrowid
. (#284) - New
table.use_rowid
introspection property, see .use_rowid. (#285) - The new
sqlite-utils dump file.db
command outputs a SQL dump that can be used to recreate a database. (#274) -h
now works as a shortcut for--help
, thanks Loren McIntyre. (#276)- Now using pytest-cov and Codecov to track test coverage - currently at 96%. (#275)
- SQL errors that occur when using
sqlite-utils query
are now displayed as CLI errors.
3.9.1
2021-06-13T02:59:08Z
- Fixed bug when using
table.upsert_all()
to create a table with only a single column that is treated as the primary key. (#271)
3.9
2021-06-12T02:07:18Z
- New
sqlite-utils schema
command showing the full SQL schema for a database, see Showing the schema (CLI). (#268) db.schema
introspection property exposing the same feature to the Python library, see Showing the schema (Python library).
3.8
2021-06-03T05:16:33Z
- New
sqlite-utils indexes
command to list indexes in a database, see Listing indexes. (#263) table.xindexes
introspection property returning more details about that table's indexes, see .xindexes. (#261)
3.7
2021-05-29T05:47:59Z
- New
table.pks_and_rows_where()
method returning(primary_key, row_dictionary)
tuples - see Listing rows with their primary keys. (#240) - Fixed bug with table.add_foreign_key() against columns containing spaces. (#238)
table_or_view.drop(ignore=True)
option for avoiding errors if the table or view does not exist. (#237)sqlite-utils drop-view --ignore
andsqlite-utils drop-table --ignore
options. (#237)- Fixed a bug with inserts of nested JSON containing non-ascii strings - thanks, Dylan Wu. (#257)
- Suggest
--alter
if an error occurs caused by a missing column. (#259) - Support creating indexes with columns in descending order, see API documentation and CLI documentation. (#260)
- Correctly handle CSV files that start with a UTF-8 BOM. (#250)
3.6
2021-02-19T05:18:02Z
This release adds the ability to execute queries joining data from more than one database file - similar to the cross database querying feature introduced in Datasette 0.55.
- The
db.attach(alias, filepath)
Python method can be used to attach extra databases to the same connection, see db.attach() in the Python API documentation. (#113) - The
--attach
option attaches extra aliased databases to run SQL queries against directly on the command-line, see attaching additional databases in the CLI documentation. (#236)
3.5
2021-02-14T22:43:06Z
sqlite-utils insert --sniff
option for detecting the delimiter and quote character used by a CSV file, see Alternative delimiters and quote characters. (#230)- The
table.rows_where()
,table.search()
andtable.search_sql()
methods all now take optionaloffset=
andlimit=
arguments. (#231) - New
--no-headers
option forsqlite-utils insert --csv
to handle CSV files that are missing the header row, see CSV files without a header row. (#228) - Fixed bug where inserting data with extra columns in subsequent chunks would throw an error. Thanks @nieuwenhoven for the fix. (#234)
- Fixed bug importing CSV files with columns containing more than 128KB of data. (#229)
- Test suite now runs in CI against Ubuntu, macOS and Windows. Thanks @nieuwenhoven for the Windows test fixes. (#232)
3.4.1
2021-02-06T02:10:04Z
- Fixed a code import bug that slipped in to 3.4. (#226)
3.4
2021-02-06T01:37:27Z
sqlite-utils insert --csv
now accepts optional--delimiter
and--quotechar
options. See Alternative delimiters and quote characters. (#223)
3.3
2021-01-18T04:28:24Z
- The
table.m2m()
method now accepts an optionalalter=True
argument to specify that any missing columns should be added to the referenced table. See Working with many-to-many relationships. (#222)
3.2.1
2021-01-12T23:22:53Z
- Fixed a bug where
.add_missing_columns()
failed to take case insensitive column names into account. (#221)
3.2
2021-01-03T21:15:26Z
This release introduces a new mechanism for speeding up count(*)
queries using cached table counts, stored in a _counts
table and updated by triggers. This mechanism is described in Cached table counts using triggers, and can be enabled using Python API methods or the new enable-counts
CLI command. (#212)
table.enable_counts()
method for enabling these triggers on a specific table.db.enable_counts()
method for enabling triggers on every table in the database. (#213)- New
sqlite-utils enable-counts my.db
command for enabling counts on all or specific tables, see Enabling cached counts. (#214) - New
sqlite-utils triggers
command for listing the triggers defined for a database or specific tables, see Listing triggers. (#218) - New
db.use_counts_table
property which, ifTrue
, causestable.count
to read from the_counts
table. (#215) table.has_counts_triggers
property revealing if a table has been configured with the new_counts
database triggers.db.reset_counts()
method andsqlite-utils reset-counts
command for resetting the values in the_counts
table. (#219)- The previously undocumented
db.escape()
method has been renamed todb.quote()
and is now covered by the documentation: Quoting strings for use in SQL. (#217) - New
table.triggers_dict
anddb.triggers_dict
introspection properties. (#211, #216) sqlite-utils insert
now shows a more useful error message for invalid JSON. (#206)
3.1.1
2021-01-01T23:56:20Z
- Fixed failing test caused by
optimize
sometimes creating larger database files. (#209) - Documentation now lives on https://sqlite-utils.datasette.io/
- README now includes
brew install sqlite-utils
installation method.
3.1
2020-12-13T07:30:59Z
- New command:
sqlite-utils analyze-tables my.db
outputs useful information about the table columns in the database, such as the number of distinct values and how many rows are null. See Analyzing tables for documentation. (#207) - New
table.analyze_column(column)
Python method used by theanalyze-tables
command - see Analyzing a column. - The
table.update()
method now correctly handles values that should be stored as JSON. Thanks, Andreas Madsack. (#204)
3.0
2020-11-08T17:23:38Z
This release introduces a new sqlite-utils search
command for searching tables, see Executing searches. (#192)
The table.search()
method has been redesigned, see Searching with table.search(). (#197)
The release includes minor backwards-incompatible changes, hence the version bump to 3.0. Those changes, which should not affect most users, are:
- The
-c
shortcut option for outputting CSV is no longer available. The full--csv
option is required instead. - The
-f
shortcut for--fmt
has also been removed - use--fmt
. - The
table.search()
method now defaults to sorting by relevance, not sorting byrowid
. (#198) - The
table.search()
method now returns a generator over a list of Python dictionaries. It previously returned a list of tuples.
Also in this release:
- The
query
,tables
,rows
andsearch
CLI commands now accept a new--tsv
option which outputs the results in TSV. (#193) - A new
table.virtual_table_using
property reveals if a table is a virtual table, and returns the upper case type of virtual table (e.g.FTS4
orFTS5
) if it is. It returnsNone
if the table is not a virtual table. (#196) - The new
table.search_sql()
method returns the SQL for searching a table, see Building SQL queries with table.search_sql(). sqlite-utils rows
now accepts multiple optional-c
parameters specifying the columns to return. (#200)
Changes since the 3.0a0 alpha release:
- The
sqlite-utils search
command now defaults to returning every result, unless you add a--limit 20
option. - The
sqlite-utils search -c
andtable.search(columns=[])
options are now fully respected. (#201)
3.0a0
2020-11-07T01:22:24Z
This release introduces a new sqlite-utils search
command for searching tables, see Executing searches. (#192)
The table.search()
method has been redesigned, see Searching with table.search(). (#197)
The release includes minor backwards-incompatible changes, hence the version bump to 3.0. Those changes, which should not affect most users, are:
- The
-c
shortcut option for outputting CSV is no longer available. The full--csv
option is required instead. - The
-f
shortcut for--fmt
has also been removed - use--fmt
. - The
table.search()
method now defaults to sorting by relevance, not sorting byrowid
. (#198) - The
table.search()
method now returns a generator over a list of Python dictionaries. It previously returned a list of tuples.
Also in this release:
- The
query
,tables
,rows
andsearch
CLI commands now accept a new--tsv
option which outputs the results in TSV. (#193) - A new
table.virtual_table_using
property reveals if a table is a virtual table, and returns the upper case type of virtual table (e.g.FTS4
orFTS5
) if it is. It returnsNone
if the table is not a virtual table. (#196) - The new
table.search_sql()
method returns the SQL for searching a table, see Building SQL queries with table.search_sql(). sqlite-utils rows
now accepts multiple optional-c
parameters specifying the columns to return. (#200)
2.23
2020-10-28T21:38:10Z
table.m2m(other_table, records)
method now takes any iterable, not just a list or tuple. Thanks, Adam Wolf. (#189)sqlite-utils insert
now displays a progress bar for CSV or TSV imports. (#173)- New
@db.register_function(deterministic=True)
option for registering deterministic SQLite functions in Python 3.8 or higher. (#191)
2.22
2020-10-16T19:30:25Z
- New
--encoding
option for processing CSV and TSV files that use a non-utf-8 encoding, for both theinsert
andupdate
commands. (#182) - The
--load-extension
option is now available to many more commands. (#137) --load-extension=spatialite
can be used to load SpatiaLite from common installation locations, if it is available. (#136)- Tests now also run against Python 3.9. (#184)
- Passing
pk=["id"]
now has the same effect as passingpk="id"
. (#181)
2.21
2020-09-24T16:44:30Z
table.extract()
andsqlite-utils extract
now apply much, much faster - one example operation reduced from twelve minutes to just four seconds! (#172)sqlite-utils extract
no longer shows a progress bar, because it's fast enough not to need one.- New
column_order=
option fortable.transform()
which can be used to alter the order of columns in a table. (#175) sqlite-utils transform --column-order=
option (with a-o
shortcut) for changing column order. (#176)- The
table.transform(drop_foreign_keys=)
parameter and thesqlite-utils transform --drop-foreign-key
option have changed. They now accept just the name of the column rather than requiring all three of the column, other table and other column. This is technically a backwards-incompatible change but I chose not to bump the major version number because the transform feature is so new. (#177) - The table
.disable_fts()
,.rebuild_fts()
,.delete()
,.delete_where()
and.add_missing_columns()
methods all nowreturn self
, which means they can be chained together with other table operations.
2.20
2020-09-23T00:35:52Z
This release introduces two key new capabilities: transform (#114) and extract (#42).
Transform
SQLite's ALTER TABLE has several documented limitations. The table.transform()
Python method and sqlite-utils transform
CLI command work around these limitations using a pattern where a new table with the desired structure is created, data is copied over to it and the old table is then dropped and replaced by the new one.
You can use these tools to drop columns, change column types, rename columns, add and remove NOT NULL
and defaults, remove foreign key constraints and more. See the transforming tables (CLI) and transforming tables (Python library) documentation for full details of how to use them.
Extract
Sometimes a database table - especially one imported from a CSV file - will contain duplicate data. A Trees
table may include a Species
column with only a few dozen unique values, when the table itself contains thousands of rows.
The table.extract()
method and sqlite-utils extract
commands can extract a column - or multiple columns - out into a separate lookup table, and set up a foreign key relationship from the original table.
The Python library extract() documentation describes how extraction works in detail, and Extracting columns into a separate table in the CLI documentation includes a detailed example.
Other changes
- The
@db.register_function
decorator can be used to quickly register Python functions as custom SQL functions, see Registering custom SQL functions. (#162) - The
table.rows_where()
method now accepts an optionalselect=
argument for specifying which columns should be selected, see Listing rows.
2.19
2020-09-20T22:22:56Z
- New
sqlite-utils add-foreign-keys
command for Adding multiple foreign keys at once. (#157) - New
table.enable_fts(..., replace=True)
argument for replacing an existing FTS table with a new configuration. (#160) - New
table.add_foreign_key(..., ignore=True)
argument for ignoring a foreign key if it already exists. (#112)
2.18
2020-09-08T23:37:28Z
table.rebuild_fts()
method for rebuilding a FTS index, see Rebuilding a full-text search table. (#155)sqlite-utils rebuild-fts data.db
command for rebuilding FTS indexes across all tables, or just specific tables. (#155)table.optimize()
method no longer deletes junk rows from the*_fts_docsize
table. This was added in 2.17 but it turns out runningtable.rebuild_fts()
is a better solution to this problem.- Fixed a bug where rows with additional columns that are inserted after the first batch of records could cause an error due to breaking SQLite's maximum number of parameters. Thanks, Simon Wiles. (#145)
2.17
2020-09-07T22:08:12Z
This release handles a bug where replacing rows in FTS tables could result in growing numbers of unneccessary rows in the associated *_fts_docsize
table. (#149)
PRAGMA recursive_triggers=on
by default for all connections. You can turn it off withDatabase(recursive_triggers=False)
. (#152)table.optimize()
method now deletes unnecessary rows from the*_fts_docsize
table. (#153)- New tracer method for tracking underlying SQL queries, see Tracing queries. (#150)
- Neater indentation for schema SQL. (#148)
- Documentation for
sqlite_utils.AlterError
exception thrown by inadd_foreign_keys()
.
2.16.1
2020-08-28T22:45:11Z
insert_all(..., alter=True)
now works for columns introduced after the first 100 records. Thanks, Simon Wiles! (#139)- Continuous Integration is now powered by GitHub Actions. (#143)
2.16
2020-08-21T21:02:29Z
--load-extension
option forsqlite-utils query
for loading SQLite extensions. (#134)- New
sqlite_utils.utils.find_spatialite()
function for finding SpatiaLite in common locations. (#135)
2.15.1
2020-08-12T16:59:48Z
- Now available as a
sdist
package on PyPI in addition to a wheel. (#133)
2.15
2020-08-10T19:06:02Z
- New
db.enable_wal()
anddb.disable_wal()
methods for enabling and disabling Write-Ahead Logging for a database file - see WAL mode in the Python API documentation. - Also
sqlite-utils enable-wal file.db
andsqlite-utils disable-wal file.db
commands for doing the same thing on the command-line, see WAL mode (CLI). (#132)
2.14.1
2020-08-06T06:31:11Z
- Documentation improvements
2.14
2020-08-01T20:58:47Z
- The insert-files command can now read from standard input:
cat dog.jpg | sqlite-utils insert-files dogs.db pics - --name=dog.jpg
. (#127) - You can now specify a full-text search tokenizer using the new
tokenize=
parameter to enable_fts(). This means you can enable Porter stemming on a table by runningdb["articles"].enable_fts(["headline", "body"], tokenize="porter")
. (#130) - You can also set a custom tokenizer using the sqlite-utils enable-fts CLI command, via the new
--tokenize
option.
2.13
2020-07-30T01:13:53Z
memoryview
anduuid.UUID
objects are now supported.memoryview
objects will be stored usingBLOB
anduuid.UUID
objects will be stored usingTEXT
. (#128)
2.12
2020-07-27T07:21:26Z
The theme of this release is better tools for working with binary data. The new insert-files
command can be used to insert binary files directly into a database table, and other commands have been improved with better support for BLOB columns.
sqlite-utils insert-files my.db gifs *.gif
can now insert the contents of files into a specified table. The columns in the table can be customized to include different pieces of metadata derived from the files. See Inserting binary data from files. (#122)--raw
option tosqlite-utils query
- for outputting just a single raw column value - see Returning raw data from a query, such as binary content. (#123)- JSON output now encodes BLOB values as special base64 obects - see Running queries and returning JSON. (#125)
- The same format of JSON base64 objects can now be used to insert binary data - see Inserting JSON data. (#126)
- The
sqlite-utils query
command can now accept named parameters, e.g.sqlite-utils :memory: "select :num * :num2" -p num 5 -p num2 6
- see Running queries and returning JSON. (#124)
2.11
2020-07-08T17:36:07Z
- New
--truncate
option tosqlite-utils insert
, andtruncate=True
argument to.insert_all()
. Thanks, Thomas Sibley. (#118) - The
sqlite-utils query
command now runs updates in a transaction. Thanks, Thomas Sibley. (#120)
2.10.1
2020-06-23T21:04:07Z
- Added documentation for the
table.pks
introspection property. #116
2.10
2020-06-12T17:43:45Z
- The
sqlite-utils
command now supports UPDATE/INSERT/DELETE in addition to SELECT. #115
2.9.1
2020-05-11T19:20:29Z
- Added custom project links to the PyPI listing.
2.9
2020-05-11T01:54:56Z
- New
sqlite-utils drop-table
command, see Dropping tables. (#111) - New
sqlite-utils drop-view
command, see Dropping views. - Python
decimal.Decimal
objects are now stored asFLOAT
. (#110)
2.8
2020-05-03T15:39:56Z
- New
sqlite-utils create-table
command, see Creating tables. (#27) - New
sqlite-utils create-view
command, see Creating views. (#107)
2.7.2
2020-05-02T16:05:27Z
db.create_view(...)
now has additional parametersignore=True
orreplace=True
, see Creating views. (#106)
2.7.1
2020-05-01T22:08:37Z
- New
sqlite-utils views my.db
command for listing views in a database, see Listing views. (#105) sqlite-utils tables
(andviews
) has a new--schema
option which outputs the table/view schema, see Listing tables. (#104)- Nested structures containing invalid JSON values (e.g. Python bytestrings) are now serialized using
repr()
instead of throwing an error. (#102)
2.7
2020-04-18T00:04:50Z
- New
columns=
argument for the.insert()
,.insert_all()
,.upsert()
and.upsert_all()
methods, for over-riding the auto-detected types for columns and specifying additional columns that should be added when the table is created. See Custom column order and column types. (#100)
2.6
2020-04-16T03:13:13Z
- New
table.rows_where(..., order_by="age desc")
argument, see Listing rows. (#76)
2.5
2020-04-13T03:52:19Z
- Panda’s Timestamp is now stored as a SQLite TEXT column. Thanks, b0b5h4rp13! (#96)
table.last_pk
is now only available for inserts or upserts of a single record. (#98)- New
Database(filepath, recreate=True)
parameter for deleting and recreating the database. (#97)
2.4.4
2020-03-23T20:32:09Z
- Fixed bug where columns with only null values were not correctly created. (#95)
2.4.3
2020-03-23T19:58:55Z
- Column type suggestion code is no longer confused by null values. (#94)
2.4.2
2020-03-14T20:09:56Z
table.column_dicts
now works with all column types - previously it would throw errors on types other thanTEXT
,BLOB
,INTEGER
orFLOAT
. (#92)- Documentation for
NotFoundError
thrown bytable.get(pk)
- see Retrieving a specific record.
2.4.1
2020-03-02T06:12:21Z
table.enable_fts()
now works with columns that contain spaces. (#90)
2.4
2020-02-27T04:55:58Z
table.disable_fts()
can now be used to remove FTS tables and triggers that were created usingtable.enable_fts(...)
. (#88)- The
sqlite-utils disable-fts
command can be used to remove FTS tables and triggers from the command-line. (#88) - Trying to create table columns with square braces ([ or ]) in the name now raises an error. (#86)
- Subclasses of
dict
,list
andtuple
are now detected as needing a JSON column. (#87)
2.3.1
2020-02-11T05:52:23Z
table.create_index()
now works for columns that contain spaces. (#85)
2.3
2020-02-08T23:56:16Z
table.exists()
is now a method, not a property. This was not a documented part of the API before so I’m considering this a non-breaking change. (#83)
2.2.1
2020-02-07T07:20:03Z
Fixed a bug where .upsert(..., hash_id="pk")
threw an error (#84).
2.2
2020-02-01T21:59:08Z
New feature: sqlite_utils.suggest_column_types([records])
returns the suggested column types for a list of records. See Suggesting column types. (#81).
This replaces the undocumented table.detect_column_types()
method.
2.1
2020-01-31T00:25:20Z
New feature: conversions={...}
can be passed to the .insert()
family of functions to specify SQL conversions that should be applied to values that are being inserted or updated. See Converting column values using SQL functions. (#77).
2.0.1
2020-01-05T17:23:02Z
The .upsert()
and .upsert_all()
methods now raise a sqlite_utils.db.PrimaryKeyRequired
exception if you call them without specifying the primary key column using pk=
(#73).
2.0
2019-12-30T06:18:58Z
This release changes the behaviour of upsert
. It’s a breaking change, hence 2.0.
The upsert
command-line utility and the .upsert()
and .upsert_all()
Python API methods have had their behaviour altered. They used to completely replace the affected records: now, they update the specified values on existing records but leave other columns unaffected.
See Upserting data using the Python API and Upserting data using the CLI for full details.
If you want the old behaviour - where records were completely replaced - you can use $ sqlite-utils insert ... --replace
on the command-line and .insert(..., replace=True)
and .insert_all(..., replace=True)
in the Python API. See Insert-replacing data using the Python API and Insert-replacing data using the CLI for more.
For full background on this change, see issue #66.
1.12.1
2019-11-07T04:58:47Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-12-1
1.12
2019-11-04T16:28:52Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-12
1.11
2019-09-03T00:58:41Z
https://sqlite-utils.readthedocs.io/en/stable/changelog.html#v1-11
1.10
2019-08-23T12:24:04Z
https://sqlite-utils.readthedocs.io/en/stable/changelog.html#v1-10
1.9
2019-08-04T03:35:30Z
https://sqlite-utils.readthedocs.io/en/stable/changelog.html#v1-9
1.8
2019-07-28T15:41:42Z
https://sqlite-utils.readthedocs.io/en/stable/changelog.html#v1-8
1.7.1
2019-07-28T12:00:51Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-7-1
1.7
2019-07-24T06:50:41Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-7
1.6
2019-07-19T04:51:21Z
sqlite-utils insert
can now accept TSV data via the new--tsv
option (#41)
1.3
2019-06-29T06:32:36Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-3
1.2.2
2019-06-26T04:20:55Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-2-2
1.2.1
2019-06-21T00:01:24Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-2-1
1.2
2019-06-13T06:39:59Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-2
1.1
2019-05-29T05:12:03Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-1
- Support for
ignore=True
/--ignore
for ignoring inserted records if the primary key alread exists (#21) - Ability to add a column that is a foreign key reference using
fk=...
/--fk
(#16)
1.0.1
2019-05-28T00:50:28Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-0-1
1.0
2019-05-25T01:06:38Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v1-0
0.14
2019-02-24T23:11:51Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-14
0.13
2019-02-24T06:54:43Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-13
0.12
2019-02-23T02:22:28Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-12
0.11
2019-02-08T05:23:50Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-11
0.10
2019-02-07T05:17:52Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-10
0.9
2019-01-28T06:34:33Z
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-9
0.8
2019-01-26T02:13:29Z
Two new commands: sqlite-utils csv
and sqlite-utils json
https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-8
0.7
2019-01-25T07:20:49Z
Release notes are here: https://sqlite-utils.readthedocs.io/en/latest/changelog.html#v0-7