Подключение к серверу MySQL можно установить, используя либо функцию mysql.connector.connect(), либо класс mysql.connector.MySQLConnection():

cnx = mysql.connector.connect(user='joe', database='test')
cnx = MySQLConnection(user='joe', database='test')

В следующей таблице описаны аргументы, которые можно использовать для инициализации подключения. Звездочка (*) после аргумента указывает на синонимичное имя аргумента, доступное только для совместимости с другими драйверами MySQL для Python. Oracle рекомендует не использовать эти альтернативные имена.

Параметры аутентификации MySQL

Аутентификация с MySQL обычно использует username и password.

При указании аргумента database текущая база данных устанавливается в указанное значение. Для изменения текущей базы данных позже выполните USE SQL-запрос или установите свойство database экземпляра MySQLConnection.

По умолчанию Connector/Python пытается подключиться к серверу MySQL, работающему на локальном хосте, используя TCP/IP. Аргумент host по умолчанию имеет значение IP-адреса 127.0.0.1, а port — 3306. Unix-сокеты поддерживаются установкой unix_socket. Именные каналы на платформе Windows не поддерживаются.

Connector/Python поддерживает плагины аутентификации, доступные с MySQL 8.0, включая предпочтительный плагин аутентификации.

Поддерживается устаревший плагин, но он отключен по умолчанию с MySQL Server 8.4.0 и удален с MySQL Server 9.0.0.

Метод connect() поддерживает аргумент auth_plugin, который может быть использован для принудительного использования определённого плагина аутентификации.

Connector/Python поддерживает для аутентификации без пароля. Клиенты Linux поддерживаются с Connector/Python 8.0.26, а поддержка Windows была добавлена в Connector/Python 8.0.27 с реализацией расширения C и в Connector/Python 8.0.29 с реализацией на чистом Python. Для Windows соответствующий параметр подключения kerberos_auth_mode был добавлен в 8.0.32 для настройки режима либо SSPI (по умолчанию), либо GSSAPI (через реализацию на чистом Python или реализацию расширения C с 8.4.0). Хотя Windows поддерживает оба режима, Linux поддерживает только GSSAPI.

При необходимости используйте сокращение [gssapi] при установке пакета mysql-connector-python pip для включения определённых версий GSSAPI, как определено коннектором, что на данный момент (Connector/Python 9.1.0) составляет v1.8.3:

$ pip install mysql-connector-python[gssapi]

Следующий пример предполагает, что настроен для использования аутентификации GSSAPI/Kerberos SASL:

import mysql.connector as cpy
import logging

logging.basicConfig(level=logging.DEBUG)

SERVICE_NAME = "ldap"
LDAP_SERVER_IP = "server_ip or hostname"  # e.g., winexample01

config = {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "myuser@example.com",
    "password": "s3cret",
    "use_pure": True,
    "krb_service_principal": f"{SERVICE_NAME}/{LDAP_SERVER_IP}"
}

with cpy.connect(**config) as cnx:
    with cnx.cursor() as cur:
        cur.execute("SELECT @@version")
        res = cur.fetchone()
        print(res[0])

Connector/Python поддерживает многофакторную аутентификацию (MFA) с версии 8.0.28, используя параметры подключения password1 (псевдоним password), password2 и password3.

Connector/Python поддерживает с Connector/Python 8.2.0, что поддерживается в MySQL Enterprise Edition. При необходимости используйте параметр подключения Connector/Python webauthn_callback для уведомления пользователей о необходимости взаимодействия с аппаратным устройством. Эта функциональность присутствует в реализации на C (которая использует libmysqlclient), но реализация на чистом Python требует зависимости FIDO2, которая не предоставляется с MySQL-коннектором и предполагается уже присутствующей в вашей среде. Она может быть установлена независимо с помощью:

$> pip install fido2

Ранее поддерживаемый (сейчас удалённый с версии 8.4.0) authentication_fido плагин MySQL Server поддерживался с помощью параметра fido_callback, который был доступен в реализации расширения C.

Connector/Python поддерживает OpenID Connect с Connector/Python 9.1.0. Функциональность включена с помощью клиентского плагина аутентификации authentication_openid_connect_client, подключающегося к MySQL Enterprise Edition с плагином аутентификации authentication_openid_connect. Эти примеры включают плагин с auth_plugin и определяют расположение файла токена JWT с openid_token_file:

# Standard connection
import mysql.connector as cpy
config = {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "openid_token_file": "{path-to-id-token-file}",
    "auth_plugin": "authentication_openid_connect_client",
    "use_pure": True, # Use False for C-Extension
}
with cpy.connect(**config) as cnx:
    with cnx.cursor() as cur:
        cur.execute("SELECT @@version")
        print(cur.fetchall())

