diff --git a/docs/cli.rst b/docs/cli.rst index 8f65f45e..2e506ddb 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -424,6 +424,9 @@ The ``--functions`` option can be used multiple times to load functions from mul from urllib.parse import urlparse return urlparse(url).path' +.. note:: + In Python: :ref:`db.register_function() ` + .. _cli_query_extensions: SQLite extensions @@ -1024,6 +1027,9 @@ To show more than 10 common values, use ``--common-limit 20``. To skip the most sqlite-utils analyze-tables github.db tags --common-limit 20 --no-least +.. note:: + In Python: :ref:`table.analyze_column() ` CLI reference: :ref:`sqlite-utils analyze-tables ` + .. _cli_analyze_tables_save: Saving the analyzed table details @@ -1191,6 +1197,9 @@ You can delete all the existing rows in the table before inserting the new recor You can add the ``--analyze`` option to run ``ANALYZE`` against the table after the rows have been inserted. +.. note:: + In Python: :ref:`table.insert_all() ` CLI reference: :ref:`sqlite-utils insert ` + .. _cli_inserting_data_binary: Inserting binary data @@ -1615,6 +1624,9 @@ To replace a dog with in ID of 2 with a new record, run the following: echo '{"id": 2, "name": "Pancakes", "age": 3}' | \ sqlite-utils insert dogs.db dogs - --pk=id --replace +.. note:: + In Python: :ref:`table.insert(..., replace=True) ` CLI reference: :ref:`sqlite-utils insert ` + .. _cli_upsert: Upserting data @@ -1641,6 +1653,9 @@ The command will fail if you reference columns that do not exist on the table. T ``upsert`` in sqlite-utils 1.x worked like ``insert ... --replace`` does in 2.x. See `issue #66 `__ for details of this change. +.. note:: + In Python: :ref:`table.upsert() ` CLI reference: :ref:`sqlite-utils upsert ` + .. _cli_bulk: Executing SQL in bulk @@ -1842,6 +1857,9 @@ You can include named parameters in your where clause and populate them using on The ``--dry-run`` option will output a preview of the conversion against the first ten rows, without modifying the database. +.. note:: + In Python: :ref:`table.convert() ` CLI reference: :ref:`sqlite-utils convert ` + .. _cli_convert_import: Importing additional modules @@ -2140,6 +2158,9 @@ If a table with the same name already exists, you will get an error. You can cho You can also pass ``--transform`` to transform the existing table to match the new schema. See :ref:`python_api_explicit_create` in the Python library documentation for details of how this option works. +.. note:: + In Python: :ref:`table.create() ` CLI reference: :ref:`sqlite-utils create-table ` + .. _cli_renaming_tables: Renaming a table @@ -2153,6 +2174,9 @@ Yo ucan rename a table using the ``rename-table`` command: Pass ``--ignore`` to ignore any errors caused by the table not existing, or the new name already being in use. +.. note:: + In Python: :ref:`db.rename_table() ` CLI reference: :ref:`sqlite-utils rename-table ` + .. _cli_duplicate_table: Duplicating tables @@ -2164,6 +2188,9 @@ The ``duplicate`` command duplicates a table - creating a new table with the sam sqlite-utils duplicate books.db authors authors_copy +.. note:: + In Python: :ref:`table.duplicate() ` CLI reference: :ref:`sqlite-utils duplicate ` + .. _cli_drop_table: Dropping tables @@ -2177,6 +2204,9 @@ You can drop a table using the ``drop-table`` command: Use ``--ignore`` to ignore the error if the table does not exist. +.. note:: + In Python: :ref:`table.drop() ` CLI reference: :ref:`sqlite-utils drop-table ` + .. _cli_transform_table: Transforming tables @@ -2260,6 +2290,9 @@ If you want to see the SQL that will be executed to make the change without actu DROP TABLE "roadside_attractions"; ALTER TABLE "roadside_attractions_new_4033a60276b9" RENAME TO "roadside_attractions"; +.. note:: + In Python: :ref:`table.transform() ` CLI reference: :ref:`sqlite-utils transform ` + .. _cli_transform_table_add_primary_key_to_rowid: Adding a primary key to a rowid table @@ -2437,6 +2470,9 @@ After running the above, the command ``sqlite-utils schema global.db`` reveals t CREATE UNIQUE INDEX "idx_countries_country_name" ON "countries" ("country", "name"); +.. note:: + In Python: :ref:`table.extract() ` CLI reference: :ref:`sqlite-utils extract ` + .. _cli_create_view: Creating views @@ -2458,6 +2494,9 @@ You can create a view using the ``create-view`` command: Use ``--replace`` to replace an existing view of the same name, and ``--ignore`` to do nothing if a view already exists. +.. note:: + In Python: :ref:`db.create_view() ` CLI reference: :ref:`sqlite-utils create-view ` + .. _cli_drop_view: Dropping views @@ -2471,6 +2510,9 @@ You can drop a view using the ``drop-view`` command: Use ``--ignore`` to ignore the error if the view does not exist. +.. note:: + In Python: :ref:`view.drop() ` CLI reference: :ref:`sqlite-utils drop-view ` + .. _cli_add_column: Adding columns @@ -2511,6 +2553,9 @@ You can set a ``NOT NULL DEFAULT 'x'`` constraint on the new column using ``--no sqlite-utils add-column mydb.db dogs friends_count integer --not-null-default 0 +.. note:: + In Python: :ref:`table.add_column() ` CLI reference: :ref:`sqlite-utils add-column ` + .. _cli_add_column_alter: Adding columns automatically on insert/update @@ -2522,6 +2567,9 @@ You can use the ``--alter`` option to automatically add new columns if the data sqlite-utils insert dogs.db dogs new-dogs.json --pk=id --alter +.. note:: + In Python: :ref:`table.insert(..., alter=True) ` + .. _cli_add_foreign_key: Adding foreign key constraints @@ -2549,6 +2597,9 @@ Add ``--ignore`` to ignore an existing foreign key (as opposed to returning an e See :ref:`python_api_add_foreign_key` in the Python API documentation for further details, including how the automatic table guessing mechanism works. +.. note:: + In Python: :ref:`table.add_foreign_key() ` CLI reference: :ref:`sqlite-utils add-foreign-key ` + .. _cli_add_foreign_keys: Adding multiple foreign keys at once @@ -2564,6 +2615,9 @@ Adding a foreign key requires a ``VACUUM``. On large databases this can be an ex When you are using this command each foreign key needs to be defined in full, as four arguments - the table, column, other table and other column. +.. note:: + In Python: :ref:`db.add_foreign_keys() ` CLI reference: :ref:`sqlite-utils add-foreign-keys ` + .. _cli_index_foreign_keys: Adding indexes for all foreign keys @@ -2575,6 +2629,9 @@ If you want to ensure that every foreign key column in your database has a corre sqlite-utils index-foreign-keys books.db +.. note:: + In Python: :ref:`db.index_foreign_keys() ` CLI reference: :ref:`sqlite-utils index-foreign-keys ` + .. _cli_defaults_not_null: Setting defaults and not null constraints @@ -2590,6 +2647,9 @@ You can use the ``--not-null`` and ``--default`` options (to both ``insert`` and --default age 2 \ --default score 5 +.. note:: + In Python: :ref:`not_null= and defaults= arguments ` + .. _cli_create_index: Creating indexes @@ -2621,6 +2681,9 @@ If your column names are already prefixed with a hyphen you'll need to manually Add the ``--analyze`` option to run ``ANALYZE`` against the index after it has been created. +.. note:: + In Python: :ref:`table.create_index() ` CLI reference: :ref:`sqlite-utils create-index ` + .. _cli_drop_index: Dropping indexes @@ -2634,6 +2697,9 @@ You can drop an index from an existing table using the ``drop-index`` command: Use ``--ignore`` to ignore the error if the index does not exist on that table. +.. note:: + In Python: :ref:`table.drop_index() ` CLI reference: :ref:`sqlite-utils drop-index ` + .. _cli_fts: Configuring full-text search @@ -2687,6 +2753,9 @@ You can rebuild every FTS table by running ``rebuild-fts`` without passing any t sqlite-utils rebuild-fts mydb.db +.. note:: + In Python: :ref:`table.enable_fts() ` CLI reference: :ref:`sqlite-utils enable-fts ` + .. _cli_search: Executing searches @@ -2743,6 +2812,9 @@ Use the ``--sql`` option to output the SQL that would be executed, rather than r order by "documents_fts".rank +.. note:: + In Python: :ref:`table.search() ` CLI reference: :ref:`sqlite-utils search ` + .. _cli_enable_counts: Enabling cached counts @@ -2766,6 +2838,9 @@ If the ``_counts`` table ever becomes out-of-sync with the actual table counts y sqlite-utils reset-counts mydb.db +.. note:: + In Python: :ref:`table.enable_counts() ` CLI reference: :ref:`sqlite-utils enable-counts ` + .. _cli_analyze: Optimizing index usage with ANALYZE @@ -2789,6 +2864,9 @@ You can run it against specific tables, or against specific named indexes, by pa You can also run ``ANALYZE`` as part of another command using the ``--analyze`` option. This is supported by the ``create-index``, ``insert`` and ``upsert`` commands. +.. note:: + In Python: :ref:`db.analyze() ` CLI reference: :ref:`sqlite-utils analyze ` + .. _cli_vacuum: Vacuum @@ -2800,6 +2878,9 @@ You can run VACUUM to optimize your database like so: sqlite-utils vacuum mydb.db +.. note:: + In Python: :ref:`db.vacuum() ` CLI reference: :ref:`sqlite-utils vacuum ` + .. _cli_optimize: Optimize @@ -2823,6 +2904,9 @@ To optimize specific tables rather than every FTS table, pass those tables as ex sqlite-utils optimize mydb.db table_1 table_2 +.. note:: + In Python: :ref:`table.optimize() ` CLI reference: :ref:`sqlite-utils optimize ` + .. _cli_wal: WAL mode @@ -2842,6 +2926,9 @@ You can disable WAL mode using ``disable-wal``: Both of these commands accept one or more database files as arguments. +.. note:: + In Python: :ref:`db.enable_wal() and db.disable_wal() ` CLI reference: :ref:`sqlite-utils enable-wal ` + .. _cli_dump: Dumping the database to SQL @@ -2857,6 +2944,9 @@ The ``dump`` command outputs a SQL dump of the schema and full contents of the s ... COMMIT; +.. note:: + In Python: :ref:`db.iterdump() ` CLI reference: :ref:`sqlite-utils dump ` + .. _cli_load_extension: Loading SQLite extensions @@ -2904,6 +2994,9 @@ Eight (case-insensitive) types are allowed: * GEOMETRYCOLLECTION * GEOMETRY +.. note:: + In Python: :ref:`table.add_geometry_column() ` CLI reference: :ref:`sqlite-utils add-geometry-column ` + .. _cli_spatialite_indexes: Adding spatial indexes @@ -2917,6 +3010,9 @@ Once you have a geometry column, you can speed up bounding box queries by adding See this `SpatiaLite Cookbook recipe `__ for examples of how to use a spatial index. +.. note:: + In Python: :ref:`table.create_spatial_index() ` CLI reference: :ref:`sqlite-utils create-spatial-index ` + .. _cli_install: Installing packages diff --git a/docs/python-api.rst b/docs/python-api.rst index 8b076777..1ed238e6 100644 --- a/docs/python-api.rst +++ b/docs/python-api.rst @@ -184,6 +184,9 @@ You can attach an additional database using the ``.attach()`` method, providing You can reference tables in the attached database using the alias value you passed to ``db.attach(alias, filepath)`` as a prefix, for example the ``second.table_in_second`` reference in the SQL query above. +.. note:: + In the CLI: :ref:`sqlite-utils --attach ` + .. _python_api_tracing: Tracing queries @@ -254,6 +257,9 @@ If a query returns more than one column with the same name - a join between two A suffix that would collide with another column in the query is skipped - ``select 1 as id, 2 as id, 3 as id_2`` returns ``{'id': 1, 'id_3': 2, 'id_2': 3}``. The same renaming is applied by ``table.rows_where()`` and ``table.search()``. +.. note:: + In the CLI: :ref:`sqlite-utils query ` + .. _python_api_execute: db.execute(sql, params) @@ -497,6 +503,9 @@ You can also iterate through the table objects themselves using the ``.tables`` >>> db.tables [] +.. note:: + In the CLI: :ref:`sqlite-utils tables ` + .. _python_api_views: Listing views @@ -522,6 +531,9 @@ View objects are similar to Table objects, except that any attempts to insert or * ``rows_where(where, where_args, order_by, select)`` * ``drop()`` +.. note:: + In the CLI: :ref:`sqlite-utils views ` + .. _python_api_rows: Listing rows @@ -577,6 +589,9 @@ This method also accepts ``offset=`` and ``limit=`` arguments, for specifying an ... print(row) {'id': 1, 'age': 4, 'name': 'Cleo'} +.. note:: + In the CLI: :ref:`sqlite-utils rows ` + .. _python_api_rows_count_where: Counting rows @@ -661,6 +676,9 @@ The ``db.schema`` property returns the full SQL schema for the database as a str "name" TEXT ); +.. note:: + In the CLI: :ref:`sqlite-utils schema ` + .. _python_api_creating_tables: Creating tables @@ -809,6 +827,9 @@ You can pass ``strict=True`` to create a table in ``STRICT`` mode: "name": str, }, strict=True) +.. note:: + In the CLI: :ref:`sqlite-utils create-table ` + .. _python_api_compound_primary_keys: Compound primary keys @@ -989,6 +1010,9 @@ Here's an example that uses these features: # ) +.. note:: + In the CLI: :ref:`sqlite-utils insert --not-null and --default ` + .. _python_api_rename_table: Renaming a table @@ -1006,6 +1030,9 @@ This executes the following SQL: ALTER TABLE [my_table] RENAME TO [new_name_for_my_table] +.. note:: + In the CLI: :ref:`sqlite-utils rename-table ` + .. _python_api_duplicate: Duplicating tables @@ -1021,6 +1048,9 @@ The new ``authors_copy`` table will now contain a duplicate copy of the data fro This method raises ``sqlite_utils.db.NoTable`` if the table does not exist. +.. note:: + In the CLI: :ref:`sqlite-utils duplicate ` + .. _python_api_bulk_inserts: Bulk inserts @@ -1063,6 +1093,9 @@ You can delete all the existing rows in the table before inserting the new recor Pass ``analyze=True`` to run ``ANALYZE`` against the table after inserting the new records. +.. note:: + In the CLI: :ref:`sqlite-utils insert ` + .. _python_api_insert_lists: Inserting data from a list or tuple iterator @@ -1140,6 +1173,9 @@ To replace any existing records that have a matching primary key, use the ``repl .. note:: Prior to sqlite-utils 2.0 the ``.upsert()`` and ``.upsert_all()`` methods worked the same way as ``.insert(replace=True)`` does today. See :ref:`python_api_upsert` for the new behaviour of those methods introduced in 2.0. +.. note:: + In the CLI: :ref:`sqlite-utils insert --replace ` + .. _python_api_update: Updating a specific record @@ -1225,6 +1261,9 @@ Every record passed to ``upsert()`` or ``upsert_all()`` must include a value for .. note:: ``.upsert()`` and ``.upsert_all()`` in sqlite-utils 1.x worked like ``.insert(..., replace=True)`` and ``.insert_all(..., replace=True)`` do in 2.x. See `issue #66 `__ for details of this change. +.. note:: + In the CLI: :ref:`sqlite-utils upsert ` + .. _python_api_old_upsert: Alternative upserts using INSERT OR IGNORE @@ -1576,6 +1615,9 @@ You can set a ``NOT NULL DEFAULT 'x'`` constraint on the new column using ``not_ db.table("dogs").add_column("friends_count", int, not_null_default=0) +.. note:: + In the CLI: :ref:`sqlite-utils add-column ` + .. _python_api_add_column_alter: Adding columns automatically on insert/update @@ -1599,6 +1641,9 @@ You can insert or update data that includes new columns and have the table autom new_table = db.table("new_table", alter=True) new_table.insert({"name": "Gareth", "age": 32, "shoe_size": 11}) +.. note:: + In the CLI: :ref:`sqlite-utils insert --alter ` + .. _python_api_add_foreign_key: Adding foreign key constraints @@ -1657,6 +1702,9 @@ Use ``on_delete=`` and ``on_update=`` to specify ``ON DELETE`` and ``ON UPDATE`` This creates a foreign key with an ``ON DELETE CASCADE`` clause, so deleting an author will also delete their books (provided foreign key enforcement is enabled with ``PRAGMA foreign_keys = ON``). Valid actions are ``"SET NULL"``, ``"SET DEFAULT"``, ``"CASCADE"``, ``"RESTRICT"`` and the default ``"NO ACTION"``. +.. note:: + In the CLI: :ref:`sqlite-utils add-foreign-key ` + .. _python_api_add_foreign_keys: Adding multiple foreign key constraints at once @@ -1677,6 +1725,9 @@ This method runs the same checks as ``.add_foreign_keys()`` and will raise ``sql Foreign keys that already exist are silently skipped, so repeated calls are idempotent - but only if they match exactly. Requesting a foreign key that exists with different ``ON DELETE``/``ON UPDATE`` actions raises ``AlterError``: use ``table.transform()`` to change the actions of an existing foreign key. +.. note:: + In the CLI: :ref:`sqlite-utils add-foreign-keys ` + .. _python_api_index_foreign_keys: Adding indexes for all foreign keys @@ -1690,6 +1741,9 @@ If you want to ensure that every foreign key column in your database has a corre Compound foreign keys get a single composite index across their columns. +.. note:: + In the CLI: :ref:`sqlite-utils index-foreign-keys ` + .. _python_api_drop: Dropping a table or view @@ -1711,6 +1765,9 @@ Pass ``ignore=True`` if you want to ignore the error caused by the table or view db.table("my_table").drop(ignore=True) +.. note:: + In the CLI: :ref:`sqlite-utils drop-table ` and :ref:`sqlite-utils drop-view ` + .. _python_api_transform: Transforming a table @@ -1739,6 +1796,9 @@ To keep the original table around instead of dropping it, pass the ``keep_table= This method raises a ``sqlite_utils.db.TransformError`` exception if the table cannot be transformed, usually because there are existing constraints or indexes that are incompatible with modifications to the columns. +.. note:: + In the CLI: :ref:`sqlite-utils transform ` + .. _python_api_transform_alter_column_types: Altering column types @@ -2094,6 +2154,9 @@ This produces a lookup table like so: Rows where every extracted column is ``null`` are not extracted: no record is created for them in the lookup table and their foreign key column is left as ``null``. When extracting multiple columns, rows where at least one of the extracted columns has a value will be extracted as usual. +.. note:: + In the CLI: :ref:`sqlite-utils extract ` + .. _python_api_hash: Setting an ID based on the hash of the row contents @@ -2155,6 +2218,9 @@ You can pass ``ignore=True`` to silently ignore an existing view and do nothing, select * from dogs where is_good_dog = 1 """, replace=True) +.. note:: + In the CLI: :ref:`sqlite-utils create-view ` + Storing JSON ============ @@ -2273,6 +2339,9 @@ If you are using ``pysqlite3`` the underlying method may be missing. If you inst pip install sqlite-dump +.. note:: + In the CLI: :ref:`sqlite-utils dump ` + .. _python_api_introspection: Introspecting tables and views @@ -2472,6 +2541,9 @@ The ``.indexes`` property returns all indexes created for a table, as a list of Index(seq=4, name='"Street_Tree_List_qCaretaker"', unique=0, origin='c', partial=0, columns=['qCaretaker']), Index(seq=5, name='"Street_Tree_List_PlantType"', unique=0, origin='c', partial=0, columns=['PlantType'])] +.. note:: + In the CLI: :ref:`sqlite-utils indexes ` + .. _python_api_introspection_xindexes: .xindexes @@ -2515,6 +2587,9 @@ The ``.triggers`` property lists database triggers. It can be used on both datab >>> db.triggers ... similar output to db.table("authors").triggers +.. note:: + In the CLI: :ref:`sqlite-utils triggers ` + .. _python_api_introspection_triggers_dict: .triggers_dict @@ -2663,6 +2738,9 @@ To remove the FTS tables and triggers you created, use the ``disable_fts()`` tab db.table("dogs").disable_fts() +.. note:: + In the CLI: :ref:`sqlite-utils enable-fts ` + .. _python_api_quote_fts: Quoting characters for use in search @@ -2727,6 +2805,9 @@ To return just the title and published columns for three matches for ``"dog"`` w ): print(article) +.. note:: + In the CLI: :ref:`sqlite-utils search ` + .. _python_api_fts_search_sql: Building SQL queries with table.search_sql() @@ -2811,6 +2892,9 @@ This runs the following SQL:: INSERT INTO dogs_fts (dogs_fts) VALUES ("rebuild"); +.. note:: + In the CLI: :ref:`sqlite-utils rebuild-fts ` + .. _python_api_fts_optimize: Optimizing a full-text search table @@ -2826,6 +2910,9 @@ This runs the following SQL:: INSERT INTO dogs_fts (dogs_fts) VALUES ("optimize"); +.. note:: + In the CLI: :ref:`sqlite-utils optimize ` + .. _python_api_cached_table_counts: Cached table counts using triggers @@ -2888,6 +2975,9 @@ If the ``_counts`` table ever becomes out-of-sync with the actual table counts y db.reset_counts() +.. note:: + In the CLI: :ref:`sqlite-utils enable-counts ` + .. _python_api_create_index: Creating indexes @@ -2939,6 +3029,9 @@ You can drop an index from a table using ``.drop_index(index_name)``: Use ``ignore=True`` to ignore the error if the index does not exist. +.. note:: + In the CLI: :ref:`sqlite-utils create-index ` and :ref:`sqlite-utils drop-index ` + .. _python_api_analyze: Optimizing index usage with ANALYZE @@ -2966,6 +3059,9 @@ To run against all indexes attached to a specific table, you can either pass the db.table("dogs").analyze() +.. note:: + In the CLI: :ref:`sqlite-utils analyze ` + .. _python_api_vacuum: Vacuum @@ -2977,6 +3073,9 @@ You can optimize your database by running VACUUM against it like so: Database("my_database.db").vacuum() +.. note:: + In the CLI: :ref:`sqlite-utils vacuum ` + .. _python_api_wal: WAL mode @@ -3004,6 +3103,9 @@ You can check the current journal mode for a database using the ``journal_mode`` This will usually be ``wal`` or ``delete`` (meaning WAL is disabled), but can have other values - see the `PRAGMA journal_mode `__ documentation. +.. note:: + In the CLI: :ref:`sqlite-utils enable-wal and disable-wal ` + .. _python_api_suggest_column_types: Suggesting column types @@ -3144,6 +3246,9 @@ You can cause ``sqlite3`` to return more useful errors, including the traceback sqlite3.enable_callback_tracebacks(True) +.. note:: + In the CLI: :ref:`sqlite-utils query --functions ` + .. _python_api_quote: Quoting strings for use in SQL @@ -3276,6 +3381,9 @@ Initialize SpatiaLite .. automethod:: sqlite_utils.db.Database.init_spatialite :noindex: +.. note:: + In the CLI: :ref:`sqlite-utils create-database --init-spatialite ` + .. _python_api_gis_find_spatialite: Finding SpatiaLite @@ -3291,6 +3399,9 @@ Adding geometry columns .. automethod:: sqlite_utils.db.Table.add_geometry_column :noindex: +.. note:: + In the CLI: :ref:`sqlite-utils add-geometry-column ` + .. _python_api_gis_create_spatial_index: Creating a spatial index @@ -3298,3 +3409,6 @@ Creating a spatial index .. automethod:: sqlite_utils.db.Table.create_spatial_index :noindex: + +.. note:: + In the CLI: :ref:`sqlite-utils create-spatial-index `