sqlite-utils rows --where and -p options, closes #382

Author: simonw

docs/cli-reference.rst

@@ -584,24 +584,26 @@ See :ref:`cli_rows`.
       Output all rows in the specified table
 
     Options:
-      -c, --column TEXT      Columns to return
-      --limit INTEGER        Number of rows to return - defaults to everything
-      --offset INTEGER       SQL offset to use
-      --nl                   Output newline-delimited JSON
-      --arrays               Output rows as arrays instead of objects
-      --csv                  Output CSV
-      --tsv                  Output TSV
-      --no-headers           Omit CSV headers
-      -t, --table            Output as a table
-      --fmt TEXT             Table format - one of fancy_grid, fancy_outline,
-                             github, grid, html, jira, latex, latex_booktabs,
-                             latex_longtable, latex_raw, mediawiki, moinmoin,
-                             orgtbl, pipe, plain, presto, pretty, psql, rst, simple,
-                             textile, tsv, unsafehtml, youtrack
-      --json-cols            Detect JSON cols and output them as JSON, not escaped
-                             strings
-      --load-extension TEXT  SQLite extensions to load
-      -h, --help             Show this message and exit.
+      -c, --column TEXT           Columns to return
+      --where TEXT                Optional where clause
+      -p, --param <TEXT TEXT>...  Named :parameters for where clause
+      --limit INTEGER             Number of rows to return - defaults to everything
+      --offset INTEGER            SQL offset to use
+      --nl                        Output newline-delimited JSON
+      --arrays                    Output rows as arrays instead of objects
+      --csv                       Output CSV
+      --tsv                       Output TSV
+      --no-headers                Omit CSV headers
+      -t, --table                 Output as a table
+      --fmt TEXT                  Table format - one of fancy_grid, fancy_outline,
+                                  github, grid, html, jira, latex, latex_booktabs,
+                                  latex_longtable, latex_raw, mediawiki, moinmoin,
+                                  orgtbl, pipe, plain, presto, pretty, psql, rst,
+                                  simple, textile, tsv, unsafehtml, youtrack
+      --json-cols                 Detect JSON cols and output them as JSON, not
+                                  escaped strings
+      --load-extension TEXT       SQLite extensions to load
+      -h, --help                  Show this message and exit.
 
 
 triggers

docs/cli.rst

@@ -449,6 +449,16 @@ You can use the ``-c`` option to specify a subset of columns to return::
     [{"age": 4, "name": "Cleo"},
      {"age": 2, "name": "Pancakes"}]
 
+You can filter rows using a where clause with the ``--where`` option::
+
+    $ sqlite-utils rows dogs.db dogs -c name --where 'name = "Cleo"'
+    [{"name": "Cleo"}]
+
+Or pass named parameters using ``--where`` in combination with ``-p``::
+
+    $ sqlite-utils rows dogs.db dogs -c name --where 'name = :name' -p name Cleo
+    [{"name": "Cleo"}]
+
 Use ``--limit N`` to only return the first ``N`` rows. Use ``--offset N`` to return rows starting from the specified offset.
 
 .. _cli_tables:

sqlite_utils/cli.py

@@ -1723,6 +1723,14 @@ def search(
 )
 @click.argument("dbtable")
 @click.option("-c", "--column", type=str, multiple=True, help="Columns to return")
+@click.option("--where", help="Optional where clause")
+@click.option(
+    "-p",
+    "--param",
+    multiple=True,
+    type=(str, str),
+    help="Named :parameters for where clause",
+)
 @click.option(
     "--limit",
     type=int,
@@ -1741,6 +1749,8 @@ def rows(
     path,
     dbtable,
     column,
+    where,
+    param,
     limit,
     offset,
     nl,
@@ -1758,6 +1768,8 @@ def rows(
     if column:
         columns = ", ".join("[{}]".format(c) for c in column)
     sql = "select {} from [{}]".format(columns, dbtable)
+    if where:
+        sql += " where " + where
     if limit:
         sql += " limit {}".format(limit)
     if offset:
@@ -1773,6 +1785,7 @@ def rows(
         no_headers=no_headers,
         table=table,
         fmt=fmt,
+        param=param,
         json_cols=json_cols,
         load_extension=load_extension,
     )

tests/test_cli.py

@@ -851,6 +851,7 @@ def test_query_memory_does_not_create_file(tmpdir):
             ["--nl", "-c", "age", "-c", "name"],
             '{"age": 4, "name": "Cleo"}\n{"age": 2, "name": "Pancakes"}',
         ),
+        # --limit and --offset
         (
             ["-c", "name", "--limit", "1"],
             '[{"name": "Cleo"}]',
@@ -859,6 +860,19 @@ def test_query_memory_does_not_create_file(tmpdir):
             ["-c", "name", "--limit", "1", "--offset", "1"],
             '[{"name": "Pancakes"}]',
         ),
+        # --where
+        (
+            ["-c", "name", "--where", "id = 1"],
+            '[{"name": "Cleo"}]',
+        ),
+        (
+            ["-c", "name", "--where", "id = :id", "-p", "id", "1"],
+            '[{"name": "Cleo"}]',
+        ),
+        (
+            ["-c", "name", "--where", "id = :id", "--param", "id", "1"],
+            '[{"name": "Cleo"}]',
+        ),
     ],
 )
 def test_rows(db_path, args, expected):