# Or, using an async connection
import mysql.connector.aio as cpy_async
import asyncio
config = {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "auth_plugin": "authentication_openid_connect_client",
    "openid_token_file": "{path-to-id-token-file}",
}
async def test():
    async with await cpy_async.connect(**config) as cnx:
        async with await cnx.cursor() as cur:
            await cur.execute("SELECT @@version")
            print(await cur.fetchall())
asyncio.run(test())

Кодировка символов

По умолчанию строки, полученные из MySQL, возвращаются как литералы Unicode Python. Для изменения этого поведения установите use_unicode в False. Вы можете изменить кодировку для подключения клиента с помощью аргумента charset. Для изменения кодировки после подключения к MySQL установите свойство charset экземпляра MySQLConnection. Этот метод предпочтительнее использования SET NAMES SQL-запроса непосредственно. Аналогично свойству charset, можно установить collation для текущей MySQL-сессии.

Транзакции

Значение autocommit по умолчанию равно False, поэтому транзакции не коммитируются автоматически. Вызовите метод commit() экземпляра MySQLConnection в вашем приложении после выполнения набора связанных операций вставки, обновления и удаления. Для обеспечения согласованности данных и высокой производительности операций записи рекомендуется оставить параметр конфигурации autocommit выключенным при использовании InnoDB или других транзакционных таблиц.

Временные зоны

Временная зона может быть установлена для каждого подключения с помощью аргумента time_zone. Это полезно, например, если сервер MySQL настроен на UTC, и значения TIMESTAMP должны возвращаться MySQL, преобразованные в временную зону PST.

SQL-режимы

MySQL поддерживает так называемые SQL-режимы, которые изменяют поведение сервера глобально или для каждого подключения. Например, для вывода предупреждений в виде ошибок, установите sql_mode в TRADITIONAL. Более подробная информация доступна в .

Отладка и обработка ошибок

Предупреждения, сгенерированные запросами, извлекаются автоматически, когда get_warnings установлено в True. Вы также можете немедленно вызвать исключение, установив raise_on_warnings в True. Рассмотрите возможность использования настройки MySQL для преобразования предупреждений в ошибки.

Для установки значения таймаута для подключений используйте connection_timeout.

Включение и отключение функций с помощью флагов клиента

MySQL использует флаги клиента для включения или отключения функций. С помощью аргумента client_flags вы можете управлять настройками. Чтобы узнать какие флаги доступны, используйте следующее:

from mysql.connector.constants import ClientFlag
print '\n'.join(ClientFlag.get_full_info())

Если client_flags не указано (то есть равно нулю), используются значения по умолчанию для MySQL 4.1 и выше. Если вы указываете целое число большее, чем 0, убедитесь, что все флаги установлены корректно. Более удобный способ установки и отключения флагов по отдельности – использование списка. Например, для установки FOUND_ROWS, но отключения стандартного LONG_FLAG:

flags = [ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]
mysql.connector.connect(client_flags=flags)

Обработка наборов результатов

По умолчанию MySQL Connector/Python не буферизует и не предварительно извлекает результаты. Это означает, что после выполнения запроса ваша программа отвечает за извлечение данных. Это предотвращает чрезмерное использование памяти при возврате запросами больших наборов результатов. Если вам известно, что набор результатов достаточно мал для обработки сразу, вы можете извлечь результаты немедленно, установив buffered в True. Также возможно настроить это значение для каждого курсора (см. Раздел 10.2.6, «Метод MySQLConnection.cursor()»).

Результаты, сгенерированные запросами, обычно не считываются, пока их не запросит программа-клиент. Для автоматического потребления и отбрасывания наборов результатов установите параметр consume_results в True. Результатом является чтение всех результатов, что для больших наборов результатов может быть медленным. (В этом случае может быть предпочтительнее закрыть и открыть соединение.)

Преобразования типов

По умолчанию типы MySQL в наборах результатов автоматически преобразуются в типы Python. Например, значение столбца DATETIME становится объектом datetime.datetime. Для отключения преобразования установите параметр raw в True. Вы можете сделать это для повышения производительности или для выполнения других типов преобразований самостоятельно.

Подключение через SSL

Использование SSL-соединений возможно, когда ваша установка Python поддерживает SSL, то есть когда она скомпилирована с библиотеками OpenSSL. При указании параметров ssl_ca, ssl_key и ssl_cert соединение переключается на SSL, а параметр client_flags включает значение ClientFlag.SSL автоматически. Вы можете использовать это в сочетании с параметром compressed, установленным в True.

