SQLAlchemy 2.0.51__py3-none-any.whl → 2.0.53__py3-none-any.whl

sqlalchemy/__init__.py

@@ -269,7 +269,7 @@ from .types import Uuid as Uuid
 from .types import VARBINARY as VARBINARY
 from .types import VARCHAR as VARCHAR
 
-__version__ = "2.0.51"
+__version__ = "2.0.53"
 
 
 def __go(lcls: Any) -> None:

sqlalchemy/connectors/pyodbc.py

@@ -77,10 +77,16 @@ class PyODBCConnector(Connector):
         else:
 
             def check_quote(token: str) -> str:
-                if ";" in str(token) or str(token).startswith("{"):
+                if (
+                    ";" in str(token)
+                    or "}" in str(token)
+                    or str(token).startswith("{")
+                ):
                     token = "{%s}" % token.replace("}", "}}")
                 return token
 
+            driver = keys.pop("driver", self.pyodbc_driver_name)
+
             keys = {k: check_quote(v) for k, v in keys.items()}
 
             dsn_connection = "dsn" in keys or (
@@ -96,7 +102,6 @@ class PyODBCConnector(Connector):
                     port = ",%d" % int(keys.pop("port"))
 
                 connectors = []
-                driver = keys.pop("driver", self.pyodbc_driver_name)
                 if driver is None and keys:
                     # note if keys is empty, this is a totally blank URL
                     util.warn(
@@ -105,7 +110,9 @@ class PyODBCConnector(Connector):
                         "DSN-less connections"
                     )
                 else:
-                    connectors.append("DRIVER={%s}" % driver)
+                    connectors.append(
+                        "DRIVER={%s}" % str(driver).replace("}", "}}")
+                    )
 
                 connectors.extend(
                     [
@@ -136,7 +143,9 @@ class PyODBCConnector(Connector):
                     "AutoTranslate=%s" % keys.pop("odbc_autotranslate")
                 )
 
-            connectors.extend(["%s=%s" % (k, v) for k, v in keys.items()])
+            connectors.extend(
+                ["%s=%s" % (check_quote(k), v) for k, v in keys.items()]
+            )
 
         return ((";".join(connectors),), connect_args)
 

sqlalchemy/dialects/mssql/base.py

@@ -1585,7 +1585,7 @@ class MSUUid(sqltypes.Uuid):
         if self.native_uuid:
 
             def process(value):
-                return f"""'{str(value).replace("''", "'")}'"""
+                return f"""'{str(value).replace("'", "''")}'"""
 
             return process
         else:
@@ -3780,7 +3780,6 @@ order by
             elif coltype in (
                 MSString,
                 MSChar,
-                MSText,
             ):
                 kwargs["length"] = maxlen if maxlen != -1 else None
                 if collation:
@@ -3788,11 +3787,20 @@ order by
             elif coltype in (
                 MSNVarchar,
                 MSNChar,
-                MSNText,
             ):
                 kwargs["length"] = maxlen // 2 if maxlen != -1 else None
                 if collation:
                     kwargs["collation"] = collation
+            elif coltype in (
+                MSText,
+                MSNText,
+            ):
+                # TEXT / NTEXT are unlengthed LOB types.
+                # sys.columns.max_length reports 16 for these, which is the
+                # size of the in-row LOB pointer and not a character length,
+                # so no length is applied.
+                if collation:
+                    kwargs["collation"] = collation
 
             if coltype is None:
                 if base_type is not None and base_type != type_:

sqlalchemy/dialects/mysql/base.py

@@ -2105,8 +2105,8 @@ class MySQLDDLCompiler(compiler.DDLCompiler):
             "SUBPARTITION_BY",
         ]
 
-        nonpart_options = set(opts).difference(partition_options)
-        part_options = set(opts).intersection(partition_options)
+        nonpart_options = util.OrderedSet(opts).difference(partition_options)
+        part_options = util.OrderedSet(opts).intersection(partition_options)
 
         for opt in topological.sort(
             [

sqlalchemy/dialects/oracle/oracledb.py

@@ -602,6 +602,7 @@ from ... import pool
 from ...connectors.asyncio import AsyncAdapt_dbapi_connection
 from ...connectors.asyncio import AsyncAdapt_dbapi_cursor
 from ...connectors.asyncio import AsyncAdapt_dbapi_ss_cursor
+from ...connectors.asyncio import AsyncAdapt_terminate
 from ...connectors.asyncio import AsyncAdaptFallback_dbapi_connection
 from ...engine import default
 from ...util import asbool
@@ -795,7 +796,9 @@ class AsyncAdapt_oracledb_ss_cursor(
             self._cursor = None  # type: ignore
 
 
-class AsyncAdapt_oracledb_connection(AsyncAdapt_dbapi_connection):
+class AsyncAdapt_oracledb_connection(
+    AsyncAdapt_terminate, AsyncAdapt_dbapi_connection
+):
     _connection: AsyncConnection
     __slots__ = ()
 
@@ -860,6 +863,12 @@ class AsyncAdapt_oracledb_connection(AsyncAdapt_dbapi_connection):
     def tpc_rollback(self, *args: Any, **kwargs: Any) -> Any:
         return self.await_(self._connection.tpc_rollback(*args, **kwargs))
 
+    async def _terminate_graceful_close(self) -> None:
+        await self._connection.close()
+
+    def _terminate_force_close(self) -> None:
+        self._connection.terminate()
+
 
 class AsyncAdaptFallback_oracledb_connection(
     AsyncAdaptFallback_dbapi_connection, AsyncAdapt_oracledb_connection
@@ -918,6 +927,11 @@ class OracleDialectAsync_oracledb(OracleDialect_oracledb):
 
     _min_version = (2,)
 
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+        self.has_terminate = self.oracledb_ver >= (26, 0, 0)
+
     # thick_mode mode is not supported by asyncio, oracledb will raise
     @classmethod
     def import_dbapi(cls):
@@ -937,6 +951,12 @@ class OracleDialectAsync_oracledb(OracleDialect_oracledb):
     def get_driver_connection(self, connection):
         return connection._connection
 
+    def do_terminate(self, dbapi_connection) -> None:
+        if self.has_terminate:
+            dbapi_connection.terminate()
+        else:
+            super().do_terminate(dbapi_connection)
+
 
 dialect = OracleDialect_oracledb
 dialect_async = OracleDialectAsync_oracledb

sqlalchemy/dialects/postgresql/base.py

@@ -1213,6 +1213,33 @@ identifier::
         ),
     )
 
+SQLAlchemy does not automatically copy the columns from the inherited tables
+mentioned in the ``postgresql_inherits`` argument into the new
+:class:`_schema.Table`. To populate the new table columns reflection may be
+used, or a function similar to the following one::
+
+    def get_parent_columns(tbl: sa.Table) -> list[sa.Column]:
+        return [
+            sa.Column(
+                c.name,
+                c.type,
+                key=c.key,
+                nullable=c.nullable,
+                # Set system=true to omit from the CREATE TABLE statement
+                system=True,
+            )
+            for c in tbl.columns
+        ]
+
+
+    documents = Table(
+        "some_table",
+        metadata,
+        *get_parent_columns(some_supertable),
+        # ... # add other columns here normally if needed
+        postgresql_inherits="some_supertable",
+    )
+
 ``ON COMMIT``
 ^^^^^^^^^^^^^
 
@@ -2135,7 +2162,9 @@ class PGCompiler(compiler.SQLCompiler):
         return "string_agg%s" % self.function_argspec(fn)
 
     def visit_sequence(self, seq, **kw):
-        return "nextval('%s')" % self.preparer.format_sequence(seq)
+        return "nextval(%s)" % self.preparer._format_sequence_string_literal(
+            seq
+        )
 
     def limit_clause(self, select, **kw):
         text = ""
@@ -2968,9 +2997,43 @@ class PGTypeCompiler(compiler.GenericTypeCompiler):
         return "JSONPATH"
 
 
+class _CompilerSequence:
+    """Minimal stand-in for :class:`.Sequence`.
+
+    Used for the implicit sequence behind a SERIAL column, where no
+    :class:`.Sequence` object exists but a name still has to be rendered
+    through :meth:`.IdentifierPreparer.format_sequence`.
+
+    """
+
+    __slots__ = ("name", "schema")
+
+    # the schema handed to us has already been resolved against the
+    # schema translate map, so don't let format_sequence() translate it
+    # a second time
+    _use_schema_map = False
+
+    def __init__(self, name, schema=None):
+        self.name = name
+        self.schema = schema
+
+
 class PGIdentifierPreparer(compiler.IdentifierPreparer):
     reserved_words = RESERVED_WORDS
 
+    def _format_sequence_string_literal(self, sequence):
+        """Render a sequence name as a SQL string literal.
+
+        ``nextval()`` and friends take the sequence as a string rather than
+        as an identifier, so the quoted identifier produced by
+        :meth:`.format_sequence` has to be escaped a second time for the
+        enclosing literal.
+
+        """
+        return "'%s'" % self.format_sequence(
+            sequence, use_schema=True
+        ).replace("'", "''")
+
     def _unquote_identifier(self, value):
         if value[0] == self.initial_quote:
             value = value[1:-1].replace(
@@ -3156,8 +3219,8 @@ class PGExecutionContext(default.DefaultExecutionContext):
     def fire_sequence(self, seq, type_):
         return self._execute_scalar(
             (
-                "select nextval('%s')"
-                % self.identifier_preparer.format_sequence(seq)
+                "select nextval(%s)"
+                % self.identifier_preparer._format_sequence_string_literal(seq)
             ),
             type_,
         )
@@ -3194,13 +3257,12 @@ class PGExecutionContext(default.DefaultExecutionContext):
                 else:
                     effective_schema = None
 
-                if effective_schema is not None:
-                    exc = 'select nextval(\'"%s"."%s"\')' % (
-                        effective_schema,
-                        seq_name,
+                exc = (
+                    "select nextval(%s)"
+                    % self.identifier_preparer._format_sequence_string_literal(
+                        _CompilerSequence(seq_name, effective_schema)
                     )
-                else:
-                    exc = "select nextval('\"%s\"')" % (seq_name,)
+                )
 
                 return self._execute_scalar(exc, column.type)
 
@@ -3692,7 +3754,11 @@ class PGDialect(default.DefaultDialect):
     def get_schema_names(self, connection, **kw):
         query = (
             select(pg_catalog.pg_namespace.c.nspname)
-            .where(pg_catalog.pg_namespace.c.nspname.not_like("pg_%"))
+            .where(
+                ~pg_catalog.pg_namespace.c.nspname.startswith(
+                    "pg_", autoescape=True
+                )
+            )
             .order_by(pg_catalog.pg_namespace.c.nspname)
         )
         return connection.scalars(query).all()
@@ -5229,9 +5295,7 @@ class PGDialect(default.DefaultDialect):
                 util.warn("Could not parse CHECK constraint text: %r" % src)
                 sqltext = ""
             else:
-                sqltext = re.compile(
-                    r"^[\s\n]*\((.+)\)[\s\n]*$", flags=re.DOTALL
-                ).sub(r"\1", m.group(1))
+                sqltext = util.strip_outer_parens(m.group(1))
             entry = {
                 "name": check_name,
                 "sqltext": sqltext,

sqlalchemy/dialects/postgresql/json.py

@@ -49,6 +49,9 @@ class JSONPathType(sqltypes.JSON.JSONPathType):
             if isinstance(value, str):
                 # If it's already a string assume that it's in json path
                 # format. This allows using cast with json paths literals
+                # Still need to process through super_proc for proper escaping
+                if super_proc:
+                    value = super_proc(value)
                 return value
             elif value:
                 # If it's already a string assume that it's in json path

sqlalchemy/dialects/sqlite/aiosqlite.py

@@ -76,6 +76,36 @@ based on the kind of SQLite database that's requested:
     may be used by specifying it via the
     :paramref:`_sa.create_engine.poolclass` parameter.
 
+.. _aiosqlite_memory:
+
+Using a Memory Database with Multiple Coroutines
+-------------------------------------------------
+
+The default :class:`.StaticPool` used for ``:memory:`` databases forces all
+coroutines to share a single DBAPI connection.  Because SQLite maintains only
+one transaction state per connection, concurrent coroutines can interfere
+with each other — a ``ROLLBACK`` in one coroutine will also discard
+uncommitted work from any other coroutine using the same engine.
+
+For async workloads where multiple :class:`.AsyncSession` or
+:class:`.AsyncConnection` objects may be active simultaneously, use SQLite's
+shared-cache URI mode instead.  This gives each checkout its own DBAPI
+connection with independent transaction state while still sharing one
+in-memory database::
+
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///file::memory:?cache=shared&uri=true"
+    )
+
+Because this URL form is treated as a file-based database by the dialect,
+:class:`.AsyncAdaptedQueuePool` is used automatically and no additional
+configuration is needed.
+
+See the pysqlite documentation at
+:ref:`pysqlite_uri_shared_cache` for full details on shared-cache memory
+databases, including how to use named databases to maintain multiple
+independent in-memory databases within the same process.
+
 """  # noqa
 
 from __future__ import annotations

sqlalchemy/dialects/sqlite/base.py

@@ -949,6 +949,15 @@ dialect in conjunction with the :class:`_schema.Table` construct:
 
   .. versionadded:: 2.0.37
 
+Both options are also reflected, so that a :class:`_schema.Table` which is
+autoloaded from a database that was created using either keyword will render
+that keyword again when the table is recreated.  The reflected values are
+also available directly from
+:meth:`_engine.Inspector.get_table_options`.
+
+.. versionadded:: 2.0.53  Added reflection support for the ``WITHOUT ROWID``
+   and ``STRICT`` table options.
+
 .. seealso::
 
     `SQLite CREATE TABLE options
@@ -1128,7 +1137,7 @@ class DATETIME(_DateTimeMixin, sqltypes.DateTime):
             storage_format=(
                 "%(year)04d/%(month)02d/%(day)02d %(hour)02d:%(minute)02d:%(second)02d"
             ),
-            regexp=r"(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)",
+            regexp=r"(\d+)/(\d+)/(\d+) (\d+):(\d+):(\d+)",
         )
 
     :param truncate_microseconds: when ``True`` microseconds will be truncated
@@ -2067,6 +2076,37 @@ class SQLiteExecutionContext(default.DefaultExecutionContext):
             return colname, None
 
 
+# regexp that locates a FOREIGN KEY clause within the verbatim CREATE TABLE
+# text that sqlite stores in sqlite_master.  the referred-columns group
+# requires a non-empty separator between column tokens; an earlier form made
+# the separator optional, which turned the repeat into a nested quantifier and
+# let a long word run backtrack exponentially.  kept at module level so it can
+# be exercised directly from the tests.
+FK_PATTERN = re.compile(
+    r'(?:CONSTRAINT\s+(?:"(.+?)"|(\w+))\s+)?'
+    r"FOREIGN\s+KEY\s*\(\s*(.+?)\s*\)\s+"
+    r'REFERENCES\s+(?:(?:"(.+?)")|([a-z0-9_]+))\s*\(\s*((?:"[^"]+"|[a-z0-9_]+)(?:(?:\s*,\s*|\s+)(?:"[^"]+"|[a-z0-9_]+))*\s*)\)\s*'  # noqa: E501
+    r"((?:ON\s+(?:DELETE|UPDATE)\s+"
+    r"(?:SET\s+NULL|SET\s+DEFAULT|CASCADE|RESTRICT|"
+    r"NO\s+ACTION)\s*)*)"
+    r"((?:NOT\s+)?DEFERRABLE)?"
+    r"(?:\s+INITIALLY\s+(DEFERRED|IMMEDIATE))?",
+    re.I,
+)
+
+# regexp that locates the table option keywords which may trail the closing
+# paren of the column list in the verbatim CREATE TABLE text.  the match is
+# anchored at the end of the statement, which makes the closing paren
+# unambiguous, as neither keyword can itself contain one.  the keywords may
+# be given in either order; as each may appear only once, the repeated group
+# leaves one named group per keyword holding the text that was matched.
+TABLE_OPTIONS_PATTERN = re.compile(
+    r"\)(?:\s*,?\s*(?:(?P<without_rowid>WITHOUT\s+ROWID)"
+    r"|(?P<strict>STRICT)))*\s*$",
+    re.I,
+)
+
+
 class SQLiteDialect(default.DefaultDialect):
     name = "sqlite"
     supports_alter = False
@@ -2381,6 +2421,29 @@ class SQLiteDialect(default.DefaultDialect):
                 f"{schema}.{view_name}" if schema else view_name
             )
 
+    @reflection.cache
+    def get_table_options(self, connection, table_name, schema=None, **kw):
+        tablesql = self._get_table_sql(
+            connection, table_name, schema=schema, **kw
+        )
+
+        options = {}
+
+        # tablesql is None for the internal sqlite_ tables, which have no
+        # entry in sqlite_master
+        if tablesql is not None:
+            match = TABLE_OPTIONS_PATTERN.search(tablesql.strip())
+            if match:
+                if match.group("without_rowid"):
+                    options["sqlite_with_rowid"] = False
+                if match.group("strict"):
+                    options["sqlite_strict"] = True
+
+        if options:
+            return options
+        else:
+            return ReflectionDefaults.table_options()
+
     @reflection.cache
     def get_columns(self, connection, table_name, schema=None, **kw):
         pragma = "table_info"
@@ -2549,7 +2612,7 @@ class SQLiteDialect(default.DefaultDialect):
         constraint_name = None
         table_data = self._get_table_sql(connection, table_name, schema=schema)
         if table_data:
-            PK_PATTERN = r'CONSTRAINT +(?:"(.+?)"|(\w+)) +PRIMARY KEY'
+            PK_PATTERN = r'CONSTRAINT\s+(?:"(.+?)"|(\w+))\s+PRIMARY\s+KEY'
             result = re.search(PK_PATTERN, table_data, re.I)
             if result:
                 constraint_name = result.group(1) or result.group(2)
@@ -2653,16 +2716,7 @@ class SQLiteDialect(default.DefaultDialect):
             # FKs, namely the name of the constraint and other options.
             # so parsing the columns is really about matching it up to what
             # we already have.
-            FK_PATTERN = (
-                r'(?:CONSTRAINT +(?:"(.+?)"|(\w+)) +)?'
-                r"FOREIGN KEY *\( *(.+?) *\) +"
-                r'REFERENCES +(?:(?:"(.+?)")|([a-z0-9_]+)) *\( *((?:(?:"[^"]+"|[a-z0-9_]+) *(?:, *)?)+)\) *'  # noqa: E501
-                r"((?:ON (?:DELETE|UPDATE) "
-                r"(?:SET NULL|SET DEFAULT|CASCADE|RESTRICT|NO ACTION) *)*)"
-                r"((?:NOT +)?DEFERRABLE)?"
-                r"(?: +INITIALLY +(DEFERRED|IMMEDIATE))?"
-            )
-            for match in re.finditer(FK_PATTERN, table_data, re.I):
+            for match in FK_PATTERN.finditer(table_data):
                 (
                     constraint_quoted_name,
                     constraint_name,
@@ -2687,7 +2741,13 @@ class SQLiteDialect(default.DefaultDialect):
                 referred_name = referred_quoted_name or referred_name
                 options = {}
 
-                for token in re.split(r" *\bON\b *", onupdatedelete.upper()):
+                # a newline may separate the words of an
+                # ON DELETE / ON UPDATE clause; normalize to single
+                # spaces so the tokens below compare correctly
+                onupdatedelete = re.sub(
+                    r"\s+", " ", onupdatedelete.upper()
+                ).strip()
+                for token in re.split(r" *\bON\b *", onupdatedelete):
                     if token.startswith("DELETE"):
                         ondelete = token[6:].strip()
                         if ondelete and ondelete != "NO ACTION":
@@ -2770,11 +2830,11 @@ class SQLiteDialect(default.DefaultDialect):
             if table_data is None:
                 return
             UNIQUE_PATTERN = (
-                r'(?:CONSTRAINT +(?:"(.+?)"|(\w+)) +)?UNIQUE *\((.+?)\)'
+                r'(?:CONSTRAINT\s+(?:"(.+?)"|(\w+))\s+)?UNIQUE\s*\((.+?)\)'
             )
             INLINE_UNIQUE_PATTERN = (
                 r'(?:(".+?")|(?:[\[`])?([a-z0-9_]+)(?:[\]`])?)[\t ]'
-                r"+[a-z0-9_ ]+?[\t ]+UNIQUE"
+                r"+[a-z0-9_]+(?:[\t ]+[a-z0-9_]+)*?[\t ]+UNIQUE"
             )
 
             for match in re.finditer(UNIQUE_PATTERN, table_data, re.I):
@@ -2865,32 +2925,14 @@ class SQLiteDialect(default.DefaultDialect):
                     flags=re.DOTALL,
                 )
 
-            # Find the matching closing parenthesis by counting balanced parens
-            # Must track string context to ignore parens inside string literals
-            start = match.end()  # Position after 'CHECK ('
-            paren_count = 1
-            in_single_quote = False
-            in_double_quote = False
-
-            for pos, char in enumerate(table_data[start:], start):
-                # Track string literal context
-                if char == "'" and not in_double_quote:
-                    in_single_quote = not in_single_quote
-                elif char == '"' and not in_single_quote:
-                    in_double_quote = not in_double_quote
-                # Only count parens when not inside a string literal
-                elif not in_single_quote and not in_double_quote:
-                    if char == "(":
-                        paren_count += 1
-                    elif char == ")":
-                        paren_count -= 1
-                        if paren_count == 0:
-                            # Successfully found matching closing parenthesis
-                            sqltext = table_data[start:pos].strip()
-                            cks.append(
-                                {"sqltext": sqltext, "name": constraint_name}
-                            )
-                            break
+            # Find the matching closing parenthesis with quote-aware paren
+            # counting. ``match.end() - 1`` is the position of the ``(``
+            # that opened the CHECK clause; ``match.end()`` is the first
+            # character of the constraint body.
+            close = util.find_matching_paren(table_data, match.end() - 1)
+            if close is not None:
+                sqltext = table_data[match.end() : close].strip()
+                cks.append({"sqltext": sqltext, "name": constraint_name})
 
         cks.sort(key=lambda d: d["name"] or "~")  # sort None as last
         if cks:

sqlalchemy/dialects/sqlite/pysqlite.py

@@ -209,8 +209,8 @@ processing.
 
 .. _pysqlite_threading_pooling:
 
-Threading/Pooling Behavior
----------------------------
+Concurrency/Threading/Pooling Behavior
+--------------------------------------
 
 The ``sqlite3`` DBAPI by default prohibits the use of a particular connection
 in a thread which is not the one in which it was created.  As SQLite has
@@ -261,15 +261,82 @@ connection reuse implemented by :class:`.QueuePool`.  However, it still
 may be beneficial to use this class if the application is experiencing
 issues with files being locked.
 
-Using a Memory Database in Multiple Threads
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using a Memory Database in Multiple Threads or Coroutines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``:memory:`` SQLite database exists only within the scope of a single
+DBAPI connection.  It is not possible for two separate ``sqlite3``
+connection objects to access the same ``:memory:`` database unless SQLite's
+shared-cache feature is enabled.  Without shared cache, each connection
+creates its own independent in-memory database.
+
+This means a ``:memory:`` database is **not suitable** for use with
+multiple concurrent threads or coroutines unless either:
+
+* All workers are fully serialized (mutexed) against each other
+  such that only one is using the database at a time, or
+* SQLite's shared-cache URI feature is used to allow multiple
+  independent connections to access the same in-memory database.
+
+The same considerations apply when using the :ref:`aiosqlite <aiosqlite>`
+dialect, which wraps ``pysqlite`` connections in an async interface —
+without shared cache, each connection still creates its own independent
+in-memory database.
+
+The recommended approach for multithreaded or async in-memory
+use is the shared-cache URI feature, described below.
+
+.. _pysqlite_uri_shared_cache:
+
+Using a Shared-Cache Memory Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SQLite's
+`URI shared-cache <https://www.sqlite.org/sharedcache.html>`_
+mode allows multiple independent DBAPI connections, each with
+their own transaction state, to access the same in-memory
+database.  This is enabled by using a ``file:`` URI with
+``cache=shared`` and passing ``uri=true`` in the query
+string::
+
+    engine = create_engine("sqlite:///file::memory:?cache=shared&uri=true")
+
+For async use with aiosqlite, use
+:func:`_asyncio.create_async_engine`::
+
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///file::memory:?cache=shared&uri=true"
+    )
+
+Because this URL form is treated as a file-based database by the
+dialect, :class:`.QueuePool` is used automatically and
+``check_same_thread`` defaults to ``False``, so no additional pool
+or connect_args configuration is needed.  Each checkout from the
+pool is a distinct DBAPI connection with its own transaction state,
+and the in-memory database persists as long as at least one
+connection remains open.
+
+The shared-cache database is scoped by the filename component of
+the URI.  ``file::memory:`` (empty name) is process-global — all
+engines in the process that use this URI share the same database.
+To maintain multiple independent in-memory databases within the
+same process, supply a distinct name for each::
+
+    engine_a = create_engine(
+        "sqlite:///file:db_a?mode=memory&cache=shared&uri=true"
+    )
+    engine_b = create_engine(
+        "sqlite:///file:db_b?mode=memory&cache=shared&uri=true"
+    )
+
+Using StaticPool for Single-Connection Memory Databases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To use a ``:memory:`` database in a multithreaded scenario, the same
-connection object must be shared among threads, since the database exists
-only within the scope of that connection.   The
-:class:`.StaticPool` implementation will maintain a single connection
-globally, and the ``check_same_thread`` flag can be passed to Pysqlite
-as ``False``::
+An older approach for sharing a ``:memory:`` database among threads
+is to force all checkouts to return the same DBAPI connection using
+:class:`.StaticPool`.  **This approach does not support any form of
+concurrency** and is only useful when all access to the engine is
+fully serialized, such as in single-threaded test suites::
 
     from sqlalchemy.pool import StaticPool
 
@@ -279,8 +346,18 @@ as ``False``::
         poolclass=StaticPool,
     )
 
-Note that using a ``:memory:`` database in multiple threads requires a recent
-version of SQLite.
+.. warning::
+
+    Because :class:`.StaticPool` maintains a single DBAPI connection,
+    all :class:`.Session` or :class:`.Connection` objects that use
+    this engine share that one underlying connection and its single
+    SQLite transaction state.  A ``ROLLBACK`` issued by one session
+    (e.g. during error handling) will also roll back uncommitted work
+    from any other session, and concurrent ``COMMIT`` / ``ROLLBACK``
+    calls can interfere with each other unpredictably.  This approach
+    is only appropriate when access to the engine is fully serialized,
+    such as in single-threaded test suites.  For concurrent workloads,
+    use the shared-cache URI approach described above.
 
 Using Temporary Tables with SQLite
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^