Skip to content

Commit 6e85a4b

Browse files
simonwsimonw
committed
Added examples to more --help output, refs #384 
1 parent 25d8c82 commit 6e85a4b

File tree

2 files changed

+171
-46
lines changed

2 files changed

+171
-46
lines changed

‎docs/cli-reference.rst‎

Lines changed: 77 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,12 @@ See :ref:`cli_query`.
8585

8686
Execute SQL query and return the results as JSON
8787

88+
Example:
89+
90+
sqlite-utils data.db \
91+
"select * from chickens where age > :age" \
92+
-p age 1
93+
8894
Options:
8995
--attach <TEXT FILE>... Additional databases to attach - specify alias and
9096
filepath
@@ -93,7 +99,7 @@ See :ref:`cli_query`.
9399
--csv Output CSV
94100
--tsv Output TSV
95101
--no-headers Omit CSV headers
96-
-t, --table Output as a table
102+
-t, --table Output as a formatted table
97103
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
98104
github, grid, html, jira, latex, latex_booktabs,
99105
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -150,7 +156,7 @@ See :ref:`cli_memory`.
150156
--csv Output CSV
151157
--tsv Output TSV
152158
--no-headers Omit CSV headers
153-
-t, --table Output as a table
159+
-t, --table Output as a formatted table
154160
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
155161
github, grid, html, jira, latex, latex_booktabs,
156162
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -183,7 +189,11 @@ See :ref:`cli_inserting_data`, :ref:`cli_insert_csv_tsv`.
183189
Insert records from FILE into a table, creating the table if it does not
184190
already exist.
185191

186-
By default the input is expected to be a JSON array of objects. Or:
192+
Example:
193+
194+
echo '{"name": "Lila"}' | sqlite-utils insert data.db chickens -
195+
196+
By default the input is expected to be a JSON object or array of objects.
187197

188198
- Use --nl for newline-delimited JSON objects
189199
- Use --csv or --tsv for comma-separated or tab-separated input
@@ -243,6 +253,15 @@ See :ref:`cli_upsert`.
243253
incoming record has a primary key that matches an existing record the existing
244254
record will be updated.
245255

256+
The --pk option is required.
257+
258+
Example:
259+
260+
echo '[
261+
{"id": 1, "name": "Lila"},
262+
{"id": 2, "name": "Suna"}
263+
]' | sqlite-utils upsert data.db chickens - --pk id
264+
246265
Options:
247266
--pk TEXT Columns to use as the primary key, e.g. id
248267
--flatten Flatten nested JSON objects, so {"a": {"b": 1}}
@@ -281,6 +300,15 @@ See :ref:`cli_bulk`.
281300

282301
Execute parameterized SQL against the provided list of documents.
283302

303+
Example:
304+
305+
echo '[
306+
{"id": 1, "name": "Lila2"},
307+
{"id": 2, "name": "Suna2"}
308+
]' | sqlite-utils bulk data.db '
309+
update chickens set name = :name where id = :id
310+
' -
311+
284312
Options:
285313
--flatten Flatten nested JSON objects, so {"a": {"b": 1}} becomes
286314
{"a_b": 1}
@@ -311,6 +339,10 @@ See :ref:`cli_search`.
311339

312340
Execute a full-text search against this table
313341

342+
Example:
343+
344+
sqlite-utils search data.db chickens lila
345+
314346
Options:
315347
-o, --order TEXT Order by ('column' or 'column desc')
316348
-c, --column TEXT Columns to return
@@ -322,7 +354,7 @@ See :ref:`cli_search`.
322354
--csv Output CSV
323355
--tsv Output TSV
324356
--no-headers Omit CSV headers
325-
-t, --table Output as a table
357+
-t, --table Output as a formatted table
326358
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
327359
github, grid, html, jira, latex, latex_booktabs,
328360
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -345,6 +377,12 @@ See :ref:`cli_transform_table`.
345377

346378
Transform a table beyond the capabilities of ALTER TABLE
347379

380+
Example:
381+
382+
sqlite-utils transform mydb.db mytable \
383+
--drop column1 \
384+
--rename column2 column_renamed
385+
348386
Options:
349387
--type <TEXT CHOICE>... Change column type to INTEGER, TEXT, FLOAT or BLOB
350388
--drop TEXT Drop this column
@@ -373,6 +411,10 @@ See :ref:`cli_extract`.
373411

374412
Extract one or more columns into a separate table
375413

414+
Example:
415+
416+
sqlite-utils extract trees.db Street_Trees species
417+
376418
Options:
377419
--table TEXT Name of the other table to extract columns to
378420
--fk-column TEXT Name of the foreign key column to add to the table
@@ -392,6 +434,10 @@ See :ref:`cli_schema`.
392434

