Connector/Python обеспечивает вызов connect()
, чтобы установить связь с сервером MySQL. Следующие разделы описывают
разрешенные аргументы в connect()
и описывает,
как использовать файлы опций, которые поставляют дополнительные аргументы.
Связь с сервером MySQL может быть установлена, используя функцию
mysql.connector.connect()
или класс
mysql.connector.MySQLConnection()
:
cnx = mysql.connector.connect(user='joe', database='test') cnx = MySQLConnection(user='joe', database='test')
Следующая таблица описывает аргументы, которые могут использоваться, чтобы начать связь. Звездочка (*) после аргумента указывает на синонимичное имя аргумента, доступное только для совместимости с другими драйверами Python MySQL. Oracle рекомендует не использовать эти альтернативные имена.
Таблица 7.1. Аргументы соединения для Connector/Python
Имя аргумента | Значение по умолчанию | Описание |
---|---|---|
user
(username *) | Имя пользователя для сервера MySQL. | |
password
(passwd *) |
Пароль пользователя для сервера MySQL. | |
database
(db *) | Имя базы данных, чтобы использовать, соединяясь с сервером MySQL. | |
host |
127.0.0.1 | Имя хоста или IP-адрес сервера MySQL. |
port |
3306 | Порт TCP/IP сервера MySQL. Должно быть целое число. |
unix_socket | Местоположение файла сокета Unix. | |
auth_plugin |
Плагин идентификации, добавлено в 1.2.1. | |
use_unicode |
True |
Использовать ли Unicode. |
charset |
utf8 |
Какой набор символов MySQL использовать. |
collation |
utf8mb4_general_ai_ci (это
utf8_general_ci в 2.x |
Какое сопоставление MySQL использовать. Значения по умолчанию в 8.x произведены от значений по умолчанию последнего MySQL Server 8.0. |
autocommit |
False |
Включен ли autocommit. |
time_zone |
Установить переменную сеанса
time_zone во время связи. | |
sql_mode | Установить переменную сеанса sql_mode
во время связи. | |
get_warnings |
False |
Получать ли предупреждения. |
raise_on_warnings |
False |
Поднять ли исключение на предупреждениях. |
connection_timeout
(connect_timeout *) |
Тайм-аут для TCP и сокетных соединений Unix. | |
client_flags |
Флаги клиента MySQL. | |
buffered |
False |
Приносят ли объекты курсора немедленно результаты после выполнения запросов. |
raw |
False |
Возвращены ли результаты MySQL как есть, а не преобразованы в типы Python. |
consume_results |
False | Прочитать ли автоматически наборы результатов. |
ssl_ca |
Файл, содержащий сертификат SSL авторизации. | |
ssl_cert |
Файл, содержащий сертификат SSL. | |
ssl_disabled |
False |
True выключает SSL/TLS,
добавлено в Connector/Python 2.1.7. |
ssl_key |
Файл, содержащий ключ SSL. | |
ssl_verify_cert |
False |
Когда установлено в True , проверяет
сертификат сервера с файлом сертификата, определенным опцией
ssl_ca . Любое несоответствие вызывает исключение
ValueError . |
ssl_verify_identity |
False |
Когда установлено в True ,
дополнительно выполните проверку идентичности имени хоста, проверив имя
хоста, которое клиент использует для соединения с сервером по сертификату,
который сервер посылает клиенту.
Добавлено в Connector/Python 8.0.14. |
force_ipv6 |
False |
Когда установлено в True , применяет IPv6,
когда адрес разрешается в IPv4 и IPv6. По умолчанию IPv4
используется в таких случаях. |
dsn | Не поддержано (поднимает исключение
NotSupportedError , когда используется). | |
pool_name | Название пула связи. Ограничивается алфавитно-цифровыми символами и
специальными символами . ,
_ , * ,
$ и # .
Название пула должно быть не больше
pooling.CNX_POOL_MAXNAMESIZE
символов (по умолчанию 64). | |
pool_size |
5 | Размер пула связи должен быть больше 0 и меньше или равным
pooling.CNX_POOL_MAXSIZE
(по умолчанию 32). |
pool_reset_session |
True | Перезагрузить ли переменные сеанса, когда связь возвращена в пул. |
compress |
False |
Использовать ли сжатый протокол клиент-сервер. |
converter_class |
Класс конвертера, чтобы использовать. | |
failover |
Последовательность отказоустойчивости сервера. | |
option_files |
Какие файлы опций прочитать. Добавлено в 2.0.0. | |
option_groups |
['client', 'connector_python'] |
Какие группы прочитать из файлов опций. Добавлено в 2.0.0. |
allow_local_infile |
True |
Позволить ли LOAD DATA LOCAL INFILE .
Добавлено в 2.0.0. |
use_pure |
False в 8.0.11 и
True более ранних версиях. Если только одна
реализация (C или Python) доступна, то значение по умолчанию собирается
позволить доступную реализацию. |
Использовать ли чистый Python или расширение C. Если
use_pure=False и C расширение недоступно,
Connector/Python автоматически отступит к чистому Python.
Может быть установлено с
mysql.connector.connect(), но не с
MySQLConnection.connect().
Добавлено в 2.1.1. |
Идентификация с использованием MySQL
username
и
password
.
MySQL Connector/Python не поддерживает старые протоколы MySQL до 4.1.
Когда аргумент database
дан, текущая база
данных установлена в данное значение. Чтобы изменить текущую базу данных
позже, выполните SQL-запрос USE
или установите
свойство database
экземпляра
MySQLConnection
.
По умолчанию Connector/Python пытается соединиться с сервером MySQL,
работающим на местном хосте, использующем TCP/IP.
host
по умолчанию установлен к IP-адресу
127.0.0.1 и port
к 3306.
Unix сокеты поддерживаются, устанавливая
unix_socket
.
Именованные каналы на платформе Windows не поддерживаются.
Connector/Python 1.2.1 и выше понимает
плагины идентификации, доступные с MySQL 5.6. Это включает
mysql_clear_password
и
sha256_password
,
оба из которых требуют связи SSL.
Плагин sha256_password
не работает по не-SSL связи, потому что Connector/Python
не поддерживает шифрование RSA.
Метод connect()
понимает параметр
auth_plugin
, который может использоваться, чтобы
вызвать использование конкретного плагина. Например, если сервер формируется,
чтобы использовать sha256_password
по умолчанию
и вы хотите соединиться с учетной записью, которая подтверждает подлинность
использованием mysql_native_password
,
соединитесь с использованием SSL или определите
auth_plugin='mysql_native_password'
.
По умолчанию последовательности, прибывающие из MySQL, возвращены как
литералы Unicode. Чтобы изменить это поведение, установите
use_unicode
= False
.
Можно изменить настройки для связи клиента через параметр
charset
. Чтобы изменить набор символов после
соединения с MySQL, установите свойство charset
экземпляра MySQLConnection
.
Эта техника предпочтительней использования SQL-запроса
SET NAMES
напрямую.
Подобно свойству charset
можно установить
collation
для текущей сессии MySQL.
Значение autocommit
по умолчанию
False
, таким образом, транзакции
автоматически не передаются. Вызовите метод
commit()
экземпляра
MySQLConnection
в рамках вашего приложения после выполнения ряда связанных действий.
Для непротиворечивости данных и высокой пропускной способности для операций
записи лучше оставить параметр конфигурации
autocommit
выключенным, используя
InnoDB
или другие транзакционные таблицы.
Часовой пояс может быть установлен для каждого подключения параметром
time_zone
.
Это полезно, например, если сервер MySQL установлен в UTC и значения
TIMESTAMP
должны быть возвращены MySQL,
преобразованными в часовой пояс PST
.
MySQL поддерживает так называемые режимы SQL, которые изменяют поведение
сервера глобально или для каждого подключения. Например, чтобы поднять
предупреждения как ошибки, установите sql_mode
=
TRADITIONAL
.
Для получения дополнительной информации посмотрите
Server SQL Modes.
Предупреждения, произведенные запросами, получены автоматически, когда
get_warnings
= True
.
Можно также немедленно поднять исключение, установив
raise_on_warnings
=
True
. Рассмотрите использование
sql_mode для того, чтобы
превратить предупреждения в ошибки.
Чтобы установить значение тайм-аута для связей, надо использовать
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).
Результаты, произведенные запросами, обычно не читаются, пока программа
клиента не забирает их. Чтобы автоматически потреблять и отказаться от
наборов результатов, установите опцию
consume_results
=
True
. Результат состоит в том, что все
результаты прочитаны, что для больших наборов результатов может быть
медленным процессом. В этом случае могло бы быть предпочтительно закрыть и
вновь открыть связь.
По умолчанию типы MySQL в наборах результатов преобразовываются
автоматически в типы Python. Например, значение столбца
DATETIME
становится объектом
datetime.datetime. Чтобы отключить преобразование,
установите опцию raw
=
True
. Вы могли бы сделать это, чтобы получить
лучшую работу или выполнить различные типы преобразования сами.
Использование связи 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.1.
Параметр boolean compress
указывает, использовать ли сжатый протокол клиент-сервер
(по умолчанию False
).
Это обеспечивает более легкую альтернативу флагу
ClientFlag.COMPRESS
.
Этот аргумент доступен с Connector/Python 1.1.2.
Аргумент converter_class
берет класс и устанавливает его, формируя связь.
Исключение AttributeError
поднято, если класс
конвертера не подкласс conversion.MySQLConverterBase
.
Метод connect()
принимает аргумент
failover
, который предоставляет информацию,
чтобы использовать для отказоустойчивости сервера в случае неудач связи.
Значение аргумента кортеж или список словарей (кортеж предпочтен, потому что
это неизменчиво). Каждый словарь содержит аргументы соединения для данного
сервера в последовательности отказоустойчивости.
Разрешенные значения словаря: user
,
password
, host
,
port
, unix_socket
,
database
, pool_name
,
pool_size
.
Добавлена опция в Connector/Python 1.2.1.
С Connector/Python 2.0.0 файлы опций поддерживаются, используя две
возможности для connect()
:
option_files
:
Какие файлы прочитать. Значение может быть путем к файлу (строка) или
последовательностью строк. По умолчанию Connector/Python не читает файлов
опций, таким образом, этот аргумент должен быть дан явно, чтобы заставить
файлы быть прочитанными. Файлы прочитаны в определенном порядке.
option_groups
:
Какие группы прочитать в файлах опций. Значение может быть названием группы
опций (строка) или последовательностью строк названий групп.
Если этот аргумент не дан, значение по умолчанию
['client', 'connector_python']
читает группы
[client]
и
[connector_python]
.
Для получения дополнительной информации посмотрите раздел 7.2.
До Connector/Python 2.0.0, чтобы позволить использование
LOAD DATA LOCAL INFILE
,
клиенты должны были явно установить флаг
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, которое пользуется библиотекой клиента. Параметр
use_pure
в
mysql.connector.connect() определяет
это. Умолчание изменено в Connector/Python 8 с
True
(использовать Python) на
False
.
Установка use_pure
изменяет используемое внедрение.
Параметр use_pure
доступен с Connector/Python 2.1.1. Для получения дополнительной информации о
расширении C см. главу 8.
С версии 2.0.0 Connector/Python имеет способность чтения опций из файлов
(для получения общей информации о файлах опций в MySQL посмотрите
Using Option Files). Два аргумента
connect()
управляют использованием файлов опций
в программах Connector/Python:
option_files
:
Какие файлы прочитать. Значение может быть путем к файлу (строка) или
последовательностью строк. По умолчанию Connector/Python не читает файлов
опций, таким образом, этот аргумент должен быть дан явно, чтобы заставить
файлы быть прочитанными. Файлы прочитаны в определенном порядке.
option_groups
:
Какие группы прочитать в файлах опций. Значение может быть названием группы
опций (строка) или последовательностью строк названий групп.
Если этот аргумент не дан, значение по умолчанию
['client', 'connector_python']
читает группы
[client]
и
[connector_python]
.
Connector/Python также поддерживает директивы включения
!include
и
!includedir
в файлах.
Эти директивы работают так же, как другие программы MySQL (см.
Using Option Files).
Этот пример определяет единственный файл опций как строку:
cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf')
Этот пример определяет много файлов опций как последовательность строк:
mysql_option_files = [ '/etc/mysql/connectors.cnf', './development.cnf', ] cnx = mysql.connector.connect(option_files=mysql_option_files)
Connector/Python не читает файлов опций по умолчанию для обратной
совместимости с версиями, более старыми, чем 2.0.0. Это отличается от
типичных клиентов MySQL, таких как
mysql или
mysqldump,
которые действительно читают файлы по умолчанию. Чтобы узнать, какие файлы
опций читают типичные клиенты на вашей системе, вызовите одного из них с
опцией --help
и изучите вывод. Например:
shell> mysql --help
...
Default options are read from the following files in the given order:
/etc/my.cnf /etc/mysql/my.cnf /usr/local/mysql/etc/my.cnf ~/.my.cnf
...
Если вы определяете аргумент соединения
option_files
, чтобы прочитать файлы,
Connector/Python читает по умолчанию группы опций
[client]
и
[connector_python]
.
Чтобы определить явно которые группы читать, используйте аргумент соединения
option_groups
. Следующий пример читает только
группу [connector_python]
:
cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf', option_groups='connector_python')
Другие аргументы соединения, определенные в вызове
connect()
, имеют приоритет перед опциями,
прочитанными из файлов. Предположим, что
/etc/mysql/connectors.conf
содержит эти строки:
[client] database=cpyapp
Следующий вызов connect()
не включает
database
. Получающаяся связь использует
cpyapp
, базу данных,
определенную в файле опций:
cnx = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf')
В отличие от этого, следующий вызов connect()
определяет базу данных по умолчанию, отличающуюся от найденной в файле опций.
Связь в итоге использует cpyapp_dev
как базу
данных по умолчанию, а не cpyapp
:
cnx2 = mysql.connector.connect(option_files='/etc/mysql/connectors.cnf', database='cpyapp_dev')
Connector/Python поднимает исключение
ValueError
, если файл опций не может быть
прочитан или уже был прочитан. Это включает файлы,
прочитанные директивами включения.
Для группы [connector_python]
допустимы только опции, поддержанные Connector/Python.
Непризнанные опции вызывают исключение
ValueError
.
Для других групп Connector/Python игнорирует непризнанные опции.
Если названная группа не существует, это не ошибка.
Connector/Python рассматривает значения опций в файлах как строки
и оценивает их с использованием eval()
.
Это позволяет спецификацию значений опций более сложных, чем простые скаляры.