Skip to content

Commit 7b2d484

Browse files
Erlend Egeberg Aaslandmiss-islington
authored andcommitted
bpo-46402: Promote SQLite URI tricks in sqlite3 docs (pythonGH-30660)
Provide some examples of URI parameters in sqlite connect(). Co-authored-by: Ned Batchelder <[email protected]> (cherry picked from commit bdf2ab1) Co-authored-by: Erlend Egeberg Aasland <[email protected]>
1 parent 42038d0 commit 7b2d484

File tree

1 file changed

+22
-8
lines changed

1 file changed

+22
-8
lines changed

Doc/library/sqlite3.rst

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -255,14 +255,28 @@ Module functions and constants
255255
for the connection, you can set the *cached_statements* parameter. The currently
256256
implemented default is to cache 100 statements.
257257

258-
If *uri* is true, *database* is interpreted as a URI. This allows you
259-
to specify options. For example, to open a database in read-only mode
260-
you can use::
261-
262-
db = sqlite3.connect('file:path/to/database?mode=ro', uri=True)
263-
264-
More information about this feature, including a list of recognized options, can
265-
be found in the `SQLite URI documentation <https://www.sqlite.org/uri.html>`_.
258+
If *uri* is :const:`True`, *database* is interpreted as a
259+
:abbr:`URI (Uniform Resource Identifier)` with a file path and an optional
260+
query string. The scheme part *must* be ``"file:"``. The path can be a
261+
relative or absolute file path. The query string allows us to pass
262+
parameters to SQLite. Some useful URI tricks include::
263+
264+
# Open a database in read-only mode.
265+
con = sqlite3.connect("file:template.db?mode=ro", uri=True)
266+
267+
# Don't implicitly create a new database file if it does not already exist.
268+
# Will raise sqlite3.OperationalError if unable to open a database file.
269+
con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
270+
271+
# Create a shared named in-memory database.
272+
con1 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
273+
con2 = sqlite3.connect("file:mem1?mode=memory&cache=shared", uri=True)
274+
con1.executescript("create table t(t); insert into t values(28);")
275+
rows = con2.execute("select * from t").fetchall()
276+
277+
More information about this feature, including a list of recognized
278+
parameters, can be found in the
279+
`SQLite URI documentation <https://www.sqlite.org/uri.html>`_.
266280

267281
.. audit-event:: sqlite3.connect database sqlite3.connect
268282
.. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect

0 commit comments

Comments
 (0)