remote/sqlite-utils
1
0
Fork 0
mirror of https://github.com/simonw/sqlite-utils.git synced 2026-09-11 02:54:23 +02:00
Code Issues Projects Releases Packages Wiki Activity

Added examples to more --help output, refs #384

Browse source
This commit is contained in:
Simon Willison 2022-01-25 18:56:44 -08:00
commit 6e85a4bbbe
2 changed files with 171 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

100
docs/cli-reference.rst
View file

@ -85,6 +85,12 @@ See :ref:`cli_query`.
Execute SQL query and return the results as JSON Execute SQL query and return the results as JSON
Example:
sqlite-utils data.db \
"select * from chickens where age > :age" \
-p age 1
Options: Options:
--attach <TEXT FILE>... Additional databases to attach - specify alias and --attach <TEXT FILE>... Additional databases to attach - specify alias and
filepath filepath
@ -93,7 +99,7 @@ See :ref:`cli_query`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,
@ -150,7 +156,7 @@ See :ref:`cli_memory`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, 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 Insert records from FILE into a table, creating the table if it does not
already exist. 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 --nl for newline-delimited JSON objects
- Use --csv or --tsv for comma-separated or tab-separated input - 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 incoming record has a primary key that matches an existing record the existing
record will be updated. 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: Options:
--pk TEXT Columns to use as the primary key, e.g. id --pk TEXT Columns to use as the primary key, e.g. id
--flatten Flatten nested JSON objects, so {"a": {"b": 1}} --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. 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: Options:
--flatten Flatten nested JSON objects, so {"a": {"b": 1}} becomes --flatten Flatten nested JSON objects, so {"a": {"b": 1}} becomes
{"a_b": 1} {"a_b": 1}
@ -311,6 +339,10 @@ See :ref:`cli_search`.
Execute a full-text search against this table Execute a full-text search against this table
Example:
sqlite-utils search data.db chickens lila
Options: Options:
-o, --order TEXT Order by ('column' or 'column desc') -o, --order TEXT Order by ('column' or 'column desc')
-c, --column TEXT Columns to return -c, --column TEXT Columns to return
@ -322,7 +354,7 @@ See :ref:`cli_search`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,
@ -345,6 +377,12 @@ See :ref:`cli_transform_table`.
Transform a table beyond the capabilities of ALTER TABLE Transform a table beyond the capabilities of ALTER TABLE
Example:
sqlite-utils transform mydb.db mytable \
--drop column1 \
--rename column2 column_renamed
Options: Options:
--type <TEXT CHOICE>... Change column type to INTEGER, TEXT, FLOAT or BLOB --type <TEXT CHOICE>... Change column type to INTEGER, TEXT, FLOAT or BLOB
--drop TEXT Drop this column --drop TEXT Drop this column
@ -373,6 +411,10 @@ See :ref:`cli_extract`.
Extract one or more columns into a separate table Extract one or more columns into a separate table
Example:
sqlite-utils extract trees.db Street_Trees species
Options: Options:
--table TEXT Name of the other table to extract columns to --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 --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 Show full schema for this database or for specified tables
Example:
sqlite-utils schema trees.db
Options: Options:
--load-extension TEXT SQLite extensions to load --load-extension TEXT SQLite extensions to load
-h, --help Show this message and exit. -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 Insert one or more files using BLOB columns in the specified table
Example usage: Example:
sqlite-utils insert-files pics.db images *.gif \ sqlite-utils insert-files pics.db images *.gif \
-c name:name \ -c name:name \
-c content:content \ -c content:content \
-c content_hash:sha256 \ -c content_hash:sha256 \
-c created:ctime_iso \ -c created:ctime_iso \
-c modified:mtime_iso \ -c modified:mtime_iso \
-c size:size \ -c size:size \
--pk name --pk name
Options: Options:
-c, --column TEXT Column definitions for the table -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 Analyze the columns in one or more tables
Example:
sqlite-utils analyze-tables data.db trees
Options: Options:
-c, --column TEXT Specific columns to analyze -c, --column TEXT Specific columns to analyze
--save Save results to _analyze_tables table --save Save results to _analyze_tables table
@ -462,9 +512,9 @@ See :ref:`cli_convert`.
Convert columns using Python code you supply. For example: Convert columns using Python code you supply. For example:
$ sqlite-utils convert my.db mytable mycolumn \ sqlite-utils convert my.db mytable mycolumn \
'"\n".join(textwrap.wrap(value, 10))' \ '"\n".join(textwrap.wrap(value, 10))' \
--import=textwrap --import=textwrap
"value" is a variable with the column value to be converted. "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: You can use these recipes like so:
$ sqlite-utils convert my.db mytable mycolumn \ sqlite-utils convert my.db mytable mycolumn \
'r.jsonsplit(value, delimiter=":")' 'r.jsonsplit(value, delimiter=":")'
Options: Options:
--import TEXT Python modules to import --import TEXT Python modules to import
@ -517,6 +567,10 @@ See :ref:`cli_tables`.
List the tables in the database List the tables in the database
Example:
sqlite-utils tables trees.db
Options: Options:
--fts4 Just show FTS4 enabled tables --fts4 Just show FTS4 enabled tables
--fts5 Just show FTS5 enabled tables --fts5 Just show FTS5 enabled tables
@ -526,7 +580,7 @@ See :ref:`cli_tables`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,
@ -558,7 +612,7 @@ See :ref:`cli_views`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,
@ -594,7 +648,7 @@ See :ref:`cli_rows`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,
@ -623,7 +677,7 @@ See :ref:`cli_triggers`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,
@ -653,7 +707,7 @@ See :ref:`cli_indexes`.
--csv Output CSV --csv Output CSV
--tsv Output TSV --tsv Output TSV
--no-headers Omit CSV headers --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, --fmt TEXT Table format - one of fancy_grid, fancy_outline,
github, grid, html, jira, latex, latex_booktabs, github, grid, html, jira, latex, latex_booktabs,
latex_longtable, latex_raw, mediawiki, moinmoin, latex_longtable, latex_raw, mediawiki, moinmoin,