393435
Show full schema for this database or for specified tables
394436

437+
Example:
438+
439+
sqlite-utils schema trees.db
440+
395441
Options:
396442
--load-extension TEXT SQLite extensions to load
397443
-h, --help Show this message and exit.
@@ -408,16 +454,16 @@ See :ref:`cli_insert_files`.
408454

409455
Insert one or more files using BLOB columns in the specified table
410456

411-
Example usage:
457+
Example:
412458

413-
sqlite-utils insert-files pics.db images *.gif \
414-
-c name:name \
415-
-c content:content \
416-
-c content_hash:sha256 \
417-
-c created:ctime_iso \
418-
-c modified:mtime_iso \
419-
-c size:size \
420-
--pk name
459+
sqlite-utils insert-files pics.db images *.gif \
460+
-c name:name \
461+
-c content:content \
462+
-c content_hash:sha256 \
463+
-c created:ctime_iso \
464+
-c modified:mtime_iso \
465+
-c size:size \
466+
--pk name
421467

422468
Options:
423469
-c, --column TEXT Column definitions for the table
@@ -444,6 +490,10 @@ See :ref:`cli_analyze_tables`.
444490

445491
Analyze the columns in one or more tables
446492

493+
Example:
494+
495+
sqlite-utils analyze-tables data.db trees
496+
447497
Options:
448498
-c, --column TEXT Specific columns to analyze
449499
--save Save results to _analyze_tables table
@@ -462,9 +512,9 @@ See :ref:`cli_convert`.
462512

463513
Convert columns using Python code you supply. For example:
464514

465-
$ sqlite-utils convert my.db mytable mycolumn \
466-
'"\n".join(textwrap.wrap(value, 10))' \
467-
--import=textwrap
515+
sqlite-utils convert my.db mytable mycolumn \
516+
'"\n".join(textwrap.wrap(value, 10))' \
517+
--import=textwrap
468518

469519
"value" is a variable with the column value to be converted.
470520

@@ -486,8 +536,8 @@ See :ref:`cli_convert`.
486536

487537
You can use these recipes like so:
488538

489-
$ sqlite-utils convert my.db mytable mycolumn \
490-
'r.jsonsplit(value, delimiter=":")'
539+
sqlite-utils convert my.db mytable mycolumn \
540+
'r.jsonsplit(value, delimiter=":")'
491541

492542
Options:
493543
--import TEXT Python modules to import
@@ -517,6 +567,10 @@ See :ref:`cli_tables`.
517567

518568
List the tables in the database
519569

570+
Example:
571+
572+
sqlite-utils tables trees.db
573+
520574
Options:
521575
--fts4 Just show FTS4 enabled tables
522576
--fts5 Just show FTS5 enabled tables
@@ -526,7 +580,7 @@ See :ref:`cli_tables`.
526580
--csv Output CSV
527581
--tsv Output TSV
528582
--no-headers Omit CSV headers
529-
-t, --table Output as a table
583+
-t, --table Output as a formatted table
530584
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
531585
github, grid, html, jira, latex, latex_booktabs,
532586
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -558,7 +612,7 @@ See :ref:`cli_views`.
558612
--csv Output CSV
559613
--tsv Output TSV
560614
--no-headers Omit CSV headers
561-
-t, --table Output as a table
615+
-t, --table Output as a formatted table
562616
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
563617
github, grid, html, jira, latex, latex_booktabs,
564618
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -594,7 +648,7 @@ See :ref:`cli_rows`.
594648
--csv Output CSV
595649
--tsv Output TSV
596650
--no-headers Omit CSV headers
597-
-t, --table Output as a table
651+
-t, --table Output as a formatted table
598652
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
599653
github, grid, html, jira, latex, latex_booktabs,
600654
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -623,7 +677,7 @@ See :ref:`cli_triggers`.
623677
--csv Output CSV
624678
--tsv Output TSV
625679
--no-headers Omit CSV headers
626-
-t, --table Output as a table
680+
-t, --table Output as a formatted table
627681
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
628682
github, grid, html, jira, latex, latex_booktabs,
629683
latex_longtable, latex_raw, mediawiki, moinmoin,
@@ -653,7 +707,7 @@ See :ref:`cli_indexes`.
653707
--csv Output CSV
654708
--tsv Output TSV
655709
--no-headers Omit CSV headers
656-
-t, --table Output as a table
710+
-t, --table Output as a formatted table
657711
--fmt TEXT Table format - one of fancy_grid, fancy_outline,
658712
github, grid, html, jira, latex, latex_booktabs,
659713
latex_longtable, latex_raw, mediawiki, moinmoin,

0 commit comments

Comments
 (0)