С Connector/Python 2.2.2, если сервер MySQL поддерживает SSL-соединения, Connector/Python пытается установить защищённое (шифрованное) соединение по умолчанию, переходя к незащищённому соединению в противном случае.

С Connector/Python 1.2.1 по Connector/Python 2.2.1 возможно установить SSL-соединение, используя только параметр ssl_ca. Параметры ssl_key и ssl_cert являются необязательными. Однако, если любой из них указан, оба должны быть указаны, иначе будет генерироваться AttributeError.

# Note (Example is valid for Python v2 and v3)
from __future__ import print_function

import sys

#sys.path.insert(0, 'python{0}/'.format(sys.version_info[0]))

import mysql.connector
from mysql.connector.constants import ClientFlag

config = {
    'user': 'ssluser',
    'password': 'password',
    'host': '127.0.0.1',
    'client_flags': [ClientFlag.SSL],
    'ssl_ca': '/opt/mysql/ssl/ca.pem',
    'ssl_cert': '/opt/mysql/ssl/client-cert.pem',
    'ssl_key': '/opt/mysql/ssl/client-key.pem',
}

cnx = mysql.connector.connect(**config)
cur = cnx.cursor(buffered=True)
cur.execute("SHOW STATUS LIKE 'Ssl_cipher'")
print(cur.fetchone())
cur.close()
cnx.close()

Пулы подключений

При использовании аргументов pool_name или pool_size, Connector/Python создает новый пул. Если аргумент pool_name не указан, вызов connect() автоматически генерирует имя, составленное из аргументов подключения host, port, user и database в указанном порядке. Если аргумент pool_size не указан, по умолчанию размер пула составляет 5 подключений.

Аргумент pool_reset_session позволяет управлять тем, сбрасываются ли переменные сеанса при возвращении подключения в пул. По умолчанию они сбрасываются.

Дополнительную информацию о пулах подключений см. в разделе 9.5 «Connector/Python Connection Pooling».

Сжатие протокола

Логический аргумент compress указывает, использовать ли сжатый протокол клиент/сервер (по умолчанию False). Это предоставляет более простой способ, чем установка флага ClientFlag.COMPRESS. Этот аргумент доступен начиная с Connector/Python 1.1.2.

Класс конвертера

Аргумент converter_class принимает класс и устанавливает его при настройке подключения. Если пользовательский класс конвертера не является подклассом класса conversion.MySQLConverterBase, возникает исключение AttributeError.

Переключение серверов

Метод connect() принимает аргумент failover, который предоставляет информацию для переключения серверов в случае сбоев подключения. Значение аргумента — кортеж или список словарей (кортеж предпочтительнее, т.к. он неизменяемый). Каждый словарь содержит аргументы подключения для заданного сервера в последовательности переключения. Разрешенные значения словаря: user, password, host, port, unix_socket, database, pool_name, pool_size. Этот вариант переключения был добавлен в Connector/Python 1.2.1.

Поддержка файлов конфигурации

Начиная с Connector/Python 2.0.0, поддержка файлов конфигурации реализована с использованием двух вариантов для connect():

Более подробная информация содержится в разделе 7.2 «Connector/Python Option-File Support».

LOAD DATA LOCAL INFILE

До версии Connector/Python 2.0.0 пользователям приходилось явно устанавливать флаг ClientFlag.LOCAL_FILES для использования данной функции. Начиная с версии 2.0.0, этот флаг включен по умолчанию. Для его отключения, опция подключения allow_local_infile может быть установлена в значение False во время подключения (по умолчанию — True).

Совместимость с другими интерфейсами подключения

passwd, db и connect_timeout допустимы для совместимости с другими интерфейсами MySQL и соответствуют соответственно password, database и connection_timeout. Последние имеют приоритет. Синтаксис имени источника данных или dsn не используется; если он указан, генерируется исключение NotSupportedError.

Реализация протокола клиент/сервер

Connector/Python может использовать чистый Python-интерфейс к MySQL или C-расширение, использующее библиотеку MySQL C-клиента. Аргумент подключения use_pure mysql.connector.connect() определяет, какой вариант использовать. Значение по умолчанию в Connector/Python 8 изменилось с True (использование чистого Python-реализации) на False. Установка use_pure меняет используемую реализацию.

Аргумент use_pure доступен начиная с Connector/Python 2.1.1. Для получения дополнительной информации о C-расширении, см. главу 8 «The Connector/Python C Extension».