Skip to content

tables and views commands accept optional table/view names (#478) - #845

Open
ChrisJr404 wants to merge 1 commit into
simonw:mainfrom
ChrisJr404:tables-filter-by-name
Open

tables and views commands accept optional table/view names (#478)#845
ChrisJr404 wants to merge 1 commit into
simonw:mainfrom
ChrisJr404:tables-filter-by-name

Conversation

@ChrisJr404

@ChrisJr404 ChrisJr404 commented Aug 18, 2026

Copy link
Copy Markdown

Adds an optional list of table (or view) names to the tables and views commands so you can restrict the output to just the tables you care about, rather than always listing everything. This addresses #478.

The motivating case from the issue is --counts against a database that contains one very large table: counting every table is expensive, so being able to say sqlite-utils tables data.db small1 small2 --counts and skip the big one is useful.

sqlite-utils tables mydb.db dogs cats --counts
[{"table": "dogs", "count": 12},
 {"table": "cats", "count": 332}]

Names are output in the order they are passed. Following the suggestion in the issue that this should error rather than fail silently, an unknown name raises a ClickException and exits non-zero, so the exit code can be used to confirm that a set of expected tables (or views) exists:

$ sqlite-utils tables mydb.db dogs nope
Error: The following table does not exist: nope
$ echo $?
1

The views command shares the tables callback, so it picks up the same behaviour against view names.

The change is backwards compatible: with no names passed, both commands behave exactly as before.

I added tests covering filtering, argument-order preservation, combining names with --counts, and the single/multiple missing-name error messages for both commands. The docs (docs/cli.rst) and the cog-generated docs/cli-reference.rst are updated. black, flake8, mypy, pyright and cog --check all pass, and the full tests/test_cli.py suite is green.


📚 Documentation preview 📚: https://sqlite-utils--845.org.readthedocs.build/en/845/

The tables and views commands now take one or more optional table (or view)
names as positional arguments after the database path, restricting the output
to just those tables. This is handy with --counts against a database that has
a large table you would rather skip.

Names are listed in the order they are passed. If any named table or view does
not exist the command raises an error and exits with a non-zero status, so the
exit code can be used to confirm a set of expected tables is present.

Closes simonw#478
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant