SQLAlchemy 2.1.0rc1__cp315-cp315-win_amd64.whl

sqlalchemy/dialects/mysql/provision.py

@@ -0,0 +1,153 @@
+# dialects/mysql/provision.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
+# mypy: ignore-errors
+import contextlib
+
+from ... import event
+from ... import exc
+from ...testing.provision import allow_stale_update_impl
+from ...testing.provision import configure_follower
+from ...testing.provision import create_db
+from ...testing.provision import delete_from_all_tables
+from ...testing.provision import drop_db
+from ...testing.provision import generate_driver_url
+from ...testing.provision import temp_table_keyword_args
+from ...testing.provision import upsert
+
+
+@generate_driver_url.for_db("mysql", "mariadb")
+def generate_driver_url(url, driver, query_str):
+    backend = url.get_backend_name()
+
+    # NOTE: at the moment, tests are running mariadbconnector
+    # against both mariadb and mysql backends.   if we want this to be
+    # limited, do the decision making here to reject a "mysql+mariadbconnector"
+    # URL.  Optionally also re-enable the module level
+    # MySQLDialect_mariadbconnector.is_mysql flag as well, which must include
+    # a unit and/or functional test.
+
+    # all the Jenkins tests have been running mysqlclient Python library
+    # built against mariadb client drivers for years against all MySQL /
+    # MariaDB versions going back to MySQL 5.6, currently they can talk
+    # to MySQL databases without problems.
+
+    if backend == "mysql":
+        dialect_cls = url.get_dialect()
+        if dialect_cls._is_mariadb_from_url(url):
+            backend = "mariadb"
+
+    new_url = url.set(
+        drivername="%s+%s" % (backend, driver)
+    ).update_query_string(query_str)
+
+    if driver == "mariadbconnector":
+        new_url = new_url.difference_update_query(["charset"])
+    elif driver == "mysqlconnector":
+        new_url = new_url.update_query_pairs(
+            [("collation", "utf8mb4_general_ci")]
+        )
+
+    try:
+        new_url.get_dialect()
+    except exc.NoSuchModuleError:
+        return None
+    else:
+        return new_url
+
+
+@create_db.for_db("mysql", "mariadb")
+def _mysql_create_db(cfg, eng, ident):
+    with eng.begin() as conn:
+        try:
+            _mysql_drop_db(cfg, conn, ident)
+        except Exception:
+            pass
+
+    with eng.begin() as conn:
+        conn.exec_driver_sql(
+            "CREATE DATABASE %s CHARACTER SET utf8mb4" % ident
+        )
+        conn.exec_driver_sql(
+            "CREATE DATABASE %s_test_schema CHARACTER SET utf8mb4" % ident
+        )
+        conn.exec_driver_sql(
+            "CREATE DATABASE %s_test_schema_2 CHARACTER SET utf8mb4" % ident
+        )
+
+
+@configure_follower.for_db("mysql", "mariadb")
+def _mysql_configure_follower(config, ident):
+    config.test_schema = "%s_test_schema" % ident
+    config.test_schema_2 = "%s_test_schema_2" % ident
+
+
+@drop_db.for_db("mysql", "mariadb")
+def _mysql_drop_db(cfg, eng, ident):
+    with eng.begin() as conn:
+        conn.exec_driver_sql("DROP DATABASE %s_test_schema" % ident)
+        conn.exec_driver_sql("DROP DATABASE %s_test_schema_2" % ident)
+        conn.exec_driver_sql("DROP DATABASE %s" % ident)
+
+
+@temp_table_keyword_args.for_db("mysql", "mariadb")
+def _mysql_temp_table_keyword_args(cfg, eng):
+    return {"prefixes": ["TEMPORARY"]}
+
+
+@upsert.for_db("mariadb")
+def _upsert(
+    cfg,
+    table,
+    returning,
+    *,
+    set_lambda=None,
+    sort_by_parameter_order=False,
+    index_elements=None,
+):
+    from sqlalchemy.dialects.mysql import insert
+
+    stmt = insert(table)
+
+    if set_lambda:
+        stmt = stmt.on_duplicate_key_update(**set_lambda(stmt.inserted))
+    else:
+        pk1 = table.primary_key.c[0]
+        stmt = stmt.on_duplicate_key_update({pk1.key: pk1})
+
+    stmt = stmt.returning(
+        *returning, sort_by_parameter_order=sort_by_parameter_order
+    )
+    return stmt
+
+
+@delete_from_all_tables.for_db("mysql", "mariadb")
+def _delete_from_all_tables(connection, cfg, metadata):
+    connection.exec_driver_sql("SET foreign_key_checks = 0")
+    try:
+        delete_from_all_tables.call_original(connection, cfg, metadata)
+    finally:
+        connection.exec_driver_sql("SET foreign_key_checks = 1")
+
+
+@allow_stale_update_impl.for_db("mariadb")
+def _allow_stale_update_impl(cfg):
+    @contextlib.contextmanager
+    def go():
+        @event.listens_for(cfg.db, "engine_connect")
+        def turn_off_snapshot_isolation(conn):
+            conn.exec_driver_sql("SET innodb_snapshot_isolation = 'OFF'")
+            conn.rollback()
+
+        try:
+            yield
+        finally:
+            event.remove(cfg.db, "engine_connect", turn_off_snapshot_isolation)
+
+            # dispose the pool; quick way to just have those reset
+            cfg.db.dispose()
+
+    return go()

sqlalchemy/dialects/mysql/pymysql.py

@@ -0,0 +1,188 @@
+# dialects/mysql/pymysql.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:: mysql+pymysql
+    :name: PyMySQL
+    :dbapi: pymysql
+    :connectstring: mysql+pymysql://<username>:<password>@<host>/<dbname>[?<options>]
+    :url: https://pymysql.readthedocs.io/
+
+Unicode
+-------
+
+Please see :ref:`mysql_unicode` for current recommendations on unicode
+handling.
+
+.. _pymysql_ssl:
+
+SSL Connections
+------------------
+
+The PyMySQL DBAPI accepts the same SSL arguments as that of MySQLdb,
+described at :ref:`mysqldb_ssl`.   See that section for additional examples.
+
+If the server uses an automatically-generated certificate that is self-signed
+or does not match the host name (as seen from the client), it may also be
+necessary to indicate ``ssl_check_hostname=false`` in PyMySQL::
+
+    connection_uri = (
+        "mysql+pymysql://scott:tiger@192.168.0.134/test"
+        "?ssl_ca=/home/gord/client-ssl/ca.pem"
+        "&ssl_cert=/home/gord/client-ssl/client-cert.pem"
+        "&ssl_key=/home/gord/client-ssl/client-key.pem"
+        "&ssl_check_hostname=false"
+    )
+
+MySQL-Python Compatibility
+--------------------------
+
+The pymysql DBAPI is a pure Python port of the MySQL-python (MySQLdb) driver,
+and targets 100% compatibility.   Most behavioral notes for MySQL-python apply
+to the pymysql driver as well.
+
+"""  # noqa
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Literal
+from typing import Optional
+from typing import Type
+from typing import TYPE_CHECKING
+from typing import Union
+
+from .mysqldb import MySQLDialect_mysqldb
+from ... import util
+from ...util import langhelpers
+
+if TYPE_CHECKING:
+
+    from ...engine.interfaces import ConnectArgsType
+    from ...engine.interfaces import DBAPIConnection
+    from ...engine.interfaces import DBAPICursor
+    from ...engine.interfaces import DBAPIModule
+    from ...engine.interfaces import PoolProxiedConnection
+    from ...engine.url import URL
+
+
+def _connection_ping_reconnects_true(connection_cls: Type[Any]) -> bool:
+    """Given a Connection class like pymysql.Connection, aiomysql.Connection,
+    asyncmy.Connection, inspect the ping() method and determine if it
+    has a "reconnect" parameter that either defaults to True, or is positional.
+
+    a return value of True here means that when we call ``connection.ping()``,
+    we **must** pass `reconnect=False`.  a return value of False means that
+    we should call ``connection.ping()`` with **no arguments**.
+
+    This routine originates from issue #10492 for pymysql, however arg
+    signature mismatches in aiomysql/asyncmy tracked by issue #13306
+    necessitated a more open ended function.
+
+    """
+    insp = langhelpers.get_callable_argspec(connection_cls.ping)
+    try:
+        reconnect_arg = insp.args[1]
+    except IndexError:
+        return False
+    else:
+        return reconnect_arg == "reconnect" and (
+            not insp.defaults or insp.defaults[0] is not False
+        )
+
+
+class MySQLDialect_pymysql(MySQLDialect_mysqldb):
+    driver = "pymysql"
+    supports_statement_cache = True
+
+    description_encoding = None
+
+    def retrieve_dbapi_version(self, dbapi: DBAPIModule) -> util.VersionInfo:
+        # pymysql publishes its own version as ``VERSION_STRING``; the
+        # ``__version__`` and ``version_info`` attributes it also publishes
+        # are mysqlclient compatibility values, e.g. ``"2.2.8"`` for a
+        # pymysql that is itself version 1.2.0
+        return util.parse_version_string(
+            getattr(dbapi, "VERSION_STRING", None)
+        )
+
+    @langhelpers.memoized_property
+    def supports_server_side_cursors(self) -> bool:
+        try:
+            cursors = __import__("pymysql.cursors").cursors
+            self._sscursor = cursors.SSCursor
+            return True
+        except (ImportError, AttributeError):
+            return False
+
+    @classmethod
+    def import_dbapi(cls) -> DBAPIModule:
+        return __import__("pymysql")
+
+    @langhelpers.memoized_property
+    def _send_false_to_ping(self) -> bool:
+        """determine if pymysql has deprecated, changed the default of,
+        or removed the 'reconnect' argument of connection.ping().
+
+        See #10492 and
+        https://github.com/PyMySQL/mysqlclient/discussions/651#discussioncomment-7308971
+        for background.
+
+        Revised as part of #13306
+
+        """  # noqa: E501
+
+        try:
+            Connection = __import__(
+                "pymysql.connections"
+            ).connections.Connection
+        except (ImportError, AttributeError):
+            return True
+        else:
+            return _connection_ping_reconnects_true(Connection)
+
+    def do_ping(self, dbapi_connection: DBAPIConnection) -> Literal[True]:
+        if self._send_false_to_ping:
+            dbapi_connection.ping(False)
+        else:
+            dbapi_connection.ping()
+
+        return True
+
+    def create_connect_args(
+        self, url: URL, _translate_args: Optional[dict[str, Any]] = None
+    ) -> ConnectArgsType:
+        if _translate_args is None:
+            _translate_args = dict(username="user")
+        return super().create_connect_args(
+            url, _translate_args=_translate_args
+        )
+
+    def is_disconnect(
+        self,
+        e: DBAPIModule.Error,
+        connection: Optional[Union[PoolProxiedConnection, DBAPIConnection]],
+        cursor: Optional[DBAPICursor],
+    ) -> bool:
+        if super().is_disconnect(e, connection, cursor):
+            return True
+        elif isinstance(e, self.loaded_dbapi.Error):
+            str_e = str(e).lower()
+            return (
+                "already closed" in str_e or "connection was killed" in str_e
+            )
+        else:
+            return False
+
+    def _extract_error_code(self, exception: BaseException) -> Any:
+        if isinstance(exception.args[0], Exception):
+            exception = exception.args[0]
+        return exception.args[0]
+
+
+dialect = MySQLDialect_pymysql

sqlalchemy/dialects/mysql/pyodbc.py

@@ -0,0 +1,157 @@
+# dialects/mysql/pyodbc.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:: mysql+pyodbc
+    :name: PyODBC
+    :dbapi: pyodbc
+    :connectstring: mysql+pyodbc://<username>:<password>@<dsnname>
+    :url: https://pypi.org/project/pyodbc/
+
+.. note::
+
+    The PyODBC for MySQL dialect is **not tested as part of
+    SQLAlchemy's continuous integration**.
+    The recommended MySQL dialects are mysqlclient and PyMySQL.
+    However, if you want to use the mysql+pyodbc dialect and require
+    full support for ``utf8mb4`` characters (including supplementary
+    characters like emoji) be sure to use a current release of
+    MySQL Connector/ODBC and specify the "ANSI" (**not** "Unicode")
+    version of the driver in your DSN or connection string.
+
+Pass through exact pyodbc connection string::
+
+    import urllib
+
+    connection_string = (
+        "DRIVER=MySQL ODBC 8.0 ANSI Driver;"
+        "SERVER=localhost;"
+        "PORT=3307;"
+        "DATABASE=mydb;"
+        "UID=root;"
+        "PWD=(whatever);"
+        "charset=utf8mb4;"
+    )
+    params = urllib.parse.quote_plus(connection_string)
+    connection_uri = "mysql+pyodbc:///?odbc_connect=%s" % params
+
+"""  # noqa
+
+from __future__ import annotations
+
+import datetime
+import re
+from typing import Any
+from typing import Callable
+from typing import Optional
+from typing import TYPE_CHECKING
+from typing import Union
+
+from .base import MySQLDialect
+from .base import MySQLExecutionContext
+from .types import TIME
+from ... import exc
+from ... import util
+from ...connectors.pyodbc import PyODBCConnector
+from ...sql.sqltypes import Time
+
+if TYPE_CHECKING:
+    from ...engine import Connection
+    from ...engine.interfaces import DBAPIConnection
+    from ...engine.interfaces import Dialect
+    from ...sql.type_api import _ResultProcessorType
+
+
+class _pyodbcTIME(TIME):
+    def result_processor(
+        self, dialect: Dialect, coltype: object
+    ) -> _ResultProcessorType[datetime.time]:
+        def process(value: Any) -> Union[datetime.time, None]:
+            # pyodbc returns a datetime.time object; no need to convert
+            return value  # type: ignore[no-any-return]
+
+        return process
+
+
+class MySQLExecutionContext_pyodbc(MySQLExecutionContext):
+    def get_lastrowid(self) -> int:
+        cursor = self.create_cursor()
+        cursor.execute("SELECT LAST_INSERT_ID()")
+        lastrowid = cursor.fetchone()[0]  # type: ignore[index]
+        cursor.close()
+        return lastrowid  # type: ignore[no-any-return]
+
+
+class MySQLDialect_pyodbc(PyODBCConnector, MySQLDialect):
+    supports_statement_cache = True
+    colspecs = util.update_copy(MySQLDialect.colspecs, {Time: _pyodbcTIME})
+    supports_unicode_statements = True
+    execution_ctx_cls = MySQLExecutionContext_pyodbc
+
+    pyodbc_driver_name = "MySQL"
+
+    def _detect_charset(self, connection: Connection) -> str:
+        """Sniff out the character set in use for connection results."""
+
+        # Prefer 'character_set_results' for the current connection over the
+        # value in the driver.  SET NAMES or individual variable SETs will
+        # change the charset without updating the driver's view of the world.
+        #
+        # If it's decided that issuing that sort of SQL leaves you SOL, then
+        # this can prefer the driver value.
+
+        # set this to None as _fetch_setting attempts to use it (None is OK)
+        self._connection_charset = None
+        try:
+            value = self._fetch_setting(connection, "character_set_client")
+            if value:
+                return value
+        except exc.DBAPIError:
+            pass
+
+        util.warn(
+            "Could not detect the connection character set.  "
+            "Assuming latin1."
+        )
+        return "latin1"
+
+    def _get_server_version_info(
+        self, connection: Connection
+    ) -> tuple[int, ...]:
+        return MySQLDialect._get_server_version_info(self, connection)
+
+    def _extract_error_code(self, exception: BaseException) -> Optional[int]:
+        m = re.compile(r"\((\d+)\)").search(str(exception.args))
+        if m is None:
+            return None
+        c: Optional[str] = m.group(1)
+        if c:
+            return int(c)
+        else:
+            return None
+
+    def on_connect(self) -> Callable[[DBAPIConnection], None]:
+        super_ = super().on_connect()
+
+        def on_connect(conn: DBAPIConnection) -> None:
+            if super_ is not None:
+                super_(conn)
+
+            # declare Unicode encoding for pyodbc as per
+            #   https://github.com/mkleehammer/pyodbc/wiki/Unicode
+            pyodbc_SQL_CHAR = 1  # pyodbc.SQL_CHAR
+            pyodbc_SQL_WCHAR = -8  # pyodbc.SQL_WCHAR
+            conn.setdecoding(pyodbc_SQL_CHAR, encoding="utf-8")
+            conn.setdecoding(pyodbc_SQL_WCHAR, encoding="utf-8")
+            conn.setencoding(encoding="utf-8")
+
+        return on_connect
+
+
+dialect = MySQLDialect_pyodbc