117
sqlite_utils/cli.py
View file

@ -75,7 +75,9 @@ def output_options(fn):
click.option("--csv", is_flag=True, help="Output CSV"), click.option("--csv", is_flag=True, help="Output CSV"),
click.option("--tsv", is_flag=True, help="Output TSV"), click.option("--tsv", is_flag=True, help="Output TSV"),
click.option("--no-headers", is_flag=True, help="Omit CSV headers"), 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( click.option(
"--fmt", "--fmt",
help="Table format - one of {}".format( help="Table format - one of {}".format(
@ -161,7 +163,13 @@ def tables(
load_extension, load_extension,
views=False, 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) db = sqlite_utils.Database(path)
_load_extensions(db, load_extension) _load_extensions(db, load_extension)
headers = ["view" if views else "table"] headers = ["view" if views else "table"]
@ -1001,7 +1009,11 @@ def insert(
Insert records from FILE into a table, creating the table if it Insert records from FILE into a table, creating the table if it
does not already exist. 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 \b
- Use --nl for newline-delimited JSON objects - 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 Upsert records based on their primary key. Works like 'insert' but if
an incoming record has a primary key that matches an existing record an incoming record has a primary key that matches an existing record
the existing record will be updated. 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: try:
insert_upsert_implementation( insert_upsert_implementation(
@ -1152,6 +1174,16 @@ def bulk(
): ):
""" """
Execute parameterized SQL against the provided list of documents. 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: try:
insert_upsert_implementation( insert_upsert_implementation(
@ -1402,7 +1434,15 @@ def query(
param, param,
load_extension, 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) db = sqlite_utils.Database(path)
for alias, attach_path in attach: for alias, attach_path in attach:
db.attach(alias, attach_path) db.attach(alias, attach_path)
@ -1665,7 +1705,12 @@ def search(
json_cols, json_cols,
load_extension, 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) db = sqlite_utils.Database(path)
_load_extensions(db, load_extension) _load_extensions(db, load_extension)
# Check table exists # Check table exists
@ -1912,7 +1957,13 @@ def schema(
tables, tables,
load_extension, 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) db = sqlite_utils.Database(path)
_load_extensions(db, load_extension) _load_extensions(db, load_extension)
if tables: if tables:
@ -1985,7 +2036,15 @@ def transform(
sql, sql,
load_extension, 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) db = sqlite_utils.Database(path)
_load_extensions(db, load_extension) _load_extensions(db, load_extension)
types = {} types = {}
@ -2060,7 +2119,13 @@ def extract(
rename, rename,
load_extension, 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) db = sqlite_utils.Database(path)
_load_extensions(db, load_extension) _load_extensions(db, load_extension)
kwargs = dict( kwargs = dict(
@ -2122,17 +2187,17 @@ def insert_files(
""" """
Insert one or more files using BLOB columns in the specified table Insert one or more files using BLOB columns in the specified table
Example usage: Example:
\b \b
sqlite-utils insert-files pics.db images *.gif \\ sqlite-utils insert-files pics.db images *.gif \\
-c name:name \\ -c name:name \\
-c content:content \\ -c content:content \\
-c content_hash:sha256 \\ -c content_hash:sha256 \\
-c created:ctime_iso \\ -c created:ctime_iso \\
-c modified:mtime_iso \\ -c modified:mtime_iso \\
-c size:size \\ -c size:size \\
--pk name --pk name
""" """
if not column: if not column:
if text: if text:
@ -2244,7 +2309,13 @@ def analyze_tables(
save, save,
load_extension, 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) db = sqlite_utils.Database(path)
_load_extensions(db, load_extension) _load_extensions(db, load_extension)
_analyze(db, tables, columns, save) _analyze(db, tables, columns, save)
@ -2308,9 +2379,9 @@ def _generate_convert_help():
Convert columns using Python code you supply. For example: Convert columns using Python code you supply. For example:
\b \b
$ sqlite-utils convert my.db mytable mycolumn \\ sqlite-utils convert my.db mytable mycolumn \\
'"\\n".join(textwrap.wrap(value, 10))' \\ '"\\n".join(textwrap.wrap(value, 10))' \\
--import=textwrap --import=textwrap
"value" is a variable with the column value to be converted. "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: You can use these recipes like so:
\b \b
$ sqlite-utils convert my.db mytable mycolumn \\ sqlite-utils convert my.db mytable mycolumn \\
'r.jsonsplit(value, delimiter=":")' 'r.jsonsplit(value, delimiter=":")'
""" """
).strip() ).strip()
return help return help