diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst index 546be1b..868cc3b 100644 --- a/docs/cli-reference.rst +++ b/docs/cli-reference.rst @@ -85,6 +85,12 @@ See :ref:`cli_query`. Execute SQL query and return the results as JSON + Example: + + sqlite-utils data.db \ + "select * from chickens where age > :age" \ + -p age 1 + Options: --attach ... Additional databases to attach - specify alias and filepath @@ -93,7 +99,7 @@ See :ref:`cli_query`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -150,7 +156,7 @@ See :ref:`cli_memory`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -183,7 +189,11 @@ See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`. Insert records from FILE into a table, creating the table if it does not already exist. - By default the input is expected to be a JSON array of objects. Or: + Example: + + echo '{"name": "Lila"}' | sqlite-utils insert data.db chickens - + + By default the input is expected to be a JSON object or array of objects. - Use --nl for newline-delimited JSON objects - Use --csv or --tsv for comma-separated or tab-separated input @@ -243,6 +253,15 @@ See :ref:`cli_upsert`. incoming record has a primary key that matches an existing record the existing record will be updated. + The --pk option is required. + + Example: + + echo '[ + {"id": 1, "name": "Lila"}, + {"id": 2, "name": "Suna"} + ]' | sqlite-utils upsert data.db chickens - --pk id + Options: --pk TEXT Columns to use as the primary key, e.g. id --flatten Flatten nested JSON objects, so {"a": {"b": 1}} @@ -281,6 +300,15 @@ See :ref:`cli_bulk`. Execute parameterized SQL against the provided list of documents. + Example: + + echo '[ + {"id": 1, "name": "Lila2"}, + {"id": 2, "name": "Suna2"} + ]' | sqlite-utils bulk data.db ' + update chickens set name = :name where id = :id + ' - + Options: --flatten Flatten nested JSON objects, so {"a": {"b": 1}} becomes {"a_b": 1} @@ -311,6 +339,10 @@ See :ref:`cli_search`. Execute a full-text search against this table + Example: + + sqlite-utils search data.db chickens lila + Options: -o, --order TEXT Order by ('column' or 'column desc') -c, --column TEXT Columns to return @@ -322,7 +354,7 @@ See :ref:`cli_search`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -345,6 +377,12 @@ See :ref:`cli_transform_table`. Transform a table beyond the capabilities of ALTER TABLE + Example: + + sqlite-utils transform mydb.db mytable \ + --drop column1 \ + --rename column2 column_renamed + Options: --type ... Change column type to INTEGER, TEXT, FLOAT or BLOB --drop TEXT Drop this column @@ -373,6 +411,10 @@ See :ref:`cli_extract`. Extract one or more columns into a separate table + Example: + + sqlite-utils extract trees.db Street_Trees species + Options: --table TEXT Name of the other table to extract columns to --fk-column TEXT Name of the foreign key column to add to the table @@ -392,6 +434,10 @@ See :ref:`cli_schema`. Show full schema for this database or for specified tables + Example: + + sqlite-utils schema trees.db + Options: --load-extension TEXT SQLite extensions to load -h, --help Show this message and exit. @@ -408,16 +454,16 @@ See :ref:`cli_insert_files`. Insert one or more files using BLOB columns in the specified table - Example usage: + Example: - sqlite-utils insert-files pics.db images *.gif \ - -c name:name \ - -c content:content \ - -c content_hash:sha256 \ - -c created:ctime_iso \ - -c modified:mtime_iso \ - -c size:size \ - --pk name + sqlite-utils insert-files pics.db images *.gif \ + -c name:name \ + -c content:content \ + -c content_hash:sha256 \ + -c created:ctime_iso \ + -c modified:mtime_iso \ + -c size:size \ + --pk name Options: -c, --column TEXT Column definitions for the table @@ -444,6 +490,10 @@ See :ref:`cli_analyze_tables`. Analyze the columns in one or more tables + Example: + + sqlite-utils analyze-tables data.db trees + Options: -c, --column TEXT Specific columns to analyze --save Save results to _analyze_tables table @@ -462,9 +512,9 @@ See :ref:`cli_convert`. Convert columns using Python code you supply. For example: - $ sqlite-utils convert my.db mytable mycolumn \ - '"\n".join(textwrap.wrap(value, 10))' \ - --import=textwrap + sqlite-utils convert my.db mytable mycolumn \ + '"\n".join(textwrap.wrap(value, 10))' \ + --import=textwrap "value" is a variable with the column value to be converted. @@ -486,8 +536,8 @@ See :ref:`cli_convert`. You can use these recipes like so: - $ sqlite-utils convert my.db mytable mycolumn \ - 'r.jsonsplit(value, delimiter=":")' + sqlite-utils convert my.db mytable mycolumn \ + 'r.jsonsplit(value, delimiter=":")' Options: --import TEXT Python modules to import @@ -517,6 +567,10 @@ See :ref:`cli_tables`. List the tables in the database + Example: + + sqlite-utils tables trees.db + Options: --fts4 Just show FTS4 enabled tables --fts5 Just show FTS5 enabled tables @@ -526,7 +580,7 @@ See :ref:`cli_tables`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -558,7 +612,7 @@ See :ref:`cli_views`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -594,7 +648,7 @@ See :ref:`cli_rows`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -623,7 +677,7 @@ See :ref:`cli_triggers`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, @@ -653,7 +707,7 @@ See :ref:`cli_indexes`. --csv Output CSV --tsv Output TSV --no-headers Omit CSV headers - -t, --table Output as a table + -t, --table Output as a formatted table --fmt TEXT Table format - one of fancy_grid, fancy_outline, github, grid, html, jira, latex, latex_booktabs, latex_longtable, latex_raw, mediawiki, moinmoin, diff --git a/sqlite_utils/cli.py b/sqlite_utils/cli.py index 4f950ad..42fc8e8 100644 --- a/sqlite_utils/cli.py +++ b/sqlite_utils/cli.py @@ -75,7 +75,9 @@ def output_options(fn): click.option("--csv", is_flag=True, help="Output CSV"), click.option("--tsv", is_flag=True, help="Output TSV"), click.option("--no-headers", is_flag=True, help="Omit CSV headers"), - click.option("-t", "--table", is_flag=True, help="Output as a table"), + click.option( + "-t", "--table", is_flag=True, help="Output as a formatted table" + ), click.option( "--fmt", help="Table format - one of {}".format( @@ -161,7 +163,13 @@ def tables( load_extension, views=False, ): - """List the tables in the database""" + """List the tables in the database + + Example: + + \b + sqlite-utils tables trees.db + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) headers = ["view" if views else "table"] @@ -1001,7 +1009,11 @@ def insert( Insert records from FILE into a table, creating the table if it does not already exist. - By default the input is expected to be a JSON array of objects. Or: + Example: + + echo '{"name": "Lila"}' | sqlite-utils insert data.db chickens - + + By default the input is expected to be a JSON object or array of objects. \b - Use --nl for newline-delimited JSON objects @@ -1087,6 +1099,16 @@ def upsert( Upsert records based on their primary key. Works like 'insert' but if an incoming record has a primary key that matches an existing record the existing record will be updated. + + The --pk option is required. + + Example: + + \b + echo '[ + {"id": 1, "name": "Lila"}, + {"id": 2, "name": "Suna"} + ]' | sqlite-utils upsert data.db chickens - --pk id """ try: insert_upsert_implementation( @@ -1152,6 +1174,16 @@ def bulk( ): """ Execute parameterized SQL against the provided list of documents. + + Example: + + \b + echo '[ + {"id": 1, "name": "Lila2"}, + {"id": 2, "name": "Suna2"} + ]' | sqlite-utils bulk data.db ' + update chickens set name = :name where id = :id + ' - """ try: insert_upsert_implementation( @@ -1402,7 +1434,15 @@ def query( param, load_extension, ): - "Execute SQL query and return the results as JSON" + """Execute SQL query and return the results as JSON + + Example: + + \b + sqlite-utils data.db \\ + "select * from chickens where age > :age" \\ + -p age 1 + """ db = sqlite_utils.Database(path) for alias, attach_path in attach: db.attach(alias, attach_path) @@ -1665,7 +1705,12 @@ def search( json_cols, load_extension, ): - "Execute a full-text search against this table" + """Execute a full-text search against this table + + Example: + + sqlite-utils search data.db chickens lila + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) # Check table exists @@ -1912,7 +1957,13 @@ def schema( tables, load_extension, ): - "Show full schema for this database or for specified tables" + """Show full schema for this database or for specified tables + + Example: + + \b + sqlite-utils schema trees.db + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) if tables: @@ -1985,7 +2036,15 @@ def transform( sql, load_extension, ): - "Transform a table beyond the capabilities of ALTER TABLE" + """Transform a table beyond the capabilities of ALTER TABLE + + Example: + + \b + sqlite-utils transform mydb.db mytable \\ + --drop column1 \\ + --rename column2 column_renamed + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) types = {} @@ -2060,7 +2119,13 @@ def extract( rename, load_extension, ): - "Extract one or more columns into a separate table" + """Extract one or more columns into a separate table + + Example: + + \b + sqlite-utils extract trees.db Street_Trees species + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) kwargs = dict( @@ -2122,17 +2187,17 @@ def insert_files( """ Insert one or more files using BLOB columns in the specified table - Example usage: + Example: \b - sqlite-utils insert-files pics.db images *.gif \\ - -c name:name \\ - -c content:content \\ - -c content_hash:sha256 \\ - -c created:ctime_iso \\ - -c modified:mtime_iso \\ - -c size:size \\ - --pk name + sqlite-utils insert-files pics.db images *.gif \\ + -c name:name \\ + -c content:content \\ + -c content_hash:sha256 \\ + -c created:ctime_iso \\ + -c modified:mtime_iso \\ + -c size:size \\ + --pk name """ if not column: if text: @@ -2244,7 +2309,13 @@ def analyze_tables( save, load_extension, ): - "Analyze the columns in one or more tables" + """Analyze the columns in one or more tables + + Example: + + \b + sqlite-utils analyze-tables data.db trees + """ db = sqlite_utils.Database(path) _load_extensions(db, load_extension) _analyze(db, tables, columns, save) @@ -2308,9 +2379,9 @@ def _generate_convert_help(): Convert columns using Python code you supply. For example: \b - $ sqlite-utils convert my.db mytable mycolumn \\ - '"\\n".join(textwrap.wrap(value, 10))' \\ - --import=textwrap + sqlite-utils convert my.db mytable mycolumn \\ + '"\\n".join(textwrap.wrap(value, 10))' \\ + --import=textwrap "value" is a variable with the column value to be converted. @@ -2333,8 +2404,8 @@ def _generate_convert_help(): You can use these recipes like so: \b - $ sqlite-utils convert my.db mytable mycolumn \\ - 'r.jsonsplit(value, delimiter=":")' + sqlite-utils convert my.db mytable mycolumn \\ + 'r.jsonsplit(value, delimiter=":")' """ ).strip() return help