From 4c14a65343cc7cfd64ab47358ac9045426d1085c Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Tue, 18 Jan 2022 13:37:02 +0100 Subject: [PATCH] bpo-46402: Promote SQLite URI tricks in `sqlite3` docs (GH-30660) Provide some examples of URI parameters in sqlite connect(). Co-authored-by: Ned Batchelder (cherry picked from commit bdf2ab1887a2edfb089a3c2a1590cf1e84ea0048) Co-authored-by: Erlend Egeberg Aasland --- Doc/library/sqlite3.rst | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 0ffb8ff0b969c9..e50928a3845c46 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -254,14 +254,28 @@ Module functions and constants for the connection, you can set the *cached_statements* parameter. The currently implemented default is to cache 100 statements. - If *uri* is true, *database* is interpreted as a URI. This allows you - to specify options. For example, to open a database in read-only mode - you can use:: - - db = sqlite3.connect('file:path/to/database?mode=ro', uri=True) - - More information about this feature, including a list of recognized options, can - be found in the `SQLite URI documentation `_. + If *uri* is :const:`True`, *database* is interpreted as a + :abbr:`URI (Uniform Resource Identifier)` with a file path and an optional + query string. The scheme part *must* be ``"file:"``. The path can be a + relative or absolute file path. The query string allows us to pass + parameters to SQLite. Some useful URI tricks include:: + + # Open a database in read-only mode. + con = sqlite3.connect("file:template.db?mode=ro", uri=True) + + # Don't implicitly create a new database file if it does not already exist. + # Will raise sqlite3.OperationalError if unable to open a database file. + con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True) + + # Create a shared named in-memory database. + con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True) + con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True) + con1.executescript("create table t(t); insert into t values(28);") + rows = con2.execute("select * from t").fetchall() + + More information about this feature, including a list of recognized + parameters, can be found in the + `SQLite URI documentation `_. .. audit-event:: sqlite3.connect database sqlite3.connect