# dialects/sqlite/aiosqlite.py
# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: https://www.opensource.org/licenses/mit-license.php


r"""

.. dialect:: sqlite+aiosqlite
    :name: aiosqlite
    :dbapi: aiosqlite
    :connectstring: sqlite+aiosqlite:///file_path
    :url: https://pypi.org/project/aiosqlite/

The aiosqlite dialect provides support for the SQLAlchemy asyncio interface
running on top of pysqlite.

aiosqlite is a wrapper around pysqlite that uses a background thread for
each connection.   It does not actually use non-blocking IO, as SQLite
databases are not socket-based.  However it does provide a working asyncio
interface that's useful for testing and prototyping purposes.

Using a special asyncio mediation layer, the aiosqlite dialect is usable
as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>`
extension package.

This dialect should normally be used only with the
:func:`_asyncio.create_async_engine` engine creation function::

    from sqlalchemy.ext.asyncio import create_async_engine

    engine = create_async_engine("sqlite+aiosqlite:///filename")

The URL passes through all arguments to the ``pysqlite`` driver, so all
connection arguments are the same as they are for that of :ref:`pysqlite`.

.. _aiosqlite_udfs:

User-Defined Functions
----------------------

aiosqlite extends pysqlite to support async, so we can create our own user-defined functions (UDFs)
in Python and use them directly in SQLite queries as described here: :ref:`pysqlite_udfs`.

.. _aiosqlite_serializable:

Serializable isolation / Savepoints / Transactional DDL (asyncio version)
-------------------------------------------------------------------------

A newly revised version of this important section is now available
at the top level of the SQLAlchemy SQLite documentation, in the section
:ref:`sqlite_transactions`.


.. _aiosqlite_pooling:

Pooling Behavior
----------------

The SQLAlchemy ``aiosqlite`` DBAPI establishes the connection pool differently
based on the kind of SQLite database that's requested:

* When a ``:memory:`` SQLite database is specified, the dialect by default
  will use :class:`.StaticPool`. This pool maintains a single
  connection, so that all access to the engine
  use the same ``:memory:`` database.
* When a file-based database is specified, the dialect will use
  :class:`.AsyncAdaptedQueuePool` as the source of connections.

  .. versionchanged:: 2.0.38

    SQLite file database engines now use :class:`.AsyncAdaptedQueuePool` by default.
    Previously, :class:`.NullPool` were used.  The :class:`.NullPool` class
    may be used by specifying it via the
    :paramref:`_sa.create_engine.poolclass` parameter.

As with the pysqlite dialect, this selection is made based on the database
name alone, and the ``mode=memory`` query string argument is deprecated as
a means of influencing it; see :ref:`pysqlite_threading_pooling` for
background.

.. _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.

Note that a shared-cache database is discarded once its last connection is
closed, so that operations such as :meth:`_asyncio.AsyncEngine.dispose` or
the use of :paramref:`_sa.create_engine.pool_recycle` will destroy its
contents; see :ref:`pysqlite_shared_cache_lifespan` for background and for
how to hold such a database open.

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

import asyncio
from functools import partial
from threading import Thread
from types import ModuleType
from typing import Any
from typing import cast
from typing import NoReturn
from typing import Optional
from typing import TYPE_CHECKING
from typing import Union

from .base import SQLiteExecutionContext
from .pysqlite import SQLiteDialect_pysqlite
from ... import pool
from ... import util
from ...connectors.asyncio import AsyncAdapt_dbapi_connection
from ...connectors.asyncio import AsyncAdapt_dbapi_cursor
from ...connectors.asyncio import AsyncAdapt_dbapi_module
from ...connectors.asyncio import AsyncAdapt_dbapi_ss_cursor
from ...connectors.asyncio import AsyncAdapt_terminate
from ...util.concurrency import await_

if TYPE_CHECKING:
    from ...connectors.asyncio import AsyncIODBAPIConnection
    from ...engine.interfaces import DBAPIConnection
    from ...engine.interfaces import DBAPICursor
    from ...engine.interfaces import DBAPIModule
    from ...engine.url import URL
    from ...pool.base import PoolProxiedConnection


class AsyncAdapt_aiosqlite_cursor(AsyncAdapt_dbapi_cursor):
    __slots__ = ()


class AsyncAdapt_aiosqlite_ss_cursor(AsyncAdapt_dbapi_ss_cursor):
    __slots__ = ()


class AsyncAdapt_aiosqlite_connection(
    AsyncAdapt_terminate, AsyncAdapt_dbapi_connection
):
    __slots__ = ()

    _cursor_cls = AsyncAdapt_aiosqlite_cursor
    _ss_cursor_cls = AsyncAdapt_aiosqlite_ss_cursor

    @property
    def isolation_level(self) -> Optional[str]:
        return cast(str, self._connection.isolation_level)

    @isolation_level.setter
    def isolation_level(self, value: Optional[str]) -> None:
        # aiosqlite's isolation_level setter works outside the Thread
        # that it's supposed to, necessitating setting check_same_thread=False.
        # for improved stability, we instead invent our own awaitable version
        # using aiosqlite's async queue directly.

        def set_iso(
            connection: AsyncAdapt_aiosqlite_connection, value: Optional[str]
        ) -> None:
            connection.isolation_level = value

        function = partial(set_iso, self._connection._conn, value)
        future = asyncio.get_event_loop().create_future()

        self._connection._tx.put_nowait((future, function))

        try:
            await_(future)
        except Exception as error:
            self._handle_exception(error)

    def create_function(self, *args: Any, **kw: Any) -> None:
        try:
            await_(self._connection.create_function(*args, **kw))
        except Exception as error:
            self._handle_exception(error)

    def rollback(self) -> None:
        if self._connection._connection:
            super().rollback()

    def commit(self) -> None:
        if self._connection._connection:
            super().commit()

    def close(self) -> None:
        try:
            await_(self._connection.close())
        except ValueError:
            # this is undocumented for aiosqlite, that ValueError
            # was raised if .close() was called more than once, which is
            # both not customary for DBAPI and is also not a DBAPI.Error
            # exception. This is now fixed in aiosqlite via my PR
            # https://github.com/omnilib/aiosqlite/pull/238, so we can be
            # assured this will not become some other kind of exception,
            # since it doesn't raise anymore.

            pass
        except Exception as error:
            self._handle_exception(error)

    @classmethod
    def _handle_exception_no_connection(
        cls, dbapi: Any, error: Exception
    ) -> NoReturn:
        if isinstance(error, ValueError) and error.args[0].lower() in (
            "no active connection",
            "connection closed",
        ):
            raise dbapi.sqlite.OperationalError(error.args[0]) from error
        else:
            super()._handle_exception_no_connection(dbapi, error)

    async def _terminate_graceful_close(self) -> None:
        """Try to close connection gracefully"""
        await self._connection.close()

    def _terminate_force_close(self) -> None:
        """Terminate the connection"""

        # this was added in aiosqlite 0.22.1.  if stop() is not present,
        # the dialect should indicate has_terminate=False
        try:
            meth = self._connection.stop
        except AttributeError as ae:
            raise NotImplementedError(
                "terminate_force_close() not implemented by this DBAPI shim"
            ) from ae
        else:
            meth()


class AsyncAdapt_aiosqlite_dbapi(AsyncAdapt_dbapi_module):
    def __init__(self, aiosqlite: ModuleType, sqlite: ModuleType):
        super().__init__(aiosqlite, dbapi_module=sqlite)
        self.aiosqlite = aiosqlite
        self.sqlite = sqlite
        self.paramstyle = "qmark"
        self.has_stop = hasattr(aiosqlite.Connection, "stop")
        self._init_dbapi_attributes()

    def _init_dbapi_attributes(self) -> None:
        for name in (
            "DatabaseError",
            "Error",
            "IntegrityError",
            "NotSupportedError",
            "OperationalError",
            "ProgrammingError",
            "sqlite_version",
            "sqlite_version_info",
        ):
            setattr(self, name, getattr(self.aiosqlite, name))

        for name in ("PARSE_COLNAMES", "PARSE_DECLTYPES"):
            setattr(self, name, getattr(self.sqlite, name))

        for name in ("Binary",):
            setattr(self, name, getattr(self.sqlite, name))

    def connect(self, *arg: Any, **kw: Any) -> AsyncAdapt_aiosqlite_connection:
        creator_fn = kw.pop("async_creator_fn", None)
        if creator_fn:
            connection = creator_fn(*arg, **kw)
        else:
            connection = self.aiosqlite.connect(*arg, **kw)

            # aiosqlite uses a Thread.   you'll thank us later
            if isinstance(connection, Thread):
                # Connection itself was a thread in version prior to 0.22
                connection.daemon = True
            else:
                # in 0.22+ instead it contains a thread.
                connection._thread.daemon = True

        return AsyncAdapt_aiosqlite_connection(self, await_(connection))


class SQLiteExecutionContext_aiosqlite(SQLiteExecutionContext):
    def create_server_side_cursor(self) -> DBAPICursor:
        return self._dbapi_connection.cursor(server_side=True)


class SQLiteDialect_aiosqlite(SQLiteDialect_pysqlite):
    driver = "aiosqlite"
    supports_statement_cache = True

    is_async = True
    has_terminate = True

    supports_server_side_cursors = True

    execution_ctx_cls = SQLiteExecutionContext_aiosqlite

    def __init__(self, **kwargs: Any):
        super().__init__(**kwargs)
        if self.dbapi and not self.dbapi.has_stop:
            self.has_terminate = False

    @classmethod
    def import_dbapi(cls) -> AsyncAdapt_aiosqlite_dbapi:
        return AsyncAdapt_aiosqlite_dbapi(
            __import__("aiosqlite"), __import__("sqlite3")
        )

    def retrieve_dbapi_version(self, dbapi: DBAPIModule) -> util.VersionInfo:
        # the version of aiosqlite, rather than the Python version
        # reported by the pysqlite dialect
        aiosqlite = getattr(dbapi, "aiosqlite", None)
        return util.parse_version_string(
            getattr(aiosqlite, "__version__", None)
        )

    @classmethod
    def get_pool_class(cls, url: URL) -> type[pool.Pool]:
        if cls._is_url_file_db(url):
            return pool.AsyncAdaptedQueuePool
        else:
            cls._warn_memory_mode_pool_selection(
                url, pool.StaticPool, pool.AsyncAdaptedQueuePool
            )
            return pool.StaticPool

    def is_disconnect(
        self,
        e: DBAPIModule.Error,
        connection: Optional[Union[PoolProxiedConnection, DBAPIConnection]],
        cursor: Optional[DBAPICursor],
    ) -> bool:
        self.dbapi = cast("DBAPIModule", self.dbapi)
        if isinstance(e, self.dbapi.OperationalError):
            err_lower = str(e).lower()
            if (
                "no active connection" in err_lower
                or "connection closed" in err_lower
            ):
                return True

        return super().is_disconnect(e, connection, cursor)

    def get_driver_connection(
        self, connection: DBAPIConnection
    ) -> AsyncIODBAPIConnection:
        return connection._connection  # type: ignore[no-any-return]

    def do_terminate(self, dbapi_connection: DBAPIConnection) -> None:
        dbapi_connection.terminate()


dialect = SQLiteDialect_aiosqlite