Mailing List Archive

https://github.com/python/cpython/commit/bdf2ab1887a2edfb089a3c2a1590cf1e84ea0048
commit: bdf2ab1887a2edfb089a3c2a1590cf1e84ea0048
branch: main
author: Erlend Egeberg Aasland <erlend.aasland@innova.no>
committer: ericvsmith <ericvsmith@users.noreply.github.com>
date: 2022-01-18T07:37:02-05:00
summary:

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 <ned@nedbatchelder.com>

files:
M Doc/library/sqlite3.rst

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 415a5f9a92902..d213933ba5827 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -273,14 +273,28 @@ Module functions and constants
for the connection, you can set the *cached_statements* parameter. The currently
implemented default is to cache 128 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 <https://www.sqlite.org/uri.html>`_.
+ 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 <https://www.sqlite.org/uri.html>`_.

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

_______________________________________________
Python-checkins mailing list
Python-checkins@python.org
https://mail.python.org/mailman/listinfo/python-checkins