- New :ref:`db.query(sql, params) <python_api_query>` 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 :ref:`contributing <contributing>` to this project. (#292)
- New
sqlite-utils memory data.csv --schema
option, for outputting the schema of the in-memory database generated from one or more files. See :ref:`cli_memory_schema_dump_save`. (#288) - Added :ref:`installation instructions <installation>`. (#286)
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.
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 :ref:`cli_memory`. (#272)
The :ref:`sqlite-utils insert <cli_inserting_data>` 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 :ref:`cli_insert_csv_tsv` for details. (#282)
- 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 :ref:`python_api_introspection_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.
- Fixed bug when using
table.upsert_all()
to create a table with only a single column that is treated as the primary key. (#271)
- New
sqlite-utils schema
command showing the full SQL schema for a database, see :ref:`Showing the schema (CLI)<cli_schema>`. (#268) db.schema
introspection property exposing the same feature to the Python library, see :ref:`Showing the schema (Python library) <python_api_schema>`.
- New
sqlite-utils indexes
command to list indexes in a database, see :ref:`cli_indexes`. (#263) table.xindexes
introspection property returning more details about that table's indexes, see :ref:`python_api_introspection_xindexes`. (#261)
- New
table.pks_and_rows_where()
method returning(primary_key, row_dictionary)
tuples - see :ref:`python_api_pks_and_rows_where`. (#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 :ref:`API documentation <python_api_create_index>` and :ref:`CLI documentation <cli_create_index>`. (#260)
- Correctly handle CSV files that start with a UTF-8 BOM. (#250)
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 :ref:`db.attach() in the Python API documentation <python_api_attach>`. (#113) - The
--attach
option attaches extra aliased databases to run SQL queries against directly on the command-line, see :ref:`attaching additional databases in the CLI documentation <cli_query_attach>`. (#236)
sqlite-utils insert --sniff
option for detecting the delimiter and quote character used by a CSV file, see :ref:`cli_insert_csv_tsv_delimiter`. (#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 :ref:`cli_insert_csv_tsv_no_header`. (#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)
- Fixed a code import bug that slipped in to 3.4. (#226)
sqlite-utils insert --csv
now accepts optional--delimiter
and--quotechar
options. See :ref:`cli_insert_csv_tsv_delimiter`. (#223)
- The
table.m2m()
method now accepts an optionalalter=True
argument to specify that any missing columns should be added to the referenced table. See :ref:`python_api_m2m`. (#222)
- Fixed a bug where
.add_missing_columns()
failed to take case insensitive column names into account. (#221)
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 :ref:`python_api_cached_table_counts`, 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 :ref:`cli_enable_counts`. (#214) - New
sqlite-utils triggers
command for listing the triggers defined for a database or specific tables, see :ref:`cli_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: :ref:`python_api_quote`. (#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)
- 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.
- 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 :ref:`cli_analyze_tables` for documentation. (#207) - New
table.analyze_column(column)
Python method used by theanalyze-tables
command - see :ref:`python_api_analyze_column`. - The
table.update()
method now correctly handles values that should be stored as JSON. Thanks, Andreas Madsack. (#204)
This release introduces a new sqlite-utils search
command for searching tables, see :ref:`cli_search`. (#192)
The table.search()
method has been redesigned, see :ref:`python_api_fts_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 :ref:`python_api_fts_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)
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)
- 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)
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.
This release introduces two key new capabilities: transform (#114) and extract (#42).
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 change column types, rename columns, drop columns, add and remove NOT NULL
and defaults, remove foreign key constraints and more. See the :ref:`transforming tables (CLI) <cli_transform_table>` and :ref:`transforming tables (Python library) <python_api_transform>` documentation for full details of how to use them.
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 :ref:`extract() documentation <python_api_extract>` describes how extraction works in detail, and :ref:`cli_extract` in the CLI documentation includes a detailed example.
- The
@db.register_function
decorator can be used to quickly register Python functions as custom SQL functions, see :ref:`python_api_register_function`. (#162) - The
table.rows_where()
method now accepts an optionalselect=
argument for specifying which columns should be selected, see :ref:`python_api_rows`.
- New
sqlite-utils add-foreign-keys
command for :ref:`cli_add_foreign_keys`. (#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)
table.rebuild_fts()
method for rebuilding a FTS index, see :ref:`python_api_fts_rebuild`. (#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)
This release handles a bug where replacing rows in FTS tables could result in growing numbers of unnecessary 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 :ref:`python_api_tracing`. (#150)
- Neater indentation for schema SQL. (#148)
- Documentation for
sqlite_utils.AlterError
exception thrown by inadd_foreign_keys()
.
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)
--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)
- Now available as a
sdist
package on PyPI in addition to a wheel. (#133)
- New
db.enable_wal()
anddb.disable_wal()
methods for enabling and disabling Write-Ahead Logging for a database file - see :ref:`python_api_wal` 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 :ref:`WAL mode (CLI) <cli_wal>`. (#132)
- Documentation improvements.
- The :ref:`insert-files command <cli_insert_files>` 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 :ref:`enable_fts() <python_api_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 :ref:`sqlite-utils enable-fts <cli_fts>` CLI command, via the new
--tokenize
option.
memoryview
anduuid.UUID
objects are now supported.memoryview
objects will be stored usingBLOB
anduuid.UUID
objects will be stored usingTEXT
. (#128)
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 :ref:`cli_insert_files`. (#122)--raw
option tosqlite-utils query
- for outputting just a single raw column value - see :ref:`cli_query_raw`. (#123)- JSON output now encodes BLOB values as special base64 objects - see :ref:`cli_query_json`. (#125)
- The same format of JSON base64 objects can now be used to insert binary data - see :ref:`cli_inserting_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 :ref:`cli_query_json`. (#124)
- 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)
- Added documentation for the
table.pks
introspection property. (#116)
- The
sqlite-utils
command now supports UPDATE/INSERT/DELETE in addition to SELECT. (#115)
- Added custom project links to the PyPI listing.
- New
sqlite-utils drop-table
command, see :ref:`cli_drop_table`. (#111) - New
sqlite-utils drop-view
command, see :ref:`cli_drop_view`. - Python
decimal.Decimal
objects are now stored asFLOAT
. (#110)
- New
sqlite-utils create-table
command, see :ref:`cli_create_table`. (#27) - New
sqlite-utils create-view
command, see :ref:`cli_create_view`. (#107)
db.create_view(...)
now has additional parametersignore=True
orreplace=True
, see :ref:`python_api_create_view`. (#106)
- New
sqlite-utils views my.db
command for listing views in a database, see :ref:`cli_views`. (#105) sqlite-utils tables
(andviews
) has a new--schema
option which outputs the table/view schema, see :ref:`cli_tables`. (#104)- Nested structures containing invalid JSON values (e.g. Python bytestrings) are now serialized using
repr()
instead of throwing an error. (#102)
- 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 :ref:`python_api_custom_columns`. (#100)
- New
table.rows_where(..., order_by="age desc")
argument, see :ref:`python_api_rows`. (#76)
- 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)
- Fixed bug where columns with only null values were not correctly created. (#95)
- Column type suggestion code is no longer confused by null values. (#94)
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 :ref:`python_api_get`.
table.enable_fts()
now works with columns that contain spaces. (#90)
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)
table.create_index()
now works for columns that contain spaces. (#85)
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)
Fixed a bug where .upsert(..., hash_id="pk")
threw an error (#84).
New feature: sqlite_utils.suggest_column_types([records])
returns the suggested column types for a list of records. See :ref:`python_api_suggest_column_types`. (#81).
This replaces the undocumented table.detect_column_types()
method.
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 :ref:`python_api_conversions` . (#77).
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).
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 :ref:`Upserting data using the Python API <python_api_upsert>` and :ref:`Upserting data using the CLI <cli_upsert>` 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 :ref:`Insert-replacing data using the Python API <python_api_insert_replace>` and :ref:`Insert-replacing data using the CLI <cli_insert_replace>` for more.
For full background on this change, see issue #66.
- Fixed error thrown when
.insert_all()
and.upsert_all()
were called with empty lists (#52)
Python library utilities for deleting records (#62)
db["tablename"].delete(4)
to delete by primary key, see :ref:`python_api_delete`db["tablename"].delete_where("id > ?", [3])
to delete by a where clause, see :ref:`python_api_delete_where`
Option to create triggers to automatically keep FTS tables up-to-date with newly inserted, updated and deleted records. Thanks, Amjith Ramanujam! (#57)
sqlite-utils enable-fts ... --create-triggers
- see :ref:`Configuring full-text search using the CLI <cli_fts>`db["tablename"].enable_fts(..., create_triggers=True)
- see :ref:`Configuring full-text search using the Python library <python_api_fts>`- Support for introspecting triggers for a database or table - see :ref:`python_api_introspection` (#59)
Ability to introspect and run queries against views (#54)
db.view_names()
method and anddb.views
property- Separate
View
andTable
classes, both subclassing newQueryable
class view.drop()
method
table.m2m(...)
method for creating many-to-many relationships: :ref:`python_api_m2m` (#23)
table.update(pk, values)
method: :ref:`python_api_update` (#35)
- Fixed bug where inserting records with 11 columns in a batch of 100 triggered a "too many SQL variables" error (#50)
- Documentation and tests for
table.drop()
method: :ref:`python_api_drop`
Support for lookup tables.
- New
table.lookup({...})
utility method for building and querying lookup tables - see :ref:`python_api_lookup_tables` (#44) - New
extracts=
table configuration option, see :ref:`python_api_extracts` (#46) - Use pysqlite3 if it is available, otherwise use
sqlite3
from the standard library - Table options can now be passed to the new
db.table(name, **options)
factory function in addition to being passed toinsert_all(records, **options)
and friends - see :ref:`python_api_table_configuration` - In-memory databases can now be created using
db = Database(memory=True)
sqlite-utils insert
can now accept TSV data via the new--tsv
option (#41)
- Support for compound primary keys (#36)
- Configure these using the CLI tool by passing
--pk
multiple times - In Python, pass a tuple of columns to the
pk=(..., ...)
argument: :ref:`python_api_compound_primary_keys`
- Configure these using the CLI tool by passing
- New
table.get()
method for retrieving a record by its primary key: :ref:`python_api_get` (#39)
- Assorted minor documentation fixes: changes since 1.4
- Added
sqlite-utils index-foreign-keys
command (:ref:`docs <cli_index_foreign_keys>`) anddb.index_foreign_keys()
method (:ref:`docs <python_api_index_foreign_keys>`) (#33)
- New mechanism for adding multiple foreign key constraints at once: :ref:`db.add_foreign_keys() documentation <python_api_add_foreign_keys>` (#31)
- Fixed bug where
datetime.time
was not being handled correctly
- Check the column exists before attempting to add a foreign key (#29)
- Improved foreign key definitions: you no longer need to specify the
column
,other_table
ANDother_column
to define a foreign key - if you omit theother_table
orother_column
the script will attempt to guess the correct values by introspecting the database. See :ref:`python_api_add_foreign_key` for details. (#25) - Ability to set
NOT NULL
constraints andDEFAULT
values when creating tables (#24). Documentation: :ref:`Setting defaults and not null constraints (Python API) <python_api_defaults_not_null>`, :ref:`Setting defaults and not null constraints (CLI) <cli_defaults_not_null>` - Support for
not_null_default=X
/--not-null-default
for setting aNOT NULL DEFAULT 'x'
when adding a new column. Documentation: :ref:`Adding columns (Python API) <python_api_add_column>`, :ref:`Adding columns (CLI) <cli_add_column>`
- Support for
ignore=True
/--ignore
for ignoring inserted records if the primary key already exists (#21) - documentation: :ref:`Inserting data (Python API) <python_api_bulk_inserts>`, :ref:`Inserting data (CLI) <cli_inserting_data>` - Ability to add a column that is a foreign key reference using
fk=...
/--fk
(#16) - documentation: :ref:`Adding columns (Python API) <python_api_add_column>`, :ref:`Adding columns (CLI) <cli_add_column>`
sqlite-utils rows data.db table --json-cols
- fixed bug where--json-cols
was not obeyed
- Option to automatically add new columns if you attempt to insert or upsert data with extra fields:
sqlite-utils insert ... --alter
- see :ref:`Adding columns automatically with the sqlite-utils CLI <cli_add_column_alter>`db["tablename"].insert(record, alter=True)
- see :ref:`Adding columns automatically using the Python API <python_api_add_column_alter>`
New
--json-cols
option for outputting nested JSON, see :ref:`cli_json_values`
- Ability to create unique indexes:
db["mytable"].create_index(["name"], unique=True)
db["mytable"].create_index(["name"], if_not_exists=True)
$ sqlite-utils create-index mydb.db mytable col1 [col2...]
, see :ref:`cli_create_index`table.add_column(name, type)
method, see :ref:`python_api_add_column`$ sqlite-utils add-column mydb.db mytable nameofcolumn
, see :ref:`cli_add_column` (CLI)db["books"].add_foreign_key("author_id", "authors", "id")
, see :ref:`python_api_add_foreign_key`$ sqlite-utils add-foreign-key books.db books author_id authors id
, see :ref:`cli_add_foreign_key` (CLI)- Improved (but backwards-incompatible)
foreign_keys=
argument to various methods, see :ref:`python_api_foreign_keys`
- New
--table
and--fmt
options can be used to output query results in a variety of visual table formats, see :ref:`cli_query_table` - New
hash_id=
argument can now be used for :ref:`python_api_hash` - Can now derive correct column types for numpy int, uint and float values
table.last_id
has been renamed totable.last_rowid
table.last_pk
now contains the last inserted primary key, ifpk=
was specified- Prettier indentation in the
CREATE TABLE
generated schemas
- Added
db[table].rows
iterator - see :ref:`python_api_rows` - Replaced
sqlite-utils json
andsqlite-utils csv
with a new default subcommand calledsqlite-utils query
which defaults to JSON and takes formatting options--nl
,--csv
and--no-headers
- see :ref:`cli_query_json` and :ref:`cli_query_csv` - New
sqlite-utils rows data.db name-of-table
command, see :ref:`cli_rows` sqlite-utils table
command now takes options--counts
and--columns
plus the standard output format options, see :ref:`cli_tables`
New commands for enabling FTS against a table and columns:
sqlite-utils enable-fts db.db mytable col1 col2
See :ref:`cli_fts`.
Handle datetime.date
and datetime.time
values.
New option for efficiently inserting rows from a CSV:
sqlite-utils insert db.db foo - --csv
Improved support for newline-delimited JSON.
sqlite-utils insert
has two new command-line options:
--nl
means "expect newline-delimited JSON". This is an extremely efficient way of loading in large amounts of data, especially if you pipe it into standard input.--batch-size=1000
lets you increase the batch size (default is 100). A commit will be issued every X records. This also control how many initial records are considered when detecting the desired SQL table schema for the data.
In the Python API, the table.insert_all(...)
method can now accept a generator as well as a list of objects. This will be efficiently used to populate the table no matter how many records are produced by the generator.
The Database()
constructor can now accept a pathlib.Path
object in addition to a string or an existing SQLite connection object.
Two new commands: sqlite-utils csv
and sqlite-utils json
These commands execute a SQL query and return the results as CSV or JSON. See :ref:`cli_query_csv` and :ref:`cli_query_json` for more details.
$ sqlite-utils json --help Usage: sqlite-utils json [OPTIONS] PATH SQL Execute SQL query and return the results as JSON Options: --nl Output newline-delimited JSON --arrays Output rows as arrays instead of objects --help Show this message and exit. $ sqlite-utils csv --help Usage: sqlite-utils csv [OPTIONS] PATH SQL Execute SQL query and return the results as CSV Options: --no-headers Exclude headers from CSV output --help Show this message and exit.
This release implements the sqlite-utils
command-line tool with a number of useful subcommands.
sqlite-utils tables demo.db
lists the tables in the databasesqlite-utils tables demo.db --fts4
shows just the FTS4 tablessqlite-utils tables demo.db --fts5
shows just the FTS5 tablessqlite-utils vacuum demo.db
runs VACUUM against the databasesqlite-utils optimize demo.db
runs OPTIMIZE against all FTS tables, then VACUUMsqlite-utils optimize demo.db --no-vacuum
runs OPTIMIZE but skips VACUUM
The two most useful subcommands are upsert
and insert
, which allow you to ingest JSON files with one or more records in them, creating the corresponding table with the correct columns if it does not already exist. See :ref:`cli_inserting_data` for more details.
sqlite-utils insert demo.db dogs dogs.json --pk=id
inserts new records fromdogs.json
into thedogs
tablesqlite-utils upsert demo.db dogs dogs.json --pk=id
upserts records, replacing any records with duplicate primary keys
One backwards incompatible change: the db["table"].table_names
property is now a method:
db["table"].table_names()
returns a list of table namesdb["table"].table_names(fts4=True)
returns a list of just the FTS4 tablesdb["table"].table_names(fts5=True)
returns a list of just the FTS5 tables
A few other changes:
- Plenty of updated documentation, including full coverage of the new command-line tool
- Allow column names to be reserved words (use correct SQL escaping)
- Added automatic column support for bytes and datetime.datetime
.enable_fts()
now takes optional argumentfts_version
, defaults toFTS5
. UseFTS4
if the version of SQLite bundled with your Python does not support FTS5- New optional
column_order=
argument to.insert()
and friends for providing a partial or full desired order of the columns when a database table is created - :ref:`New documentation <python_api>` for
.insert_all()
and.upsert()
and.upsert_all()
db.tables
anddb.table_names
introspection propertiesdb.indexes
property for introspecting indexestable.create_index(columns, index_name)
methoddb.create_view(name, sql)
method- Table methods can now be chained, plus added
table.last_id
for accessing the last inserted row ID
enable_fts()
,populate_fts()
andsearch()
table methods