From 4c6023452cbfc0c112cfc2a940ed40d22e8d36c9 Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Tue, 25 Jan 2022 19:14:59 -0800 Subject: [PATCH] Examples in --help for remaining commands, closes #384 --- docs/cli-reference.rst | 135 ++++++++++++++++++++++---- sqlite_utils/cli.py | 216 ++++++++++++++++++++++++++++++++++------- 2 files changed, 297 insertions(+), 54 deletions(-) diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst index 868cc3b..583f7e2 100644 --- a/docs/cli-reference.rst +++ b/docs/cli-reference.rst @@ -605,6 +605,10 @@ See :ref:`cli_views`. List the views in the database + Example: + + sqlite-utils views trees.db + Options: --counts Include row counts per view --nl Output newline-delimited JSON @@ -637,6 +641,10 @@ See :ref:`cli_rows`. Output all rows in the specified table + Example: + + sqlite-utils rows trees.db Trees + Options: -c, --column TEXT Columns to return --where TEXT Optional where clause @@ -671,6 +679,10 @@ See :ref:`cli_triggers`. Show triggers configured in this database + Example: + + sqlite-utils triggers trees.db + Options: --nl Output newline-delimited JSON --arrays Output rows as arrays instead of objects @@ -698,7 +710,11 @@ See :ref:`cli_indexes`. Usage: sqlite-utils indexes [OPTIONS] PATH [TABLES]... - Show indexes for this database + Show indexes for the whole database or specific tables + + Example: + + sqlite-utils indexes trees.db Trees Options: --aux Include auxiliary columns @@ -728,7 +744,11 @@ See :ref:`cli_create_database`. Usage: sqlite-utils create-database [OPTIONS] PATH - Create a new empty database file. + Create a new empty database file + + Example: + + sqlite-utils create-database trees.db Options: --enable-wal Enable WAL mode on the created database @@ -747,11 +767,11 @@ See :ref:`cli_create_table`. Add a table with the specified columns. Columns should be specified using name, type pairs, for example: - sqlite-utils create-table my.db people \ - id integer \ - name text \ - height float \ - photo blob --pk id + sqlite-utils create-table my.db people \ + id integer \ + name text \ + height float \ + photo blob --pk id Options: --pk TEXT Column to use as primary key @@ -774,9 +794,15 @@ See :ref:`cli_create_index`. Usage: sqlite-utils create-index [OPTIONS] PATH TABLE COLUMN... - Add an index to the specified table covering the specified columns. Use - "sqlite-utils create-index mydb -- -column" to specify descending order for a - column. + Add an index to the specified table for the specified columns + + Example: + + sqlite-utils create-index chickens.db chickens name + + To create an index in descending order: + + sqlite-utils create-index chickens.db chickens -- -name Options: --name TEXT Explicit name for the new index @@ -796,7 +822,11 @@ See :ref:`cli_fts`. Usage: sqlite-utils enable-fts [OPTIONS] PATH TABLE COLUMN... - Enable full-text search for specific table and columns + Enable full-text search for specific table and columns" + + Example: + + sqlite-utils enable-fts chickens.db chickens name Options: --fts4 Use FTS4 @@ -817,6 +847,10 @@ populate-fts Re-populate full-text search for specific table and columns + Example: + + sqlite-utils populate-fts chickens.db chickens name + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -831,6 +865,10 @@ rebuild-fts Rebuild all or specific full-text search tables + Example: + + sqlite-utils rebuild-fts chickens.db chickens + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -845,6 +883,10 @@ disable-fts Disable full-text search for specific table + Example: + + sqlite-utils disable-fts chickens.db chickens + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -862,6 +904,10 @@ See :ref:`cli_optimize`. Optimize all full-text search tables and then run VACUUM - should shrink the database file + Example: + + sqlite-utils optimize chickens.db + Options: --no-vacuum Don't run VACUUM --load-extension TEXT SQLite extensions to load @@ -880,6 +926,10 @@ See :ref:`cli_analyze`. Run ANALYZE against the whole database, or against specific named indexes and tables + Example: + + sqlite-utils analyze chickens.db + Options: -h, --help Show this message and exit. @@ -895,6 +945,10 @@ See :ref:`cli_vacuum`. Run VACUUM against the database + Example: + + sqlite-utils vacuum chickens.db + Options: -h, --help Show this message and exit. @@ -910,6 +964,10 @@ See :ref:`cli_dump`. Output a SQL dump of the schema and full contents of the database + Example: + + sqlite-utils dump chickens.db + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -927,6 +985,10 @@ See :ref:`cli_add_column`. Add a column to the specified table + Example: + + sqlite-utils add-column chickens.db chickens weight float + Options: --fk TEXT Table to reference as a foreign key --fk-col TEXT Referenced column on that foreign key table - if @@ -946,9 +1008,11 @@ See :ref:`cli_add_foreign_key`. Usage: sqlite-utils add-foreign-key [OPTIONS] PATH TABLE COLUMN [OTHER_TABLE] [OTHER_COLUMN] - Add a new foreign key constraint to an existing table. Example usage: + Add a new foreign key constraint to an existing table - $ sqlite-utils add-foreign-key my.db books author_id authors id + Example: + + sqlite-utils add-foreign-key my.db books author_id authors id WARNING: Could corrupt your database! Back up your database file first. @@ -967,11 +1031,13 @@ See :ref:`cli_add_foreign_keys`. Usage: sqlite-utils add-foreign-keys [OPTIONS] PATH [FOREIGN_KEY]... - Add multiple new foreign key constraints to a database. Example usage: + Add multiple new foreign key constraints to a database - sqlite-utils add-foreign-keys my.db \ - books author_id authors id \ - authors country_id countries id + Example: + + sqlite-utils add-foreign-keys my.db \ + books author_id authors id \ + authors country_id countries id Options: --load-extension TEXT SQLite extensions to load @@ -987,7 +1053,11 @@ See :ref:`cli_index_foreign_keys`. Usage: sqlite-utils index-foreign-keys [OPTIONS] PATH - Ensure every foreign key column has an index on it. + Ensure every foreign key column has an index on it + + Example: + + sqlite-utils index-foreign-keys chickens.db Options: --load-extension TEXT SQLite extensions to load @@ -1005,6 +1075,10 @@ See :ref:`cli_wal`. Enable WAL for database files + Example: + + sqlite-utils enable-wal chickens.db + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -1019,6 +1093,10 @@ disable-wal Disable WAL for database files + Example: + + sqlite-utils disable-wal chickens.db + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -1035,6 +1113,10 @@ See :ref:`cli_enable_counts`. Configure triggers to update a _counts table with row counts + Example: + + sqlite-utils enable-counts chickens.db + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -1049,6 +1131,10 @@ reset-counts Reset calculated counts in the _counts table + Example: + + sqlite-utils reset-counts chickens.db + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -1065,6 +1151,10 @@ See :ref:`cli_drop_table`. Drop the specified table + Example: + + sqlite-utils drop-table chickens.db chickens + Options: --ignore --load-extension TEXT SQLite extensions to load @@ -1082,6 +1172,11 @@ See :ref:`cli_create_view`. Create a view for the provided SELECT query + Example: + + sqlite-utils create-view chickens.db heavy_chickens \ + 'select * from chickens where weight > 3' + Options: --ignore If view already exists, do nothing --replace If view already exists, replace it @@ -1100,6 +1195,10 @@ See :ref:`cli_drop_view`. Drop the specified view + Example: + + sqlite-utils drop-view chickens.db heavy_chickens + Options: --ignore --load-extension TEXT SQLite extensions to load diff --git a/sqlite_utils/cli.py b/sqlite_utils/cli.py index 42fc8e8..350f9e3 100644 --- a/sqlite_utils/cli.py +++ b/sqlite_utils/cli.py @@ -250,7 +250,13 @@ def views( schema, load_extension, ): - """List the views in the database""" + """List the views in the database + + Example: + + \b + sqlite-utils views trees.db + """ tables.callback( path=path, fts4=False, @@ -281,7 +287,13 @@ def views( @click.option("--no-vacuum", help="Don't run VACUUM", default=False, is_flag=True) @load_extension_option def optimize(path, tables, no_vacuum, load_extension): - """Optimize all full-text search tables and then run VACUUM - should shrink the database file""" + """Optimize all full-text search tables and then run VACUUM - should shrink the database file + + Example: + + \b + sqlite-utils optimize chickens.db + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) if not tables: @@ -302,7 +314,13 @@ def optimize(path, tables, no_vacuum, load_extension): @click.argument("tables", nargs=-1) @load_extension_option def rebuild_fts(path, tables, load_extension): - """Rebuild all or specific full-text search tables""" + """Rebuild all or specific full-text search tables + + Example: + + \b + sqlite-utils rebuild-fts chickens.db chickens + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) if not tables: @@ -320,7 +338,13 @@ def rebuild_fts(path, tables, load_extension): ) @click.argument("names", nargs=-1) def analyze(path, names): - """Run ANALYZE against the whole database, or against specific named indexes and tables""" + """Run ANALYZE against the whole database, or against specific named indexes and tables + + Example: + + \b + sqlite-utils analyze chickens.db + """ db = sqlite_utils.Database(path) try: if names: @@ -339,7 +363,13 @@ def analyze(path, names): required=True, ) def vacuum(path): - """Run VACUUM against the database""" + """Run VACUUM against the database + + Example: + + \b + sqlite-utils vacuum chickens.db + """ sqlite_utils.Database(path).vacuum() @@ -351,7 +381,13 @@ def vacuum(path): ) @load_extension_option def dump(path, load_extension): - """Output a SQL dump of the schema and full contents of the database""" + """Output a SQL dump of the schema and full contents of the database + + Example: + + \b + sqlite-utils dump chickens.db + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) for line in db.conn.iterdump(): @@ -392,7 +428,13 @@ def dump(path, load_extension): def add_column( path, table, col_name, col_type, fk, fk_col, not_null_default, load_extension ): - "Add a column to the specified table" + """Add a column to the specified table + + Example: + + \b + sqlite-utils add-column chickens.db chickens weight float + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) db[table].add_column( @@ -420,9 +462,11 @@ def add_foreign_key( path, table, column, other_table, other_column, ignore, load_extension ): """ - Add a new foreign key constraint to an existing table. Example usage: + Add a new foreign key constraint to an existing table - $ sqlite-utils add-foreign-key my.db books author_id authors id + Example: + + sqlite-utils add-foreign-key my.db books author_id authors id WARNING: Could corrupt your database! Back up your database file first. """ @@ -444,12 +488,14 @@ def add_foreign_key( @load_extension_option def add_foreign_keys(path, foreign_key, load_extension): """ - Add multiple new foreign key constraints to a database. Example usage: + Add multiple new foreign key constraints to a database + + Example: \b - sqlite-utils add-foreign-keys my.db \\ - books author_id authors id \\ - authors country_id countries id + sqlite-utils add-foreign-keys my.db \\ + books author_id authors id \\ + authors country_id countries id """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) @@ -475,7 +521,12 @@ def add_foreign_keys(path, foreign_key, load_extension): @load_extension_option def index_foreign_keys(path, load_extension): """ - Ensure every foreign key column has an index on it. + Ensure every foreign key column has an index on it + + Example: + + \b + sqlite-utils index-foreign-keys chickens.db """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) @@ -508,9 +559,17 @@ def create_index( path, table, column, name, unique, if_not_exists, analyze, load_extension ): """ - Add an index to the specified table covering the specified columns. - Use "sqlite-utils create-index mydb -- -column" to specify descending - order for a column. + Add an index to the specified table for the specified columns + + Example: + + \b + sqlite-utils create-index chickens.db chickens name + + To create an index in descending order: + + \b + sqlite-utils create-index chickens.db chickens -- -name """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) @@ -550,7 +609,13 @@ def create_index( def enable_fts( path, table, column, fts4, fts5, tokenize, create_triggers, load_extension ): - "Enable full-text search for specific table and columns" + """Enable full-text search for specific table and columns" + + Example: + + \b + sqlite-utils enable-fts chickens.db chickens name + """ fts_version = "FTS5" if fts4 and fts5: click.echo("Can only use one of --fts4 or --fts5", err=True) @@ -578,7 +643,13 @@ def enable_fts( @click.argument("column", nargs=-1, required=True) @load_extension_option def populate_fts(path, table, column, load_extension): - "Re-populate full-text search for specific table and columns" + """Re-populate full-text search for specific table and columns + + Example: + + \b + sqlite-utils populate-fts chickens.db chickens name + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) db[table].populate_fts(column) @@ -593,7 +664,13 @@ def populate_fts(path, table, column, load_extension): @click.argument("table") @load_extension_option def disable_fts(path, table, load_extension): - "Disable full-text search for specific table" + """Disable full-text search for specific table + + Example: + + \b + sqlite-utils disable-fts chickens.db chickens + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) db[table].disable_fts() @@ -608,7 +685,13 @@ def disable_fts(path, table, load_extension): ) @load_extension_option def enable_wal(path, load_extension): - "Enable WAL for database files" + """Enable WAL for database files + + Example: + + \b + sqlite-utils enable-wal chickens.db + """ for path_ in path: db = sqlite_utils.Database(path_) _load_extensions(db, load_extension) @@ -624,7 +707,13 @@ def enable_wal(path, load_extension): ) @load_extension_option def disable_wal(path, load_extension): - "Disable WAL for database files" + """Disable WAL for database files + + Example: + + \b + sqlite-utils disable-wal chickens.db + """ for path_ in path: db = sqlite_utils.Database(path_) _load_extensions(db, load_extension) @@ -640,7 +729,13 @@ def disable_wal(path, load_extension): @click.argument("tables", nargs=-1) @load_extension_option def enable_counts(path, tables, load_extension): - "Configure triggers to update a _counts table with row counts" + """Configure triggers to update a _counts table with row counts + + Example: + + \b + sqlite-utils enable-counts chickens.db + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) if not tables: @@ -662,7 +757,13 @@ def enable_counts(path, tables, load_extension): ) @load_extension_option def reset_counts(path, load_extension): - "Reset calculated counts in the _counts table" + """Reset calculated counts in the _counts table + + Example: + + \b + sqlite-utils reset-counts chickens.db + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) db.reset_counts() @@ -1228,7 +1329,13 @@ def bulk( "--enable-wal", is_flag=True, help="Enable WAL mode on the created database" ) def create_database(path, enable_wal): - "Create a new empty database file." + """Create a new empty database file + + Example: + + \b + sqlite-utils create-database trees.db + """ db = sqlite_utils.Database(path) if enable_wal: db.enable_wal() @@ -1280,11 +1387,11 @@ def create_table( name, type pairs, for example: \b - sqlite-utils create-table my.db people \\ - id integer \\ - name text \\ - height float \\ - photo blob --pk id + sqlite-utils create-table my.db people \\ + id integer \\ + name text \\ + height float \\ + photo blob --pk id """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) @@ -1329,7 +1436,13 @@ def create_table( @click.option("--ignore", is_flag=True) @load_extension_option def drop_table(path, table, ignore, load_extension): - "Drop the specified table" + """Drop the specified table + + Example: + + \b + sqlite-utils drop-table chickens.db chickens + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) try: @@ -1358,7 +1471,14 @@ def drop_table(path, table, ignore, load_extension): ) @load_extension_option def create_view(path, view, select, ignore, replace, load_extension): - "Create a view for the provided SELECT query" + """Create a view for the provided SELECT query + + Example: + + \b + sqlite-utils create-view chickens.db heavy_chickens \\ + 'select * from chickens where weight > 3' + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) # Does view already exist? @@ -1386,7 +1506,13 @@ def create_view(path, view, select, ignore, replace, load_extension): @click.option("--ignore", is_flag=True) @load_extension_option def drop_view(path, view, ignore, load_extension): - "Drop the specified view" + """Drop the specified view + + Example: + + \b + sqlite-utils drop-view chickens.db heavy_chickens + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) try: @@ -1808,7 +1934,13 @@ def rows( json_cols, load_extension, ): - "Output all rows in the specified table" + """Output all rows in the specified table + + Example: + + \b + sqlite-utils rows trees.db Trees + """ columns = "*" if column: columns = ", ".join("[{}]".format(c) for c in column) @@ -1860,7 +1992,13 @@ def triggers( json_cols, load_extension, ): - "Show triggers configured in this database" + """Show triggers configured in this database + + Example: + + \b + sqlite-utils triggers trees.db + """ sql = "select name, tbl_name as [table], sql from sqlite_master where type = 'trigger'" if tables: quote = sqlite_utils.Database(memory=True).quote @@ -1909,7 +2047,13 @@ def indexes( json_cols, load_extension, ): - "Show indexes for this database" + """Show indexes for the whole database or specific tables + + Example: + + \b + sqlite-utils indexes trees.db Trees + """ sql = """ select sqlite_master.name as "table",