Эта глава содержит описание API для Connector/Python.
Примеры нужно рассмотреть, работая на Python 2.7 или Python 3.1 и выше.
Они могли бы также работать на более старых версиях (таких как Python 2.4),
если они не используют функции, введенные в более новых версиях Python.
Например, обработка исключений используя ключевое слово
as
была введена в Python 2.6
и не будет работать в Python 2.4.
Следующий обзор показывает пакет
mysql.connector
с его модулями.
В настоящее время только самые полезные модули, классы и методы для
конечных пользователей описаны.
mysql.connector errorcode errors connection constants conversion cursor dbapi locales eng client_error protocol utils
Модуль mysql.connector
предоставляет методы и свойства верхнего уровня.
Этот метод настраивает связь, устанавливая сессию связи с сервером MySQL. Если никакие аргументы не даны, это использует уже заданные или значения по умолчанию. Для полного списка возможных аргументов посмотрите раздел 7.1.
Связь с сервером MySQL может быть установлена, используя метод
mysql.connector.connect()
или класс
mysql.connector.MySQLConnection()
:
cnx = mysql.connector.connect(user='joe', database='test') cnx = MySQLConnection(user='joe', database='test')
Для описаний методов связи и свойств, посмотрите раздел 10.2.
Это свойство последовательность, которая указывает на поддержанный уровень API DB.
>>> mysql.connector.apilevel '2.0'
Это свойство последовательность, которая указывает на стиль параметра Connector/Python по умолчанию.
>>> mysql.connector.paramstyle 'pyformat'
Это свойство целое число, которое указывает на поддержанный уровень потокобезопасности, обеспеченной Connector/Python.
>>> mysql.connector.threadsafety 1
Это свойство указывает версию Connector/Python как строку. Это доступно с Connector/Python 1.1.0.
>>> mysql.connector.__version__ '1.1.0'
Это свойство указывает версию Connector/Python как множество компонентов версии. Это доступно с Connector/Python 1.1.0.
>>> mysql.connector.__version_info__ (1, 1, 0, 'a', 0)
Класс MySQLConnection
используется, чтобы открыть и управлять связью с сервером MySQL.
Это также раньше посылало команды и SQL-операторы и читало результаты.
Синтаксис:
cnx = MySQLConnection(**kwargs)
Конструктор MySQLConnection
инициализирует атрибуты и когда по крайней мере один аргумент передается, он
пытается соединиться с сервером MySQL.
Для полного списка аргументов посмотрите раздел 7.1.
Синтаксис:
cnx.close()
close()
синоним
disconnect()
. См.
раздел
10.2.20.
Для связи, полученной из пула связи, close()
на самом деле не закрывает ее, а возвращает в пул и делает доступной для
последующих запросов связи. Посмотрите
раздел 9.1.
Этот метод посылает COMMIT
серверу MySQL,
передавая текущую транзакцию. Connector/Python по умолчанию не делает
autocommit, поэтому важно вызвать этот метод после каждой транзакции, которая
изменяет данные для таблиц с транзакционным механизмом хранения.
>>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane')) >>> cnx.commit()
Чтобы откатиться назад вместо этого и отказаться от модификаций, посмотрите метод rollback().
Синтаксис:
cnx.config(**kwargs)
Формирует экземпляр MySQLConnection
после того, как это создано. Для полного списка возможных аргументов
посмотрите раздел
7.1.
Параметры:
kwargs
: Аргументы соединения.
Вы могли использовать метод config()
,
чтобы изменить (например), имя пользователя, а затем вызвать
reconnect()
.
Пример:
cnx = mysql.connector.connect(user='joe', database='test') # Connected as 'joe' cnx.config(user='jane') cnx.reconnect() # Now connected as 'jane'
Для связи, полученной из пула связи,
config()
поднимает исключение. Посмотрите
раздел 9.1.
Синтаксис:
MySQLConnection.connect(**kwargs)
Этот метод настраивает связь, устанавливая сессию с сервером MySQL. Если никакие аргументы не даны, это использует уже настроенные или значения по умолчанию. Для полного списка возможных аргументов посмотрите раздел 7.1.
Параметры:
kwargs
: Аргументы соединения.
Пример:
cnx = MySQLConnection(user='joe', database='test')
Для связи, полученной из пула связи, класс объекта связи
PooledMySQLConnection
.
Объединенная связь отличается от необъединенной связи, как описано в
разделе 9.1.
Синтаксис:
cursor = cnx.cursor([arg=value[, arg=value]...])
Этот метод возвращает объект MySQLCursor()
или его подкласс в зависимости от передаваемых аргументов.
Возвращенный объект это экземпляр
cursor.CursorBase
.
Для получения дополнительной информации об объектах курсора, посмотрите
разделы 10.5 и
10.6.
Аргументы могут быть переданы методу
cursor()
, чтобы контролировать,
какой курсор создать:
Если buffered
=
True
, курсор приносит все строки от сервера
после того, как операция будет выполнена. Это полезно, когда запросы
возвращают небольшие наборы результатов.
buffered
может использоваться один или в
сочетании с параметром dictionary
или
named_tuple
.
buffered
может также быть передан
connect()
, чтобы установить способ
буферизации по умолчанию для всех курсоров, созданных из объекта связи.
Посмотрите раздел 7.1.
Для получения информации о о последствиях буферизования посмотрите раздел 10.6.1 .
Если raw
=
True
, курсор пропускает преобразование от типов
данных MySQL в типы Python. Сырой курсор обычно используется, чтобы получить
лучшую производительность или когда вы хотите сделать преобразование сами.
raw
может также быть передан
connect()
, чтобы установить режим без
предварительной обработки по умолчанию для всех курсоров, созданных из
объекта связи. Посмотрите
раздел 7.1.
Если dictionary
=
True
, курсор возвращает строки как словари.
Этот аргумент доступен с Connector/Python 2.0.0.
Если named_tuple
=
True
, курсор возвращает строки как названные
кортежами. Этот аргумент доступен с Connector/Python 2.0.0.
Если prepared
=
True
, курсор используется для выполнения
подготовленных запросов. Этот аргумент доступен с Connector/Python 1.1.2.
Расширение C поддерживает это с Connector/Python 8.0.17.
Параметр cursor_class
может использоваться, чтобы передать класс для того, чтобы создать
новый курсор. Это должен быть подкласс
cursor.CursorBase
.
Возвращенный объект зависит от комбинации аргументов. Примеры:
Если not buffered and not raw:
MySQLCursor
.
Если buffered and not raw:
MySQLCursorBuffered
.
Если not buffered and raw: MySQLCursorRaw
.
Если buffered and raw:
MySQLCursorBufferedRaw
.
Изменяет пользователя, использующего username
и password
. Это также назначит указанную
database
базой данных по умолчанию.
Также возможно изменить набор символов, используя параметр
charset
.
Синтаксис:
cnx.cmd_change_user(username='', password='', database='', charset=33)
Возвращает словарь, содержащий OK информацию о пакете.
Приказывает серверу писать отладочную информацию в журнал ошибок.
Подключенный пользователь должен иметь привилегию
SUPER
.
Возвращает словарь, содержащий OK информацию о пакете.
Синтаксис:
cnx.cmd_init_db(db_name)
Этот метод делает определенную базу данных базой данных по умолчанию. В последующих запросах эта база данных будет умолчанием для ссылок на таблицу, которые не включают явного определителя базы данных.
Возвращает словарь, содержащий OK информацию о пакете.
Проверка, работает ли связь с сервером.
Этот метод не должен использоваться непосредственно. Используйте ping() или is_connected().
Возвращает словарь, содержащий OK информацию о пакете.
Этот метод поднимает исключение NotSupportedError.
Вместо этого используйте SHOW PROCESSLIST
или запрос таблицы в базе данных
INFORMATION_SCHEMA
.
Эта функциональность MySQL Server устарела.
Синтаксис:
cnx.cmd_process_kill(mysql_pid)
Эта функциональность MySQL Server устарела.
Просит сервер убить поток mysql_pid
.
Хотя все еще доступно, лучше использовать SQL-оператор
KILL
.
Возвращает словарь, содержащий OK информацию о пакете.
Следующие две строки имеют тот же самый эффект:
>>> cnx.cmd_process_kill(123) >>> cnx.cmd_query('KILL 123')
Синтаксис:
cnx.cmd_query(statement)
Этот метод посылает данный statement
серверу MySQL и получает результат. Чтобы послать многочисленные запросы,
используйте
cmd_query_iter().
Возвращенный словарь содержит информацию в зависимости от того, какой
запрос был выполнен. Если запрос
SELECT
, результат содержит информацию о
столбцах. Другие запросы возвращают словарь, содержащий OK или EOF.
Ошибки, полученные от сервера MySQL, подняты как исключения.
InterfaceError
поднято, когда
многократные результаты найдены.
Возвращает словарь.
Синтаксис:
cnx.cmd_query_iter(statement)
Аналог
cmd_query(), но вернет объект генератора для итерации результата.
Используйте cmd_query_iter()
посылая
многочисленные запросы и отделяете запросы точками с запятой.
Следующий пример показывает, как работать с результатами после отправки многочисленных запросов:
statement = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2' for result in cnx.cmd_query_iter(statement): if 'columns' in result: columns = result['columns'] rows = cnx.get_rows() else: # do something useful with INSERT result
Возвращает объект генератора.
Этот метод посылает QUIT
серверу MySQL,
закрывая текущую связь. С тех пор от сервера MySQL нет никакого ответа,
пакет, который послали, возвращен.
Синтаксис:
cnx.cmd_refresh(options)
Эта функциональность MySQL Server устарела.
Этот метод сбрасывает таблицы или кэши или информацию о сервере
репликации. Подключенный пользователь должен иметь привилегию
RELOAD
.
options
должен быть значением битовой маски,
построенной, используя константы из класса
constants.RefreshOption
.
Для списка вариантов посмотрите раздел 10.11.
Пример:
>>> from mysql.connector import RefreshOption >>> refresh = RefreshOption.LOG | RefreshOption.THREADS >>> cnx.cmd_refresh(refresh)
Синтаксис:
cnx.cmd_reset_connection()
Перезагружает связь, посылая
COM_RESET_CONNECTION
серверу, чтобы очистить состояние сеанса.
Этот метод разрешает состоянию сеанса быть очищенным без
переподтверждения. Для серверов MySQL, более старых, чем 5.7.3 (когда
был введен COM_RESET_CONNECTION
),
должен использоваться метод
reset_session()
.
Этот метод перезагружает состояние сеанса, повторно подтверждая подлинность,
что является более дорогим.
Этот метод добавлен в Connector/Python 1.2.1.
Эта функциональность MySQL Server устарела.
Просит сервер базы данных завершиться. Подключенный пользователь должен
иметь привилегию SHUTDOWN
.
Возвращает словарь, содержащий OK информацию о пакете.
Возвращает словарь, содержащий информацию о сервере MySQL включая продолжительность работы в секундах и количество работающих потоков, запросов, перезагрузок и открытых таблиц.
Этот метод пытается послать QUIT
и
закрыть сокет. Это не поднимает исключений.
MySQLConnection.close()
синоним
этого метода и чаще всего используемый.
Чтобы закрыть связь, не посылая QUIT
,
используйте
shutdown()
.
Этот метод восстанавливает следующую строку набора результата запроса, возвращая кортеж.
Кортеж, возвращенный get_row()
состоит из:
Строка как кортеж, содержащий объекты байта или
None
, когда больше строк недоступно.
EOF как словарь, содержащий
status_flag
и
warning_count
или
None
,
когда возвращенная строка не является последней.
Метод get_row()
используется
MySQLCursor,
чтобы получить строки.
Синтаксис:
cnx.get_rows(count=None)
Этот метод получает все или остающиеся строки набора результата запроса,
возвращая кортеж, содержащий строки как последовательности и EOF.
Аргумент количества может использоваться, чтобы получить заданное количество
строк. Если количество не определяется или None
,
все строки возвращаются.
Кортеж, возвращенный get_rows()
состоит из:
Список кортежей, содержащих данные о строке как байт-объекты или пустой список, когда никакие строки недоступны.
EOF как словарь, содержащий
status_flag
и
warning_count
.
InterfaceError
поднято, когда все
строки были получены.
MySQLCursor
использует метод get_rows()
,
чтобы получить строки.
Возвращает кортеж.
Этот метод возвращает информацию о сервере MySQL дословно как
последовательность, например, '5.6.11-log'
или
None
, если не связан.
Этот метод возвращает версию сервера MySQL как кортеж или
None
, если не связан.
Сообщает, доступна ли связь с MySQL Server.
Этот метод проверяет, является ли связь с MySQL доступной, используя
метод ping()
, но в отличие от этого ping()
,
is_connected()
вернет
True
, когда связь доступна,
False
иначе.
Синтаксис:
cnx.isset_client_flag(flag)
Этот метод вернет True
, если флаг клиента был
установлен, False
иначе.
Синтаксис:
cnx.ping(reconnect=False, attempts=1, delay=0)
Проверяет, доступна ли связь с сервером MySQL.
Когда reconnect
=
True
, сделано
attempts
попыток снова соединиться с сервером
MySQL, и эти опции отправлены методу
reconnect(). Используйте метод delay
(секунды), если вы хотите ждать перед каждой повторной попыткой.
Когда связь недоступна, InterfaceError
поднято. Используйте метод
is_connected(), чтобы проверить связь, не поднимая ошибку.
Поднимает на ошибках InterfaceError
.
Синтаксис:
cnx.reconnect(attempts=1, delay=0)
Попытка снова соединиться с сервером MySQL.
Аргумент attempts
определяет число раз, которое надо попробовать снова соединиться.
Аргумент delay
это
число секунд, которое ждать перед каждой повторной попыткой.
Вы могли бы определить число попыток выше и использовать более длинную задержку, когда вы ожидаете, что сервер MySQL остановлен для обслуживания, или когда вы будете ожидать, что сеть будет временно недоступна.
Синтаксис:
cnx.reset_session(user_variables = None, session_variables = None)
Перезагружает связь, повторно подтверждая подлинность, чтобы очистить
состояние сеанса. user_variables
, если задан,
это словарь имен и значений пользовательских переменных.
session_variables
, если задан, это словарь
словарь имен и значений системных переменных.
Метод устанавливает каждую переменную в данное значение.
Пример:
user_variables = {'var1': '1', 'var2': '10'} session_variables = {'wait_timeout': 100000, 'sql_mode': 'TRADITIONAL'} self.cnx.reset_session(user_variables, session_variables)
Этот метод перезагружает состояние сеанса, повторно подтверждая
подлинность. Для серверов MySQL 5.7 или выше
cmd_reset_connection()
более легкая альтернатива.
Этот метод добавлен в Connector/Python 1.2.1.
Этот метод посылает серверу MySQL запрос
ROLLBACK
, отменяя все изменения данных от
текущей транзакции. По умолчанию Connector/Python не делает autocommit,
таким образом, возможно отменить транзакции, используя механизмы
хранения транзакций, например, InnoDB
.
>>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane')) >>> cnx.rollback()
Чтобы передать модификации, посмотрите метод commit().
Синтаксис:
cnx.set_charset_collation(charset=None, collation=None)
Этот метод устанавливает набор символов и сопоставление для текущей связи.
Параметр charset
может быть названием набора
символов или числовым эквивалентом, как определено в
constants.CharacterSet
.
Когда collation
=
None
, используется сопоставление по умолчанию
для набора символов.
В следующем примере мы устанавливаем набор символов в
latin1
и сопоставление в
latin1_swedish_ci
(сопоставление по умолчанию
для latin1
):
>>> cnx = mysql.connector.connect(user='scott') >>> cnx.set_charset_collation('latin1')
Определите данное сопоставление следующим образом:
>>> cnx = mysql.connector.connect(user='scott') >>> cnx.set_charset_collation('latin1', 'latin1_general_ci')
Синтаксис:
cnx.set_client_flags(flags)
Этот метод устанавливает флаги клиента, соединяясь с сервером MySQL и
возвращает новое значение как целое число.
Параметр flags
может быть целым числом или
последовательностью действительных флаговых значений клиента (см.
раздел 10.7).
Если flags
последовательность, каждый пункт в
последовательности устанавливает флаг, когда значение положительно или
сбрасывает его, когда отрицательно. Например, чтобы сбросить
LONG_FLAG
и установить
FOUND_ROWS
:
>>> from mysql.connector.constants import ClientFlag >>> cnx.set_client_flags([ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]) >>> cnx.reconnect()
Флаги клиента устанавливаются или используются только соединяясь с сервером MySQL. Поэтому необходимо снова соединиться после внесения изменений.
Этот метод закрывает сокет. Это не поднимает исключений.
В отличие от этого,
disconnect()
,
shutdown()
закрывает связь клиента, не пытаясь сначала послать
QUIT
серверу. Таким образом это не заблокирует,
если связь будет разрушена по некоторым причинам, например,
из-за отказа сети.
shutdown()
добавлен в Connector/Python 2.0.1.
Этот метод начинает транзакцию. Это принимает аргументы, указывающие, использовать ли последовательный снимок, который уровень изоляции транзакции нужен и операционный режим доступа:
cnx.start_transaction(consistent_snapshot=bool
, isolation_level=level
, readonly=access_mode
)
По умолчанию consistent_snapshot
=
False
. Если значение
True
, Connector/Python посылает
WITH CONSISTENT SNAPSHOT
с запросом.
MySQL игнорирует это для уровней изоляции, для которых не
применяется этот вариант.
По умолчанию isolation_level
=
None
, разрешенные значения:
'READ UNCOMMITTED'
,
'READ COMMITTED'
,
'REPEATABLE READ'
и
'SERIALIZABLE'
. Если
isolation_level
=
None
, никакой уровень изоляции не посылают,
таким образом, применяется уровень по умолчанию.
Параметр readonly
может быть
True
, чтобы начать транзакцию в режиме
READ ONLY
или False
для режима READ WRITE
. Если
readonly
пропущен,
режим доступа сервера по умолчанию используется.
Для получения дополнительной информации об операционном режиме доступа см.
описание для START TRANSACTION
в
START TRANSACTION, COMMIT, and ROLLBACK Statements.
Если сервер более старый, чем MySQL 5.6.5, он не поддерживает настройку
режима доступа, и Connector/Python поднимает исключение
ValueError
.
Вызов start_transaction()
поднимает
исключение ProgrammingError
, если вызван
в то время, как происходит транзакция. Это отличается от выполнения
SQL-запроса START TRANSACTION
в то время как происходит транзакция: запрос неявно
передает текущую транзакцию.
Чтобы определить, активна ли транзакция для связи, используйте свойство in_transaction.
start_transaction()
добавлен в
MySQL Connector/Python 1.1.0. Параметр readonly
добавлен в Connector/Python 1.1.5.
Этому свойству можно назначить значение True
или False
, чтобы позволить или отключить
autocommit в MySQL. Свойство может быть вызвано, чтобы
узнать значение autocommit.
Autocommit отключен по умолчанию, соединяясь через Connector/Python.
Это может быть позволено, используя
параметр соединения autocommit
.
Когда autocommit выключен, необходимо
передавать
транзакции, используя механизмы системы хранения транзакций, например,
InnoDB
или
NDBCluster
.
>>> cnx.autocommit False >>> cnx.autocommit = True >>> cnx.autocommit True
Указывает, есть ли непрочитанный результат. Это установлено в
False
, если нет непрочитанного результата, иначе
True
. Это используется курсорами, чтобы
проверить, должен ли другой курсор все еще получить свой набор результатов.
Не устанавливайте значение этому свойству, поскольку только соединитель должен изменить значение. Другими словами, рассматривайте это как свойство только для чтения.
Это свойство указывает на значение параметра связи
consume_results
, который управляет, прочитаны ли
наборы результатов, произведенные запросами автоматически. См.
раздел 7.1.
Это добавлено в Connector/Python 2.1.1.
Это свойство возвращает последовательность, указывающую, какой набор символов используется для связи.
Это свойство возвращает последовательность, указывающую, какое сопоставление используется для связи.
Это свойство возвращает ID связи (ID потока или сессии)
для текущей связи (целое число) или
None
, если нет связи.
Это свойство устанавливает текущую базу данных, выполняя запрос
USE
. Свойство может также использоваться, чтобы
узнать текущее имя базы данных.
>>> cnx.database = 'test' >>> cnx.database = 'mysql' >>> cnx.database u'mysql'
Возвращает последовательность.
Этому свойству можно назначить значение True
или False
, чтобы позволить или отключить
автоматическое получение предупреждений.
Умолчание False
. Свойство может быть применено,
чтобы узнать текущее состояние предупреждений.
Получение предупреждений автоматически может быть полезным, отлаживая запросы. Курсоры делают предупреждения доступными через метод MySQLCursor.fetchwarnings().
>>> cnx.get_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() [(1.0,)] >>> cursor.fetchwarnings() [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")]
Возвращает True
или
False
.
Это свойство вернет True
или
False
, чтобы указать, активна ли транзакция для
связи. Значение True
независимо от того, начинаете ли вы транзакцию, используя вызов API
start_transaction()
или непосредственно выполняя SQL-оператор
START TRANSACTION
или
BEGIN
.
>>> cnx.start_transaction() >>> cnx.in_transaction True >>> cnx.commit() >>> cnx.in_transaction False
in_transaction
добавлено в
MySQL Connector/Python 1.1.0.
Этому свойству можно назначить значение True
или False
, чтобы позволить или отключить, должны
ли предупреждения поднять исключения. Умолчание
False
. Свойство может быть использовано, чтобы
узнать текущий режим исключений.
Определение raise_on_warnings
также
установит get_warnings
потому что предупреждения должны быть получены, чтобы они могли быть
подняты как исключения.
Вы могли бы всегда хотеть установить режим SQL, если требуется иметь сервер MySQL, непосредственно сообщающий о предупреждениях как об ошибках (см. раздел 10.2.47). Также хорошо использовать транзакционные механизмы, таким образом транзакции могут быть отменены, ловя исключение.
Наборы результатов должны быть получены полностью, прежде чем любое исключение может быть поднято. Следующий пример показывает выполнение запроса, который производит предупреждение:
>>> cnx.raise_on_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() .. mysql.connector.errors.DataError: 1292: Truncated incorrect DOUBLE value: 'a'
Вернет True
или
False
.
Это свойство только для чтения возвращает имя хоста или IP-адрес, используемый для соединения с сервером MySQL.
Возвращает последовательность.
Это свойство только для чтения возвращает порт TCP/IP, используемый для соединения с сервером MySQL.
Возвращает целое число.
Это свойство используется, чтобы получить и установить режимы SQL
для текущей связи. Значение должно быть списком различных режимов, отделенных
запятой (","), или последовательностью режимов, предпочтительно используя
класс constants.SQLMode
.
Чтобы сбросить все режимы, передайте пустую строку или пустую последовательность.
>>> cnx.sql_mode = 'TRADITIONAL,NO_ENGINE_SUBSTITUTION' >>> cnx.sql_mode.split(',') [u'STRICT_TRANS_TABLES', u'STRICT_ALL_TABLES', u'NO_ZERO_IN_DATE', u'NO_ZERO_DATE', u'ERROR_FOR_DIVISION_BY_ZERO', u'TRADITIONAL', u'NO_AUTO_CREATE_USER', u'NO_ENGINE_SUBSTITUTION'] >>> from mysql.connector.constants import SQLMode >>> cnx.sql_mode = [ SQLMode.NO_ZERO_DATE, SQLMode.REAL_AS_FLOAT] >>> cnx.sql_mode u'REAL_AS_FLOAT,NO_ZERO_DATE'
Возвращает последовательность.
Это свойство используется, чтобы установить или узнать переменную сеанса часового пояса для текущей связи.
>>> cnx.time_zone = '+00:00' >>> cursor = cnx.cursor() >>> cursor.execute('SELECT NOW()') ; cursor.fetchone() (datetime.datetime(2012, 6, 15, 11, 24, 36),) >>> cnx.time_zone = '-09:00' >>> cursor.execute('SELECT NOW()') ; cursor.fetchone() (datetime.datetime(2012, 6, 15, 2, 24, 44),) >>> cnx.time_zone u'-09:00'
Возвращает последовательность.
Это свойство только для чтения возвращает файл сокета Unix для соединения с сервером MySQL.
Возвращает последовательность.
Это свойство только для чтения возвращает имя пользователя, используемое для соединения с сервером MySQL.
Возвращает строку.
Этот класс предоставляет экземпляр и управление пулами связи.
Синтаксис:
MySQLConnectionPool(pool_name=None, pool_size=5, pool_reset_session=True, **kwargs)
Конструктор создает объект, который управляет пулом связи.
Параметры:
pool_name
:
Название пула. Если этот аргумент не дан, Connector/Python
автоматически производит имя, составленное из значений
host
, port
,
user
и database
в kwargs
, именно в этом порядке.
Если несколько пулов имеют одинаковое имя, это не ошибка.
Приложение, которое должно отличить пулы по их
pool_name
, должно создать каждый
пул с отличным именем.
pool_size
: Размер пула.
Если этот аргумент не дан, умолчание равняется 5.
pool_reset_session
:
Перезагрузить ли переменные сеанса, когда связь возвращена в пул.
Этот аргумент был добавлен в Connector/Python 1.1.5.
До 1.1.5 переменные сеанса не перезагружаются.
kwargs
: Дополнительные аргументы
соединения, как описано в
разделе 7.1.
Пример:
dbconfig = { "database": "test", "user": "joe", } cnxpool = mysql.connector.pooling.MySQLConnectionPool(pool_name = "mypool", pool_size = 3, **dbconfig)
Синтаксис:
cnxpool.add_connection(cnx = None)
Этот метод добавляет новое или существующее соединение
MySQLConnection
в пул или поднимает исключение
PoolError
, если пул полон.
Параметры:
cnx
:
Объект MySQLConnection
, который будет добавлен к
пулу. Если этот аргумент отсутствует, пул создает новую
связь и добавляет его.
Пример:
cnxpool.add_connection()# add new connection to pool cnxpool.add_connection(cnx) # add existing connection to pool
Синтаксис:
cnxpool.get_connection()
Этот метод возвращает связь из пула или поднимает исключение
PoolError
, если никакие связи недоступны.
Пример:
cnx = cnxpool.get_connection()
Синтаксис:
cnxpool.set_config(**kwargs)
Этот метод устанавливает параметры конфигурации для связей в пуле. Связи, получаемые из пула после использования изменения конфигурации, имеют новые параметры. Связи, полученные перед изменением, остаются незатронутыми, но когда они закрываются (возвращены в пул), будут вновь открыты с новыми параметрами прежде, чем возвращены пулом для последующих запросов связи.
Параметры:
kwargs
: Аргументы соединения.
Пример:
dbconfig = {
"database": "performance_schema",
"user": "admin",
"password": "password
",
}
cnxpool.set_config(**dbconfig)
Синтаксис:
cnxpool.pool_name
Это свойство возвращает название пула связи.
Пример:
name = cnxpool.pool_name
Этот класс используется MySQLConnectionPool
,
чтобы возвратить объединенный экземпляр связи. Это также класс, используемый
для связей, полученных вызовом метода connect()
,
который вызывает пул связи (см.
раздел 9.1).
Объекты связи PooledMySQLConnection
подобны
необъединенным объектам связи MySQLConnection
с этими различиями:
Чтобы освбодить объединенную связь, полученную из пула связи,
вызовите close()
так же, как для любой
необъединенной связи. Однако для объединенной связи
close()
на самом деле не закрывает связь, а
возвращает ее в пул и делает доступной для последующих запросов связи.
Объединенная связь не может повторно формироваться, используя
config()
. Изменения связи должны быть сделаны
через сам объект пула, как описано в
разделе 9.1.
У объединенной связи есть свойство
pool_name
, которое возвращает название пула.
Синтаксис:
PooledMySQLConnection(cnxpool, cnx)
Конструктор конструктор берет пул связи и аргументы соединения и
возвращает объединенную связь. Это используется классом
MySQLConnectionPool
.
Параметры:
cnxpool
: Экземпляр
MySQLConnectionPool
.
cnx
: Экземпляр
MySQLConnection
.
Пример:
pcnx = mysql.connector.pooling.PooledMySQLConnection(cnxpool, cnx)
Синтаксис:
cnx.close()
Возвращает объединенную связь в ее пул связи.
Для объединенной связи close()
на самом деле не закрывает ее, а возвращает ее в пул и делает доступной
для последующих запросов связи.
Если параметры конфигурации пула изменяются, возвращенная связь закрыта и вновь открыта с новой конфигурацией прежде, чем быть возвращенной из пула снова в ответ на запрос связи.
Для объединенных связей config()
поднимает
исключение PoolError
.
Конфигурация для объединенных связей должна быть реализована,
используя объект пула.
Синтаксис:
cnx.pool_name
Это свойство возвращает название пула связи, которому принадлежит связь.
Пример:
cnx = cnxpool.get_connection() name = cnx.pool_name
Класс MySQLCursor
порождает
объекты, которые могут выполнить операции, такие как SQL-операторы.
Объекты курсора взаимодействуют с сервером MySQL, используя объект
MySQLConnection
.
Чтобы создать курсор, используйте метод
cursor()
объекта связи:
import mysql.connector cnx = mysql.connector.connect(database='world') cursor = cnx.cursor()
Несколько связанных классов наследуют
MySQLCursor
.
Чтобы создать курсор одного из этих типов, передайте соответствующие
аргументы cursor()
:
MySQLCursorBuffered
создает буферизированный курсор. Посмотрите
раздел 10.6.1
.
cursor = cnx.cursor(buffered=True)
MySQLCursorRaw
создает сырой курсор. Посмотрите
раздел 10.6.2.
cursor = cnx.cursor(raw=True)
MySQLCursorBufferedRaw
создает буферизированный сырой курсор. Посмотрите
раздел 10.6.3
.
cursor = cnx.cursor(raw=True, buffered=True)
MySQLCursorDict
создает курсор, который возвращает строки как словари. Посмотрите
раздел 10.6.4.
cursor = cnx.cursor(dictionary=True)
MySQLCursorBufferedDict
создает буферизированный курсор, который возвращает строки как словари.
Посмотрите
раздел 10.6.5.
cursor = cnx.cursor(dictionary=True, buffered=True)
MySQLCursorNamedTuple
создает курсор, который возвращает строки как названные кортежами. Посмотрите
раздел 10.6.6
.
cursor = cnx.cursor(named_tuple=True)
MySQLCursorBufferedNamedTuple
создает буферизированный курсор, который возвращает строки как
названные кортежами. Посмотрите
раздел 10.6.7.
cursor = cnx.cursor(named_tuple=True, buffered=True)
MySQLCursorPrepared
создает курсор для выполнения подготовленных запросов. Посмотрите
раздел 10.6.8
.
cursor = cnx.cursor(prepared=True)
В большинстве случаев метод
MySQLConnection
cursor()
используется, чтобы создать объект
MySQLCursor
:
import mysql.connector cnx = mysql.connector.connect(database='world') cursor = cnx.cursor()
Также возможно создать курсор, передавая объект
MySQLConnection
к
MySQLCursor
:
import mysql.connector from mysql.connector.cursor import MySQLCursor cnx = mysql.connector.connect(database='world') cursor = MySQLCursor(cnx)
Аргумент соединения дополнительный. Если опущен, курсор создается, но
метод
execute()
поднимает исключение.
Синтаксис:
result_args = cursor.callproc(proc_name, args=())
Этот метод вызывает хранимую процедуру, указанную параметром
proc_name
. Последовательность параметров
args
должна содержать одну запись для каждого
аргумента, который процедура ожидает.
callproc()
возвращает измененную копию входной
последовательности. Входные параметры оставляют нетронутыми.
Вывод и параметры ввода/вывода могут быть заменены новыми значениями.
Наборы результатов, произведенные хранимой процедурой, автоматически
получены и сохранены как экземпляры
MySQLCursorBuffered. Для получения дополнительной информации об
использовании этих наборов результатов посмотрите
stored_results()
.
Предположим, что хранимая процедура берет два параметра, умножает значения и возвращает результат:
CREATE PROCEDURE multiply(IN pFac1 INT, IN pFac2 INT, OUT pProd INT) BEGIN SET pProd := pFac1 * pFac2; END;
Следующий пример показывает, как выполнить
multiply()
:
>>> args = (5, 6, 0) # 0 is to hold value of the OUT parameter pProd >>> cursor.callproc('multiply', args) ('5', '6', 30L)
Connector/Python 1.2.1 и выше разрешает типам параметра быть
определенными. Чтобы сделать это, определите параметр как кортеж с двумя
пунктами, состоящий из значения параметра и типа. Предположим, что процедура
sp1()
имеет это определение:
CREATE PROCEDURE sp1(IN pStr1 VARCHAR(20), IN pStr2 VARCHAR(20), OUT pConCat VARCHAR(100)) BEGIN SET pConCat := CONCAT(pStr1, pStr2); END;
Чтобы выполнять эту процедуру от Connector/Python, определяя тип для
параметра OUT
:
args = ('ham', 'eggs', (0, 'CHAR')) result_args = cursor.callproc('sp1', args) print(result_args[2])
Синтаксис:
cursor.close()
Этот метод закрывает курсор, перезагружает все результаты и гарантирует, что у объекта курсора нет ссылки на оригинальный объект связи.
Синтаксис:
cursor.execute(operation, params=None, multi=False) iterator = cursor.execute(operation, params=None, multi=True)
Этот метод выполняет данное действие
operation
с базой данных.
Параметры найдены в кортеже или словаре params
и связаны с переменными в операции. Определите использование переменных
в стиле параметров %s
или
%(
(то есть, используя стиль name
)sformat
или
pyformat
).
execute()
возвращает итератор, если
multi
= True
.
В Python кортеж, содержащий единственную значение, должен включать запятую. Например, ('abc') оценено как скаляр, в то время как ('abc',) оценено как кортеж.
Этот пример вставляет информацию о новом сотруднике, затем выбирает данные
для того человека. Запросы выполняются как отдельные действия
execute()
:
insert_stmt = ( "INSERT INTO employees (emp_no, first_name, last_name, hire_date) " "VALUES (%s, %s, %s, %s)" ) data = (2, 'Jane', 'Doe', datetime.date(2012, 3, 23)) cursor.execute(insert_stmt, data) select_stmt = "SELECT * FROM employees WHERE emp_no = %(emp_no)s" cursor.execute(select_stmt, { 'emp_no': 2 })
Значения данных преобразовываются по мере необходимости от объектов Python
до чего-то, что MySQL понимает. В предыдущем примере экземпляр
datetime.date()
преобразовывается в
'2012-03-23'
.
Если multi
=
True
, execute()
в состоянии выполнить многочисленные запросы, определенные в
operation
. Это возвращает итератор, который
позволяет обработать результат каждого запроса. Однако использование
параметров не работает хорошо в этом случае, и обычно хорошая идея выполнить
каждый запрос самостоятельно.
Следующий пример выбирает и вставляет данные в одной операции
execute()
и показывает
результат каждого запроса:
operation = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2' for result in cursor.execute(operation, multi=True): if result.with_rows: print("Rows produced by statement '{}':".format( result.statement)) print(result.fetchall()) else: print("Number of rows affected by statement '{}': {}".format( result.statement, result.rowcount))
Если связь формируется, чтобы получить предупреждения, то все предупреждения, произведенные операцией, доступны через метод MySQLCursor.fetchwarnings().
Синтаксис:
cursor.executemany(operation, seq_of_params)
Этот метод готовит operation
для базы данных
и выполняет его для всех последовательностей параметра или отображений,
найденных в последовательности seq_of_params
.
В Python кортеж, содержащий единственную значение, должен включать запятую. Например, ('abc') оценено как скаляр, в то время как ('abc',) оценено как кортеж.
В большинстве случаев метод executemany()
повторяет последовательность параметров, каждый раз передавая текущие
параметры к методу execute()
.
Оптимизация применяется для вставок: значения данных, данные последовательностями параметра, скомплектованы, используя синтаксис многократной строки. Следующий пример вставляет три записи:
data = [ ('Jane', date(2005, 2, 12)), ('Joe', date(2006, 5, 23)), ('John', date(2010, 10, 3)), ] stmt = "INSERT INTO employees (first_name, hire_date) VALUES (%s, %s)" cursor.executemany(stmt, data)
Для предыдущего примера в MySQL послан такой
INSERT
:
INSERT INTO employees (first_name, hire_date) VALUES ('Jane', '2005-02-12'), ('Joe', '2006-05-23'), ('John', '2010-10-03')
С методом executemany()
невозможно определить многочисленные запросы, чтобы выполнить в параметре
operation
. Выполнение этого поднимает
исключение InternalError
.
Рассмотрите использование execute()
с
multi=True
.
Синтаксис:
rows = cursor.fetchall()
Метод приносит все (или все остающиеся) строки набора результата запроса и возвращает список кортежей. Если больше строк недоступно, это возвращает пустой список.
Следующий пример показывает, как получить первые два строки набора результатов, а затем любые остающиеся строки:
>>> cursor.execute("SELECT * FROM employees ORDER BY emp_no") >>> head_rows = cursor.fetchmany(size=2) >>> remaining_rows = cursor.fetchall()
Необходимо принести все строки для текущего запроса прежде, чем выполнить новые запросы, используя ту же самую связь.
Синтаксис:
rows = cursor.fetchmany(size=1)
Этот метод приносит следующий набор строк результата запроса и возвращает список кортежей. Если больше строк недоступно, это возвращает пустой список.
Количество возвращенных строк может быть определено, используя параметр
size
, который по умолчанию 1. Меньше строк
возвращено, если меньше строк доступно, чем указано.
Необходимо принести все строки для текущего запроса прежде, чем выполнить новые запросы, используя ту же самую связь.
Синтаксис:
row = cursor.fetchone()
Этот метод следующую строку набора результата запроса и возвращает
единственную последовательность или None
,
если больше строк недоступно. По умолчанию возвращенный кортеж состоит из
данных, возвращенных сервером MySQL, преобразованных в объекты Python.
Если курсор сырой, никакое преобразование не происходит, посмотрите
раздел 10.6.2.
Метод fetchone()
используется
fetchall()
и fetchmany()
. Это также используется, когда курсор используется в качестве итератора.
Следующий пример показывает два эквивалентных способа обработать результат
запроса. Первое использование fetchone()
в цикле
while
, второе использование
курсора как итератора:
# Using a while loop cursor.execute("SELECT * FROM employees") row = cursor.fetchone() while row is not None: print(row) row = cursor.fetchone() # Using the cursor as iterator cursor.execute("SELECT * FROM employees") for row in cursor: print(row)
Необходимо принести все строки для текущего запроса прежде, чем выполнить новые запросы, используя ту же самую связь.
Синтаксис:
tuples = cursor.fetchwarnings()
Этот метод возвращает список кортежей, содержащих предупреждения,
произведенные ранее выполненной операцией. Чтобы установить, получать ли
предупреждения, используйте свойство соединения
get_warnings
.
Следующий пример показывает
SELECT
, который производит предупреждение:
>>> cnx.get_warnings = True >>> cursor.execute("SELECT 'a'+1") >>> cursor.fetchall() [(1.0,)] >>> cursor.fetchwarnings() [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")]
Когда предупреждения произведены, возможно поднять ошибки вместо этого,
используя свойство соединения
raise_on_warnings
.
Синтаксис:
iterator = cursor.stored_results()
Этот метод возвращает список итераторов, который может использоваться, чтобы обработать наборы результатов, произведенные хранимой процедурой, выполненной, используя метод callproc(). Наборы результатов остаются доступными, пока вы не используете курсор, чтобы выполнить другую операцию или вызвать другую хранимую процедуру.
Следующий пример выполняет хранимую процедуру, которая производит два
набора результатов, затем использует
stored_results()
, чтобы получить их:
>>> cursor.callproc('myproc') () >>> for result in cursor.stored_results(): ... print result.fetchall() ... [(1,)] [(2,)]
Синтаксис:
sequence = cursor.column_names
Это свойство только для чтения возвращает имена столбцов набора результатов как последовательность строк Unicode.
Следующий пример показывает, как создать словарь из кортежа, содержащего
данные с использованием ключей column_names
:
cursor.execute("SELECT last_name, first_name, hire_date " "FROM employees WHERE emp_no = %s", (123,)) row = dict(zip(cursor.column_names, cursor.fetchone())) print("{last_name}, {first_name}: {hire_date}".format(row))
Альтернативно, с Connector/Python 2.0.0 можно принести строки как словари непосредственно, посмотрите раздел 10.6.4.
Синтаксис:
tuples = cursor.description
Это свойство только для чтения возвращает список кортежей, описывающих колонки в наборе результатов. Каждый кортеж в списке содержит значения следующим образом:
(column_name, type, None, None, None, None, null_ok, column_flags)
Следующий пример показывает, как интерпретировать кортежи
description
:
import mysql.connector from mysql.connector import FieldType ... cursor.execute("SELECT emp_no, last_name, hire_date " "FROM employees WHERE emp_no = %s", (123,)) for i in range(len(cursor.description)): print("Column {}:".format(i+1)) desc = cursor.description[i] print("column_name = {}".format(desc[0])) print("type = {} ({})".format(desc[1], FieldType.get_info(desc[1]))) print("null_ok = {}".format(desc[6])) print("column_flags = {}".format(desc[7]))
Вывод похож на это:
Column 1: column_name = emp_no type = 3 (LONG) null_ok = 0 column_flags = 20483 Column 2: column_name = last_name type = 253 (VAR_STRING) null_ok = 0 column_flags = 4097 Column 3: column_name = hire_date type = 10 (DATE) null_ok = 0 column_flags = 4225
column_flags
это экземпляр класса
constants.FieldFlag
.
Чтобы видеть, как интерпретировать его, сделайте это:
>>> from mysql.connector import FieldFlag >>> FieldFlag.desc
Синтаксис:
id = cursor.lastrowid
Это свойство только для чтения возвращает значение, произведенное для
столбца AUTO_INCREMENT
последним
INSERT
или
UPDATE
, или
None
, когда нет такого доступного значения.
Например, если вы скомандуете
INSERT
на таблице, которая содержит
столбец AUTO_INCREMENT
,
lastrowid
вернет значение
AUTO_INCREMENT
для новой строки.
Для примера посмотрите
раздел 5.3
.
Свойство lastrowid
похоже на функцию C API
mysql_insert_id()
, см.
mysql_insert_id().
Синтаксис:
count = cursor.rowcount
Это свойство только для чтения возвращает количество строк, возвращенных
для SELECT
или количество строк,
затронутых запросами DML, например,
INSERT
или
UPDATE
. Для примера посмотрите
раздел 10.5.4
.
Для небуферизированных курсоров не может быть известно количество строк прежде, чем строки были принесены. В этом случае количество строк -1 немедленно после выполнения запроса и увеличено, по мере получения строк.
Свойство rowcount
аналогично функции C API
mysql_affected_rows()
, см.
mysql_affected_rows().
Синтаксис:
str = cursor.statement
Это свойство только для чтения возвращает последний выполненный запрос
как последовательность. Свойство statement
может быть полезно для отладки и показа, что послали в сервер MySQL.
Последовательность может содержать многочисленные запросы, если
последовательность многократных запросов была выполнена. Это происходит для
execute()
с
multi=True
. В этом случае свойство
statement
содержит всю последовательность
запросов и вызов execute()
вернет итератор,
который может использоваться, чтобы обработать следствия отдельных запросов.
Свойство statement
для этого итератора
показывает последовательности запроса для отдельных запросов.
Синтаксис:
boolean = cursor.with_rows
Это свойство только для чтения вернет True
или False
, чтобы указать, произвела ли последний
раз выполненная операция строки.
Свойство with_rows
полезно, когда необходимо
определить, производит ли запрос набор результатов и получить строки.
Следующий пример получает строки, возвращенные
SELECT
, но
только затронутые строки оцениваются для
UPDATE
:
import mysql.connector cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() operation = 'SELECT 1; UPDATE t1 SET c1 = 2; SELECT 2' for result in cursor.execute(operation, multi=True): if result.with_rows: result.fetchall() else: print("Number of affected rows: {}".format(result.rowcount))
Классы курсора, описанные в следующих разделах, наследуют от класса
MySQLCursor
, который описан в
разделе 10.5.
Класс MySQLCursorBuffered
наследует от
MySQLCursor
.
После выполнения запроса курсор
MySQLCursorBuffered
получает весь набор
результатов от сервера и буферизует строки.
Для запросов, выполненных, используя буферизированный курсор, получающие
строки методы, такие как
fetchone()
, вернут
строки из набора буферизированных строк. Для небуферизированных курсоров
строки не получены от сервера, пока метод, получающий строки, не вызывают.
В этом случае, несомненно, необходимо будет получить все строки набора
результатов прежде, чем выполнить любые другие запросы на той же самой связи,
или будет поднято исключение InternalError
(Unread result found).
MySQLCursorBuffered
может быть полезным в
ситуациях, где многократные запросы с небольшими наборами результатов должны
быть объединены или вычислены друг с другом.
Чтобы создать буферизированный курсор, используйте аргумент
buffered
, вызывая метод связи
cursor()
.
Альтернативно, чтобы сделать все курсоры, созданные из связи, буферизованными
по умолчанию, используйте
параметр связи buffered
.
Пример:
import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will buffer results cursor = cnx.cursor(buffered=True) # All cursors created from cnx2 will be buffered by default cnx2 = mysql.connector.connect(buffered=True)
Для случая практического применения посмотрите раздел 6.1.
Класс MySQLCursorRaw
унаследован от
MySQLCursor
.
Курсор MySQLCursorRaw
пропускает преобразование от типов данных MySQL до типов Python,
когда получает строки. Сырой курсор обычно используется, чтобы получить
лучшую производительность или когда вы хотите сделать преобразование сами.
Чтобы создать сырой курсор, используйте параметр
raw
, вызывая метод связи
cursor()
. Альтернативно, чтобы сделать все
курсоры, созданные из связи, сырыми по умолчанию, используйте
параметр связи
raw
.
Пример:
import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will be raw cursor = cnx.cursor(raw=True) # All cursors created from cnx2 will be raw by default cnx2 = mysql.connector.connect(raw=True)
Класс MySQLCursorBufferedRaw
унаследован от
MySQLCursor
.
Курсор MySQLCursorBufferedRaw
похож на
MySQLCursorRaw
, но буферизован: после
выполнения запроса это получает весь набор результатов от сервера и
буферизует строки. Для получения информации о последствиях буферизования
посмотрите
раздел 10.6.1.
Чтобы создать буферизированный сырой курсор, используйте метод
raw
и параметр
buffered
, когда вызываете метод соединения
cursor()
.
Альтернативно, чтобы сделать все курсоры созданными сырыми
и буферизованными по умолчанию, используйте
параметры соединения
raw
и buffered
.
Пример:
import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will be raw and buffered cursor = cnx.cursor(raw=True, buffered=True) # All cursors created from cnx2 will be raw and buffered by default cnx2 = mysql.connector.connect(raw=True, buffered=True)
Класс MySQLCursorDict
унаследован от
MySQLCursor
.
Этот класс доступен с Connector/Python 2.0.0.
Курсор MySQLCursorDict
возвращает каждую строку как словарь. Ключи для каждого объекта словаря это
имена столбцов результата MySQL.
Пример:
cnx = mysql.connector.connect(database='world') cursor = cnx.cursor(dictionary=True) cursor.execute("SELECT * FROM country WHERE Continent = 'Europe'") print("Countries in Europe:") for row in cursor: print("* {Name}".format(Name=row['Name']
Предыдущий код производит такой вывод:
Countries in Europe: * Albania * Andorra * Austria * Belgium * Bulgaria ...
Может быть удобно передать словарь в
format()
:
cursor.execute("SELECT Name, Population FROM country WHERE Continent = 'Europe'") print("Countries in Europe with population:") for row in cursor: print("* {Name}: {Population}".format(**row))
Класс MySQLCursorBufferedDict
унаследован от
MySQLCursor
.
Этот класс доступен с Connector/Python 2.0.0.
Курсор MySQLCursorBufferedDict
аналогичен
MySQLCursorDict
, но буферизован: после
выполнения запроса это получает весь набор результатов от сервера и
буферизует строки. Для получения информации о последствиях буферизования
посмотрите
раздел 10.6.1.
Чтобы получить буферизированный курсор, который возвращает словари,
добавьте параметр buffered
, создлавая
новый курсор словаря:
cursor = cnx.cursor(dictionary=True, buffered=True)
Класс MySQLCursorNamedTuple
унаследован от
MySQLCursor
.
Этот класс доступен с Connector/Python 2.0.0.
Курсор MySQLCursorNamedTuple
возвращает каждую строку как названный кортеж. Признаки для каждого объекта
названного кортежа это имена столбцов результата MySQL.
Пример:
cnx = mysql.connector.connect(database='world') cursor = cnx.cursor(named_tuple=True) cursor.execute("SELECT * FROM country WHERE Continent = 'Europe'") print("Countries in Europe with population:") for row in cursor: print("* {Name}: {Population}".format(Name=row.Name, Population=row.Population))
Класс MySQLCursorBufferedNamedTuple
унаследован от
MySQLCursor
.
Этот класс доступен с Connector/Python 2.0.0.
Курсор MySQLCursorBufferedNamedTuple
аналогичен
MySQLCursorNamedTuple
, но буферизован: после
выполнения запроса это получает весь набор результатов от сервера и
буферизует строки. Для получения информации о последствиях буферизования
посмотрите
раздел 10.6.1.
Чтобы получить буферизированный курсор, который возвращает названные
кортежи, добавьте параметр buffered
при создании
нового курсора названного кортежа:
cursor = cnx.cursor(named_tuple=True, buffered=True)
Класс MySQLCursorPrepared
унаследован от
MySQLCursor
.
Этот класс доступен с Connector/Python 1.1.0. Расширение C поддерживает его с Connector/Python 8.0.17.
В MySQL есть два способа выполнить подготовленный запрос:
Используйте двоичный протокол клиент-сервер, чтобы послать и получить
данные. Чтобы неоднократно выполнить тот же самый запрос с различными данными
для различного выполнения, это более эффективно, чем использование
PREPARE
и
EXECUTE
.
Для получения информации о протоколе двоичной синхронной передачи данных см.
C API Prepared Statements.
В Connector/Python есть два способа создать курсор, который позволяет
выполнение подготовленных запросов, используя протокол двоичной синхронной
передачи данных. В обоих случаях метод cursor()
объекта связи возвращает объект
MySQLCursorPrepared
:
Более простой синтаксис использует параметр
prepared=True
метода
cursor()
.
Этот синтаксис доступен с Connector/Python 1.1.2.
import mysql.connector cnx = mysql.connector.connect(database='employees') cursor = cnx.cursor(prepared=True)
Альтернативно, создайте экземпляр класса
MySQLCursorPrepared
, используя аргумент
cursor_class
метода
cursor()
.
Этот синтаксис доступен с Connector/Python 1.1.0.
import mysql.connector from mysql.connector.cursor import MySQLCursorPrepared cnx = mysql.connector.connect(database='employees') cursor = cnx.cursor(cursor_class=MySQLCursorPrepared)
Курсор, порожденный от класса
MySQLCursorPrepared
, работает так:
В первый раз вы передаете запрос методу
execute()
курсора, это готовит запрос.
Для последующих вызовов execute()
фаза подготовки пропускается, если запрос тот же самый
Метод execute()
берет дополнительный
второй аргумент, содержащий список значений данных, чтобы связать с маркерами
параметра в запросе. Если аргумент списка присутствует, должно быть одно
значение на маркер параметра.
Пример:
cursor = cnx.cursor(prepared=True) stmt = "SELECT fullname FROM employees WHERE id = %s" # (1) cursor.execute(stmt, (5,))# (2) # ... fetch data ... cursor.execute(stmt, (10,)) # (3) # ... fetch data ...
%s
в рамках запроса это
маркер параметра. Не помещайте отметки цитаты вокруг маркеров параметра.
Для первого вызова execute()
курсор готовит запрос. Если данные даны в том же самом вызове, они также
выполняют запрос и необходимо получить данные.
Для последующего вызова execute()
,
который передает тот же самый SQL-оператор, курсор пропускает фазу подготовки.
Подготовленные запросы, выполненные с
MySQLCursorPrepared
, могут использовать стиль
параметров format
(%s
) или
qmark
(?
).
Это отличается от неподготовленных запросов, выполненных с
MySQLCursor
, которые могут использовать стиль
параметров format
или
pyformat
.
Чтобы использовать многочисленные подготовленные запросы одновременно,
создайте многократные курсоры от класса
MySQLCursorPrepared
.
У протокола MySQL клиент-сервер есть опция послать подготовленные
параметры операторов через команду
COM_STMT_SEND_LONG_DATA
.
Чтобы использовать это из скрипта Connector/Python,
пошлите параметр в запросе, используя интерфейс
IOBase
. Пример:
from io import IOBase ... cur = cnx.cursor(prepared=True) cur.execute("SELECT (%s)", (io.BytesIO(bytes("A", "latin1")), ))
Этот класс предоставляет определение констант флагов клиента MySQL,
которые могут использоваться, когда связь устанавливается, чтобы формировать
сессию. Класс ClientFlag
доступен, импортируя
mysql.connector
.
>>> import mysql.connector >>> mysql.connector.ClientFlag.FOUND_ROWS 2
См.
раздел 10.2.32 и
параметры соединения client_flag
.
ClientFlag
не может создавать экземпляры.
Этот класс обеспечивает все поддержанные поля MySQL или типы данных. Они могут быть полезными, имея дело с необработанными данными или определяя ваши собственные конвертеры. Тип поля хзранится с курсором в описании для каждого столбца.
Следующий пример показывает, как напечатать название типа данных для каждого столбца в наборе результатов.
from __future__ import print_function import mysql.connector from mysql.connector import FieldType cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() cursor.execute("SELECT DATE(NOW()) AS `c1`, TIME(NOW()) AS `c2`, " "NOW() AS `c3`, 'a string' AS `c4`, 42 AS `c5`") rows = cursor.fetchall() for desc in cursor.description: colname = desc[0] coltype = desc[1] print("Column {} has type {}".format(colname, FieldType.get_info(coltype))) cursor.close() cnx.close()
FieldType
не может создавать экземпляры.
Этот класс предоставляет все известные
режимы SQL. Это главным образом используется, устанавливая
режимы SQL во время связи, используя свойство связи
sql_mode
, см.
раздел
10.2.47.
Класс SQLMode
не может создавать экземпляры.
Этот класс обеспечивает все известные наборы символов MySQL и их сопоставления по умолчанию. Для примеров посмотрите раздел 10.2.31.
Класс CharacterSet
не может создавать экземпляры.
Этот класс выполняет различные операции по сбросу.
RefreshOption.GRANT
Освежить таблицы привилегий, аналогично
FLUSH PRIVILEGES
.
RefreshOption.LOG
Сбросить журналы как
FLUSH LOGS
.
RefreshOption.TABLES
Сбросить кэш таблиц как
FLUSH TABLES
.
RefreshOption.HOSTS
Сбросить кэш хоста как
FLUSH HOSTS
.
RefreshOption.STATUS
Сбросить переменные статуса аналогично
FLUSH STATUS
.
RefreshOption.THREADS
Сбросить кэш потоков.
RefreshOption.SLAVE
На подчиненном сервере репликации сбросить информацию о главном сервере и
перезапустить подчиненного аналогично
RESET SLAVE
.
Модуль mysql.connector.errors
определяет
классы исключений для ошибок и предупреждений, поднятых MySQL
Connector/Python. Большинство классов, определенных в этом модуле, доступно,
когда вы импортируете mysql.connector
.
Классы исключений, определенные в этом модуле главным образом, следуют спецификации Python Database API Specification v2.0 (PEP 249). Для некоторых клиентов MySQL или ошибок сервера не всегда ясно, которое исключение поднять.
Ошибки MySQL Server отображены на исключения Python на основе их
значения SQLSTATE (см.
Server Error Message Reference).
Следующая таблица показывает классы SQLSTATE и исключения
поднимаемые Connector/Python. Однако, возможно пересмотреть, какое исключение
поднято для каждой ошибки сервера. Исключение по умолчанию
DatabaseError
.
Таблица 10.1. Отображение ошибок сервера к исключениям Python
Класс SQLSTATE | Исключение Connector/Python |
---|---|
02 |
DataError |
02 |
DataError |
07 |
DatabaseError |
08 |
OperationalError |
0A |
NotSupportedError |
21 |
DataError |
22 |
DataError |
23 |
IntegrityError |
24 |
ProgrammingError |
25 |
ProgrammingError |
26 |
ProgrammingError |
27 |
ProgrammingError |
28 |
ProgrammingError |
2A |
ProgrammingError |
2B |
DatabaseError |
2C |
ProgrammingError |
2D |
DatabaseError |
2E |
DatabaseError |
33 |
DatabaseError |
34 |
ProgrammingError |
35 |
ProgrammingError |
37 |
ProgrammingError |
3C |
ProgrammingError |
3D |
ProgrammingError |
3F |
ProgrammingError |
40 |
InternalError |
42 |
ProgrammingError |
44 |
InternalError |
HZ |
OperationalError |
XA |
IntegrityError |
0K |
OperationalError |
HY |
DatabaseError |
Этот модуль содержит коды ошибок клиента и сервера MySQL, определенные как атрибуты модуля с кодом ошибки как значение. Используя коды ошибок вместо номеров ошибок можно сделать чтение исходного кода немного легче.
>>> from mysql.connector import errorcode >>> errorcode.ER_BAD_TABLE_ERROR 1051
Для получения дополнительной информации об ошибках MySQL посмотрите Errors, Error Codes, and Common Problems.
Это исключение базовый класс для всех других исключений в модуле
errors
. Это может использоваться, чтобы
зафиксировать все ошибки в одном запросе except
.
Следующий пример показывает, как мы могли поймать синтаксические ошибки:
import mysql.connector try: cnx = mysql.connector.connect(user='scott', database='employees') cursor = cnx.cursor() cursor.execute("SELECT * FORM employees") # Syntax error in query cnx.close() except mysql.connector.Error as err: print("Something went wrong: {}".format(err))
Инициализация исключения поддерживает несколько дополнительных аргументов,
а именно msg
,
errno
, values
и sqlstate
. Все они дополнительные и по
умолчанию None
.
errors.Error
внутренне используется
Connector/Python, чтобы поднять ошибки клиент-сервера MySQL и не должен
использоваться вашим приложением, чтобы поднять исключения.
Следующие примеры показывают результат, не используя аргументов или комбинации аргументов:
>>> from mysql.connector.errors import Error >>> str(Error()) 'Unknown error' >>> str(Error("Oops! There was an error.")) 'Oops! There was an error.' >>> str(Error(errno=2006)) '2006: MySQL server has gone away' >>> str(Error(errno=2002, values=('/tmp/mysql.sock', 2))) "2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)" >>> str(Error(errno=1146, sqlstate='42S02', msg="Table 'test.spam' doesn't exist")) "1146 (42S02): Table 'test.spam' doesn't exist"
Пример, который использует код ошибки 1146, используется, когда
Connector/Python получает ошибочный пакет от сервера MySQL.
Информация разобрана и передана к исключению
Error
.
Каждый подкласс исключения от Error
может быть инициализирован, используя ранее упомянутые аргументы.
Кроме того, у каждого экземпляра есть атрибуты
errno
, msg
и
sqlstate
, которые могут
использоваться в вашем коде.
Следующий пример показывает, как обработать ошибки, когда удаляемая
таблица не существует (когда
DROP TABLE
не включает
IF EXISTS
):
import mysql.connector from mysql.connector import errorcode cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() try: cursor.execute("DROP TABLE spam") except mysql.connector.Error as err: if err.errno == errorcode.ER_BAD_TABLE_ERROR: print("Creating table spam") else: raise
До Connector/Python 1.1.1 исходное сообщение, переданное
errors.Error()
,
не сохранено так, чтобы это могло быть прочитано. Вместо этого атрибут
Error.msg
был отформатирован со значением
SQLSTATE и кодом ошибки. С 1.1.1 только исходное сообщение сохраняется в
атрибуте Error.msg
.
Отформатированное значение вместе с кодом ошибки и значением SQLSTATE может
быть получено, печатая или получая строковое представление
ошибочного объекта. Пример:
try: conn = mysql.connector.connect(database = "baddb") except mysql.connector.Error as e: print "Error code:", e.errno# error number print "SQLSTATE value:", e.sqlstate # SQLSTATE value print "Error message:", e.msg # error message print "Error:", e # errno, sqlstate, msg values s = str(e) print "Error:", s # errno, sqlstate, msg values
errors.Error
это подкласс Python
StandardError
.
Это исключение поднято, когда были проблемы с данными.
Примеры: установка столбца в NULL
, когда
это не может быть NULL
, выход значения
из диапазона для столбца, деление на нуль, количество столбцов не
соответствует количеству значений и т.д.
errors.DataError
это подкласс
errors.DatabaseError
.
Это исключение является умолчанием для любой ошибки MySQL, которая не соответствует другим исключениям.
errors.DatabaseError
это подкласс
errors.Error
.
Это исключение поднято, когда относительная целостность данных затронута. Например, двойной ключ был вставлен или ограничение внешнего ключа неудачно.
Следующий пример показывает, что ошибка дублирования ключа подняла IntegrityError:
cursor.execute("CREATE TABLE t1 (id int, PRIMARY KEY (id))") try: cursor.execute("INSERT INTO t1 (id) VALUES (1)") cursor.execute("INSERT INTO t1 (id) VALUES (1)") except mysql.connector.IntegrityError as err: print("Error: {}".format(err))
errors.IntegrityError
это подкласс
errors.DatabaseError
.
Это исключение поднято для ошибок, происходящих из самого Connector/Python, не связанных с сервером MySQL.
errors.InterfaceError
это подкласс
errors.Error
.
Это исключение поднято, когда сервер MySQL сталкивается с внутренней ошибкой, например, когда мертвая блокировка произошла.
errors.InternalError
это подкласс
errors.DatabaseError
.
Это исключение поднято, когда была использована некоторая функция, которая не поддерживается версией MySQL, которая возвратила ошибку. Это также поднято, используя функции или запросы, которые не поддерживаются сохраненными подпрограммами.
errors.NotSupportedError
это подкласс
errors.DatabaseError
.
Это исключение поднято для ошибок, которые связаны с действиями MySQL. Например: слишком много связей, имя хоста не могло быть найдено, плохое рукопожатие, сервер закрывается, ошибки связи.
errors.OperationalError
это подкласс
errors.DatabaseError
.
Это исключение поднято для ошибок пула связи.
errors.PoolError
это подкласс
errors.Error
.
Это исключение поднято на программных ошибках, например когда у вас есть синтаксическая ошибка в SQL или таблица не была найдена.
Следующий пример показывает, как обращаться с синтаксическими ошибками:
try: cursor.execute("CREATE DESK t1 (id int, PRIMARY KEY (id))") except mysql.connector.ProgrammingError as err: if err.errno == errorcode.ER_SYNTAX_ERROR: print("Check your syntax!") else: print("Error: {}".format(err))
errors.ProgrammingError
это подкласс
errors.DatabaseError
.
Это исключение используется для сообщения о важных предупреждениях, однако, Connector/Python не использует его. Это включено, чтобы быть совместимым с Python Database Specification v2.0 (PEP-249).
Рассмотрите использование более строгого режима SQL или параметра соединения raise_on_warnings, чтобы заставить Connector/Python поднять ошибки, когда ваши запросы произведут предупреждения.
errors.Warning
это подкласс Python
StandardError
.
Синтаксис:
errors.custom_error_exception(error=None, exception=None)
Этот метод определяет исключения для ошибок сервера MySQL и возвращает текущие настройки.
Если error
это номер ошибки MySQL Server,
необходимо также передать класс exception
.
Аргумент error
может быть словарем, в этом
случае ключ это код ошибки сервера, а значение это класс исключения,
которое будет поднято.
Чтобы перезагрузить настройки, задайте пустой словарь.
import mysql.connector from mysql.connector import errorcode # Server error 1028 should raise a DatabaseError mysql.connector.custom_error_exception(1028, mysql.connector.DatabaseError) # Or using a dictionary: mysql.connector.custom_error_exception({ 1028: mysql.connector.DatabaseError, 1029: mysql.connector.OperationalError, }) # To reset, pass an empty dictionary: mysql.connector.custom_error_exception({})