Addd SQLite URI support to CLI

create_demo_db.py

@@ -0,0 +1,23 @@
+import os
+import sqlite3
+
+# Remove any existing demo.db so we start fresh
+if os.path.exists("demo.db"):
+    os.remove("demo.db")
+
+conn = sqlite3.connect("demo.db")
+conn.executescript("""
+CREATE TABLE IF NOT EXISTS movies (
+    id INTEGER PRIMARY KEY,
+    title TEXT,
+    year INTEGER,
+    genre TEXT
+);
+INSERT INTO movies VALUES (1, 'Inception', 2010, 'Sci-Fi');
+INSERT INTO movies VALUES (2, 'The Matrix', 1999, 'Sci-Fi');
+INSERT INTO movies VALUES (3, 'Interstellar', 2014, 'Sci-Fi');
+""")
+conn.commit()
+conn.close()
+print("demo.db created successfully")
+

docs/cli.rst

@@ -8,6 +8,18 @@ The ``sqlite-utils`` command-line tool can be used to manipulate SQLite database
 
 Once :ref:`installed <installation>` the tool should be available as ``sqlite-utils``. It can also be run using ``python -m sqlite_utils``.
 
+All CLI arguments that refer to a database accept `SQLite URI filenames
+<https://www.sqlite.org/uri.html>`__ as well as regular paths. For example, to
+query a database that will not change while it is open:
+
+.. code-block:: bash
+
+    sqlite-utils query 'file:foo.db?immutable=1' "select * from bar"
+
+SQLite URI options such as ``mode=ro`` are interpreted by SQLite. In particular,
+``immutable=1`` tells SQLite that the database file cannot change; do not use it
+for files that may be modified while the connection is open.
+
 .. contents:: :local:
    :class: this-will-duplicate-information-and-it-is-still-useful-here
 

docs/python-api.rst

@@ -81,6 +81,12 @@ Database objects are constructed by passing in either a path to a file on disk o
 
 This will create ``my_database.db`` if it does not already exist.
 
+SQLite URI filenames can also be passed in place of a regular path. For example,
+``Database("file:my_database.db?mode=ro")`` opens a database read-only. See the
+`SQLite URI documentation <https://www.sqlite.org/uri.html>`__ for supported
+options. ``immutable=1`` should only be used when the database cannot change
+while the connection is open.
+
 If you want to recreate a database from scratch (first removing the existing file from disk if it already exists) you can use the ``recreate=True`` argument:
 
 .. code-block:: python