Сообщить об ошибке.

Функция connect() модуля MySQLdb в Python.

Создание подключения к базе данных MySQL.

Синтаксис:

import MySQLdb

connect = MySQLdb.connect(*args, **kwargs)

Принимаемые аргументы:

  • host - имя хоста для подключения. По умолчанию используется локальный хост через сокет UNIX.
  • user - пользователь для аутентификации в БД. По умолчанию: текущий действующий пользователь.
  • passwd - пароль для аутентификации в БД. По умолчанию: None.
  • db - база данных для использования. По умолчанию: None.
  • port - TCP-порт сервера MySQL. По умолчанию: 3306.
  • unix_socket - расположение сокета UNIX. По умолчанию: используйте местоположение по умолчанию или TCP для удаленных хостов.
  • conv - словарь преобразования типов. По умолчанию: MySQLdb.converters.conversions.
  • compress - включает сжатие протокола. По умолчанию: без сжатия
  • connect_timeout - разрывает соединение, если подключение не будет завершено в течение заданного количества секунд. По умолчанию: тайм-аут отсутствует.
  • autocommit - если True, то автоматически применяет изменения к базе данных, смотрите Connection.commit().
  • named_pipe - именованный канал (Windows). По умолчанию: None.
  • init_command - начальная команда для отправки серверу при подключении. По умолчанию: None.
  • read_default_file - файл конфигурации MySQL для чтения. Подробнее в документацию API C MySQL для функции mysql_options().
  • read_default_group - группа по умолчанию для чтения. Подробнее в документацию API C MySQL для функции mysql_options().
  • cursorclass - (ключевой аргумент) класс курсора, который использует connect.cursor(). По умолчанию: cursors.Cursor (результат запроса в виде списка кортежей). Может принимать cursors.DictCursor (результат запроса в виде словаря, значения ключей - названия столбцов таблицы).
  • use_unicode - (ключевой аргумент) если значение True, то столбцы CHAR и VARCHAR и TEXT возвращаются как строки в Юникоде с использованием настроенного набора символов. Лучше всего установить кодировку по умолчанию в конфигурации сервера или конфигурации клиента (считывается с помощью read_default_file). Если изменить набор символов после подключения (MySQL-4.1 и более поздние версии), то нужно будет ввести правильное имя набора символов в connection.charset. Если значение False, то текстовые столбцы возвращаются как обычные строки, при этом всегда можно записать строки в Юникоде.
  • charset - (ключевой аргумент) если присутствует, то набор символов соединения будет изменен на этот набор символов. Для поддержки изменения набора символов требуется сервер MySQL версии 4.1 и более поздних версий; если сервер слишком старый, то будет выдана ошибка. UnsupportedError. Этот параметр подразумевает use_unicode=True, но можно переопределить его с помощью use_unicode=False, хотя, вероятно, этого делать не следует. Если charset=None, то используется набор символов по умолчанию.
  • sql_mode - (ключевой аргумент) если присутствует, то режим сеанса SQL будет установлен на заданную строку. Дополнительные сведения о sql_mode смотрите в документации по MySQL. Доступно только для серверов версии 4.1 и новее. По умолчанию: None.
  • apilevel - (ключевой аргумент) строковая константа, указывающая поддерживаемый уровень API БД. По умолчанию: '2.0'.
  • threadsafety - (ключевой аргумент) целочисленная константа, указывающая уровень потокобезопасности, поддерживаемый интерфейсом. По умолчанию установлено значение threadsafety=1, что означает: потоки могут совместно использовать этот модуль.

    Протокол MySQL не может одновременно обрабатывать несколько потоков, использующих одно и то же соединение. Некоторые более ранние версии MySQLdb использовали блокировку для достижения потокобезопасности (threadsafety=2). Хотя это не очень сложно выполнить с помощью стандартного класса Cursor (который использует mysql_store_result()), это усложняется SSCursor (который использует mysql_use_result(); с последним, необходимо убедиться, что все строки были прочитаны, прежде чем делать другой запрос. Это еще более усложняется добавлением транзакций, поскольку транзакции начинаются, когда курсор выполняет запрос, но заканчиваются, когда объект Connection выполняет COMMIT или ROLLBACK. Потоки просто не могут совместно использовать соединение во время выполнения транзакции, а также не могут совместно использовать его во время выполнения запроса.Это чрезмерно усложняло код до такой степени, что оно того не стоило.

    Общий вывод: не разделяйте соединения между потоками. Это действительно не стоит ни ваших усилий, и, в конце концов, вероятно, снизит производительность, поскольку сервер MySQL запускает отдельный поток для каждого соединения. Безусловно, можно делать кэширование соединений в пуле, и передавать эти соединения одному потоку за раз. ПРЕДУПРЕЖДЕНИЕ! Если разрешить двум потокам одновременно использовать одно соединение, то модуль MySQLdb, вероятно просто умрет.

  • charset - (ключевой аргумент) набор символов, используемый соединением. В MySQL-4.1 и новее можно в настройках подключаемой базы данных (но не рекомендуется) изменить набор символов соединения с помощью оператора SQL, при этом необходимо также изменить этот аргумент. В противном случае будут выдаваться ошибки кодирования.

  • paramstyle - (ключевой аргумент) Строковая константа, указывающая тип форматирования параметра, ожидаемый интерфейсом. По умолчанию 'format', это коды формата ANSI C printf, например '...WHERE name=%s'. Если установлено 'pyformat' то для connect.execute() используются коды расширенного формата Python, например '...WHERE name=%(name)s'. В настоящее время API не позволяет указывать более одного стиля в paramstyle.

    Обратите внимание, что любые буквальные знаки процента % в строке запроса, передаваемой в connect.execute(), то должны быть экранированы этим же знаком, т.е. %%.

    Заполнители параметров можно использовать только для вставки значений столбца. Их нельзя использовать для других частей SQL, таких как имена таблиц, операторы и т. д.

  • conv - (ключевой аргумент) словарь или сопоставление, управляющее преобразованием типов из MySQL в Python и наоборот.

    Если ключ имеет тип MySQL (из FIELD_TYPE.*), то значение может быть:

    • вызываемый объект, который принимает строковый аргумент (значение MySQL), возвращая значение Python
    • последовательность двойных кортежей, где первое значение представляет собой комбинацию флагов из MySQLdb.constants.FLAG, а второе значение представляет собой функцию, как указано выше. Последовательность проверяется до тех пор, пока флаги в поле не совпадут с флагами первого значения. Если оба значения равны None, выполняется преобразование по умолчанию. В настоящее время это используется только для различения столбцов TEXT и BLOB.

    Если ключ представляет собой тип или класс Python, то значение представляет собой вызываемый объект Python (обычно функцию), принимающий два аргумента (значение для преобразования и словарь преобразования), который преобразует значения этого типа в строковое значение SQL-литерала.

    Для большинства типов инициализируется разумными значениями по умолчанию. При создании объекта Connection можно передать свой собственный словарь преобразователя типов в качестве ключевого аргумента. В противном случае используется копия MySQLdb.converters.conversions. Некоторые нестандартные типы возвращаются в виде строк, и именно так MySQL возвращает все столбцы.

Возвращаемое значение:

Описание:

Функция connect() модуля MySQLdb создает подключение к базе данных MySQL. Возвращает объект соединения Connection.

Функция MySQLdb.connect() принимает аргументы такие же, как и API MySQL для языка С. Кроме того, есть несколько дополнительных ключевых аргументов, которые соответствуют параметрам функции MySQL C API mysql_options(), которая вызывается перед подключением. Обратите внимание, что некоторые аргументы должны быть указаны как ключевые! Значение по умолчанию для каждого параметра равно NULL или нулю, в зависимости от ситуации. Обратитесь к документации API MySQL для языка С для более подробной информации.

Методы и свойства объекта Connection.

Объекты соединения возвращаются функцией MySQLdb.connect().

Есть много других методов, определенных для объекта Connection, которые специфичны только для MySQL. Для получения дополнительной информации смотрите раздел "Реализация интерфейса MySQL C API в модуле MySQLdb" или обратитесь к внутренней документации, используя pydoc.

Connection.close():

Метод Connection.close() немедленно закрывает соединение (а не всякий раз, когда вызывается Connection.__del__()).

С этого момента соединение будет непригодным для использования. При попытке использования закрытого соединения будет вызвано исключение MySQLdb.Error (или подкласс). То же самое относится ко всем объектам курсора Connection.cursor(), пытающимся использовать соединение.

Обратите внимание, что закрытие соединения без предварительной фиксации изменений Connection.commit() вызовет неявный откат Connection.rollback().

Connection.commit():

Метод Connection.commit() зафиксирует любую ожидающую транзакцию в базе данных.

Обратите внимание, что если база данных поддерживает функцию автоматической фиксации, то она должна быть изначально отключена. В противном случае этот метод ничего не делает.

Connection.rollback():

Метод Connection.rollback() выполняется откат (отмена) текущей транзакции, если версия MySQL поддерживает транзакции. В противном случае возникает ошибка NotSupportedError.

Закрытие соединения без предварительной фиксации изменений вызовет неявный откат.

Connection.cursor([cursorclass]):

Метод Connection.cursor() возвращает новый объект Cursor, используя соединение.

БД MySQL не поддерживает курсоры, однако курсоры легко эмулируются. Можно указать альтернативный класс курсора в качестве необязательного параметра cursorclass. Если cursorclass не передан, то по умолчанию используется значение, указанное при создании объекта подключения, или стандартный класс cursors.Cursor (результат запроса будет возвращаться в виде списка кортежей). Может принимать встроенный класс cursors.DictCursor (результат запроса будет возвращаться в виде словаря, значения ключей - названия столбцов таблицы).

Пример создания соединения с MySQL.

from MySQLdb import connect, cursors

# конфигурация соединения с базой данных
MYSQLCONF = {
    'host': 'localhost', # хост базы данных
    'user': 'user', # имя пользователя базы данных
    'password': 'password', # пароль пользователя базы данных
    'db': 'test_db', # имя базы данных
    'charset': 'utf8', # используемая кодировка базы данных
    'autocommit': True, # автоматический cursor.commit()
    # извлекаемые строки из БД принимают вид словаря
    'cursorclass': cursors.DictCursor
}

# поднимаем соединение с базой данных
db = connect(**MYSQLCONF)
...