Конфигурация двигателя

Engine является отправной точкой для любого приложения SQLAlchemy. Это «домашняя база» для реальной базы данных и ее DBAPI, доставляемой приложению SQLAlchemy через пул соединений и Dialect, который описывает, как общаться с определенным видом базы данных/комбинацией DBAPI.

Общая структура может быть проиллюстрирована следующим образом:

../../_images/sqla_engine_arch.png

Там, где указано выше, Engine ссылается на Dialect и Pool, которые вместе интерпретируют функции модуля DBAPI, а также поведение базы данных.

Создание двигателя сводится к выполнению одного вызова create_engine():

from sqlalchemy import create_engine

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost:5432/mydatabase")

Приведенный выше механизм создает объект Dialect, предназначенный для PostgreSQL, а также объект Pool, который будет устанавливать DBAPI-соединение в localhost:5432 при первом получении запроса на соединение. Обратите внимание, что Engine и лежащий в его основе Pool не устанавливают первое фактическое DBAPI-соединение, пока не будет вызван метод Engine.connect() или не будет вызвана операция, зависящая от этого метода, такая как Engine.execute(). Таким образом, можно сказать, что Engine и Pool имеют поведение ленивой инициализации.

Созданный Engine можно либо использовать непосредственно для взаимодействия с базой данных, либо передать объекту Session для работы с ORM. В этом разделе рассматриваются детали конфигурирования Engine. В следующем разделе, Работа с двигателями и соединениями, будет подробно описано использование API Engine и подобных ему, обычно для приложений, не относящихся к ОРМ.

Поддерживаемые базы данных

SQLAlchemy включает множество Dialect реализаций для различных бэкендов. Диалекты для наиболее распространенных баз данных включены в SQLAlchemy; для некоторых других требуется дополнительная установка отдельного диалекта.

Информацию о различных доступных бэкендах см. в разделе Диалекты.

URL-адреса баз данных

Функция create_engine() создает объект Engine на основе URL. Формат URL обычно соответствует формату RFC-1738, с некоторыми исключениями, включая то, что в части «схема» принимаются символы подчеркивания, а не тире или точки. URL обычно включает поля имени пользователя, пароля, имени хоста, имени базы данных, а также необязательные аргументы в виде ключевых слов для дополнительной настройки. В некоторых случаях принимается путь к файлу, а в других «имя источника данных» заменяет части «хост» и «база данных». Типичная форма URL базы данных выглядит следующим образом:

dialect+driver://username:password@host:port/database

Имена диалектов включают идентифицирующее имя диалекта SQLAlchemy, такое имя, как sqlite, mysql, postgresql, oracle или mssql. Имя драйвера - это имя DBAPI, которое будет использоваться для подключения к базе данных, с использованием всех строчных букв. Если оно не указано, будет импортирован DBAPI «по умолчанию», если он доступен - по умолчанию обычно используется наиболее известный драйвер, доступный для данного бэкенда.

Исключение специальных символов, таких как знаки @ в паролях

При построении полностью сформированной строки URL для передачи в create_engine(), специальные символы, такие как те, которые могут быть использованы в пользователе и пароле, должны быть закодированы в URL для правильного разбора. Это включает знак @.

Ниже приведен пример URL, который включает пароль "kx@jj5/g", где знак «at» и символы косой черты представлены как %40 и %2F соответственно:

postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb

Кодировка для приведенного выше пароля может быть сгенерирована с помощью urllib.parse:

>>> import urllib.parse
>>> urllib.parse.quote_plus("kx@jj5/g")
'kx%40jj5%2Fg'

Затем URL может быть передан в виде строки в create_engine():

from sqlalchemy import create_engine

engine = create_engine("postgresql+pg8000://dbuser:kx%40jj5%2Fg@pghost10/appdb")

В качестве альтернативы экранированию специальных символов для создания полной строки URL, объект, передаваемый в create_engine(), может быть экземпляром объекта URL, который обходит фазу разбора и может использовать строки без экранирования напрямую. Пример см. в следующем разделе.

Изменено в версии 1.4: Исправлена поддержка знаков @ в именах хостов и базах данных. Как побочный эффект этого исправления, знаки @ в паролях должны быть экранированы.

Создание URL-адресов программным способом

Значение, передаваемое в create_engine(), может быть экземпляром URL, а не простой строкой, что позволяет обойти необходимость разбора строки и, следовательно, не требует предоставления экранированной строки URL.

Объект URL создается с помощью метода конструктора URL.create(), передавая все поля по отдельности. Специальные символы, такие как символы в паролях, могут передаваться без каких-либо изменений:

from sqlalchemy import URL

url_object = URL.create(
    "postgresql+pg8000",
    username="dbuser",
    password="kx@jj5/g",  # plain (unescaped) text
    host="pghost10",
    database="appdb",
)

Построенный объект URL может быть передан непосредственно в create_engine() вместо строкового аргумента:

from sqlalchemy import create_engine

engine = create_engine(url_object)

См.также

URL

URL.create()

URL-адреса, специфичные для бэкенда

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

PostgreSQL

Диалект PostgreSQL использует psycopg2 в качестве DBAPI по умолчанию. Другие интерфейсы DBAPI PostgreSQL включают pg8000 и asyncpg:

# default
engine = create_engine("postgresql://scott:tiger@localhost/mydatabase")

# psycopg2
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/mydatabase")

# pg8000
engine = create_engine("postgresql+pg8000://scott:tiger@localhost/mydatabase")

Дополнительные сведения о подключении к PostgreSQL можно найти на сайте PostgreSQL.

MySQL

Диалект MySQL использует mysqlclient в качестве DBAPI по умолчанию. Существуют и другие DBAPI для MySQL, включая PyMySQL:

# default
engine = create_engine("mysql://scott:tiger@localhost/foo")

# mysqlclient (a maintained fork of MySQL-Python)
engine = create_engine("mysql+mysqldb://scott:tiger@localhost/foo")

# PyMySQL
engine = create_engine("mysql+pymysql://scott:tiger@localhost/foo")

Более подробная информация о подключении к MySQL на сайте MySQL и MariaDB.

Oracle

Диалект Oracle использует cx_oracle в качестве DBAPI по умолчанию:

engine = create_engine("oracle://scott:tiger@127.0.0.1:1521/sidname")

engine = create_engine("oracle+cx_oracle://scott:tiger@tnsname")

Дополнительные сведения о подключении к Oracle на сайте Oracle.

Microsoft SQL Server

Диалект SQL Server использует pyodbc в качестве DBAPI по умолчанию. Также доступен pymssql:

# pyodbc
engine = create_engine("mssql+pyodbc://scott:tiger@mydsn")

# pymssql
engine = create_engine("mssql+pymssql://scott:tiger@hostname:port/dbname")

Дополнительные сведения о подключении к SQL Server можно найти на сайте Microsoft SQL Server.

SQLite

SQLite подключается к базам данных на основе файлов, используя по умолчанию встроенный модуль Python sqlite3.

Поскольку SQLite подключается к локальным файлам, формат URL немного отличается. Часть URL «file» - это имя файла базы данных. Для относительного пути к файлу требуется три косых черты:

# sqlite://<nohostname>/<path>
# where <path> is relative:
engine = create_engine("sqlite:///foo.db")

А для абсолютного пути к файлу за тремя косыми чертами следует абсолютный путь:

# Unix/Mac - 4 initial slashes in total
engine = create_engine("sqlite:////absolute/path/to/foo.db")

# Windows
engine = create_engine("sqlite:///C:\\path\\to\\foo.db")

# Windows alternative using raw string
engine = create_engine(r"sqlite:///C:\path\to\foo.db")

Чтобы использовать базу данных SQLite :memory:, укажите пустой URL:

engine = create_engine("sqlite://")

Дополнительные заметки о подключении к SQLite на SQLite.

Другие

Смотрите Диалекты, страницу верхнего уровня для всей дополнительной документации по диалектам.

API создания двигателя

Object Name Description

create_engine(url, **kwargs)

Создайте новый экземпляр Engine.

create_mock_engine(url, executor, **kw)

Создайте «макет» движка, используемого для эха DDL.

create_pool_from_url(url, **kwargs)

Создание экземпляра пула из заданного url.

engine_from_config(configuration[, prefix], **kwargs)

Создайте новый экземпляр Engine, используя словарь конфигурации.

make_url(name_or_url)

Учитывая строку, создайте новый экземпляр URL.

URL

Представляют собой компоненты URL-адреса, используемого для подключения к базе данных.

function sqlalchemy.create_engine(url: Union[str, _url.URL], **kwargs: Any) Engine

Создайте новый экземпляр Engine.

Стандартной формой вызова является передача URL в качестве первого позиционного аргумента, обычно строки, указывающей диалект базы данных и аргументы соединения:

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")

Примечание

Пожалуйста, ознакомьтесь с URL-адреса баз данных для получения общих рекомендаций по составлению строк URL. В частности, специальные символы, такие как те, которые часто входят в состав паролей, должны быть закодированы в URL, чтобы их можно было правильно разобрать.

После него могут следовать дополнительные аргументы ключевых слов, которые задают различные опции для результирующего Engine и лежащих в его основе конструкций Dialect и Pool:

engine = create_engine("mysql+mysqldb://scott:tiger@hostname/dbname",
                            pool_recycle=3600, echo=True)

Строковая форма URL имеет вид dialect[+driver]://user:password@host/dbname[?key=value..], где dialect - имя базы данных, такое как mysql, oracle, postgresql и т.д., а driver - имя DBAPI, такое как psycopg2, pyodbc, cx_oracle и т.д. В качестве альтернативы, URL может быть экземпляром URL.

**kwargs принимает широкий спектр опций, которые направляются к соответствующим компонентам. Аргументы могут быть специфичными для Engine, базового Dialect, а также Pool. Конкретные диалекты также принимают аргументы с ключевыми словами, которые уникальны для этого диалекта. Здесь мы описываем параметры, которые являются общими для большинства случаев использования create_engine().

После установления соединения, вновь образовавшийся Engine будет запрашивать соединение от базового Pool при вызове Engine.connect() или метода, который зависит от него, например, Engine.execute(). Pool в свою очередь установит первое фактическое DBAPI-соединение, когда этот запрос будет получен. Сам вызов create_engine() не **** устанавливает никаких реальных соединений DBAPI напрямую.

Параметры:
  • connect_args – словарь опций, которые будут переданы непосредственно в метод DBAPI connect() в качестве дополнительных аргументов ключевого слова. См. пример в Пользовательские аргументы DBAPI connect() / процедуры включения соединения.

  • creator – вызываемая функция, которая возвращает соединение DBAPI. Эта функция создания будет передана базовому пулу соединений и будет использоваться для создания всех новых соединений с базой данных. Использование этой функции приводит к тому, что параметры соединения, указанные в аргументе URL, будут обойдены. Этот хук не такой гибкий, как более новый хук DialectEvents.do_connect(), который позволяет полностью контролировать процесс создания соединения с базой данных, учитывая полный набор аргументов URL и состояние. … см. также:: DialectEvents.do_connect() - событийный хук, позволяющий полностью контролировать механику соединения DBAPI. Пользовательские аргументы DBAPI connect() / процедуры включения соединения

  • echo=False – если True, движок будет записывать все операторы, а также repr() списки их параметров в журнал обработчика журнала по умолчанию, который по умолчанию имеет значение sys.stdout для вывода. Если установлено значение строки "debug", строки результатов будут также выводиться на стандартный вывод. Атрибут echo в Engine можно изменить в любое время, чтобы включить или выключить ведение журнала; прямое управление ведением журнала также доступно с помощью стандартного модуля Python logging. … см. также:: Настройка ведения журнала - более подробно о том, как настроить ведение журнала.

  • echo_pool=False – если True, пул соединений будет записывать в журнал информационные данные, например, когда соединения аннулируются, а также когда соединения перерабатываются в обработчик журнала по умолчанию, который по умолчанию использует для вывода значение sys.stdout. Если установлено значение строки "debug", в журнал будут записываться данные о выбытии и регистрации пула. Прямое управление логированием также доступно с помощью стандартного модуля Python logging. … см. также:: Настройка ведения журнала - более подробно о том, как настроить ведение журнала.

  • empty_in_strategy – Больше не используется; SQLAlchemy теперь использует поведение «пустое множество» для IN во всех случаях. … deprecated:: 1.4 Ключевое слово create_engine.empty_in_strategy устарело и больше не имеет никакого эффекта. Все выражения IN теперь отображаются с использованием стратегии «расширяющегося параметра», которая отображает набор связанных выражений или «пустое множество» SELECT во время выполнения оператора.

  • enable_from_linting – по умолчанию имеет значение True. Выдает предупреждение, если в данном операторе SELECT обнаружены несвязанные элементы FROM, которые могут привести к возникновению картезианского произведения. … versionadded:: 1.4 .. seealso:: Встроенный линтинг FROM предупреждает о возможных картезианских произведениях в операторе SELECT

  • execution_options – Параметры выполнения словаря, которые будут применяться ко всем соединениям. См. Connection.execution_options()

  • future – Использовать API Engine и Connection в стиле 2.0. Начиная с версии SQLAlchemy 2.0, этот параметр присутствует только для обратной совместимости и должен иметь значение по умолчанию True. Параметр create_engine.future будет устаревшим в последующем выпуске 2.x и в конечном итоге будет удален. … versionadded:: 1.4 … versionchanged:: 2.0 Все объекты Engine являются движками «будущего» стиля, и больше нет режима работы future=False. … seealso:: SQLAlchemy 2.0 - руководство по миграции

  • hide_parameters – Булево значение, при установке которого в True параметры SQL-оператора не будут отображаться в журнале INFO и не будут форматироваться в строковое представление объектов StatementError. … добавлена версия:: 1.3.8 .. seealso:: Настройка ведения журнала - более подробно о том, как настроить ведение журнала.

  • implicit_returning=True – Устаревший параметр, который может быть установлен только в True. В SQLAlchemy 2.0 этот параметр ничего не делает. Чтобы отключить «неявное возвращение» для операторов, вызываемых ORM, настройте это для каждой таблицы с помощью параметра Table.implicit_returning.

  • insertmanyvalues_page_size – количество строк для форматирования в оператор INSERT, когда оператор использует режим «insertmanyvalues», который является страничной формой массовой вставки, используемой во многих бэкендах при использовании выполнения executemany, обычно в сочетании с RETURNING. Значение по умолчанию равно 1000, но также может быть подвержено специфическим для диалекта ограничивающим факторам, которые могут переопределять это значение для каждого конкретного запроса. … версия добавлена:: 2.0 .. seealso:: Поведение «Вставка многих значений» для операторов INSERT Управление размером партии Connection.execution_options.insertmanyvalues_page_size

  • isolation_level – необязательное строковое имя уровня изоляции, который будет устанавливаться для всех новых соединений безоговорочно. Уровни изоляции обычно представляют собой некоторое подмножество строковых имен "SERIALIZABLE", "REPEATABLE READ", "READ COMMITTED", "READ UNCOMMITTED" и "AUTOCOMMIT" в зависимости от бэкенда. Параметр create_engine.isolation_level отличается от параметра выполнения Connection.execution_options.isolation_level, который может быть установлен на отдельном Connection, а также от того же параметра, передаваемого в Engine.execution_options(), где он может быть использован для создания нескольких движков с различными уровнями изоляции, имеющих общий пул соединений и диалект. … versionchanged:: 2.0 Параметр create_engine.isolation_level был обобщен для работы со всеми диалектами, которые поддерживают концепцию уровня изоляции, и предоставляется как более лаконичный, предварительный переключатель конфигурации в отличие от параметра выполнения, который является скорее специальным программным параметром. … см. также:: Установка уровней изоляции транзакций, включая DBAPI Autocommit

  • json_deserializer – для диалектов, поддерживающих тип данных JSON, это вызываемая функция Python, которая преобразует строку JSON в объект Python. По умолчанию используется функция Python json.loads. … versionchanged:: 1.3.7 В диалекте SQLite эта функция переименована из _json_deserializer.

  • json_serializer – для диалектов, поддерживающих тип данных JSON, это вызываемая функция Python, которая выводит заданный объект в формате JSON. По умолчанию используется функция Python json.dumps. … versionchanged:: 1.3.7 Диалект SQLite переименовал эту функцию из _json_serializer.

  • label_length=None – необязательное целочисленное значение, которое ограничивает размер динамически генерируемых меток столбцов данным количеством символов. Если меньше 6, метки генерируются как «_(counter)». Если None, то вместо него используется значение dialect.max_identifier_length, на которое можно повлиять с помощью параметра create_engine.max_identifier_length. Значение create_engine.label_length не может быть больше, чем значение create_engine.max_identfier_length. … см. также:: create_engine.max_identifier_length

  • logging_name – Строковый идентификатор, который будет использоваться в поле «name» записей журнала, создаваемых в логгере «sqlalchemy.engine». По умолчанию это шестнадцатеричная строка идентификатора объекта. … см. также:: Настройка ведения журнала - более подробно о том, как настроить ведение журнала. Connection.execution_options.logging_token

  • max_identifier_length – integer; переопределяет max_identifier_length, определяемую диалектом. если None или ноль, не имеет эффекта. Это настроенное базой данных максимальное количество символов, которое может быть использовано в SQL-идентификаторе, таком как имя таблицы, имя столбца или имя метки. Все диалекты определяют это значение автоматически, однако в случае новой версии базы данных, для которой это значение изменилось, но диалект SQLAlchemy не был настроен, значение может быть передано здесь. … versionadded:: 1.3.9 .. seealso:: create_engine.label_length

  • max_overflow=10 – количество соединений, разрешаемых при «переполнении» пула соединений, то есть соединений, которые могут быть открыты сверх размера пула, который по умолчанию равен пяти. используется только с QueuePool.

  • module=None – ссылка на объект модуля Python (сам модуль, а не его строковое имя). Указывает альтернативный модуль DBAPI, который будет использоваться диалектом движка. Каждый поддиалект ссылается на определенный DBAPI, который будет импортирован перед первым подключением. Этот параметр заставляет обойти импорт, и вместо него будет использоваться указанный модуль. Может быть использован для тестирования DBAPI, а также для внедрения «макетных» реализаций DBAPI в Engine.

  • paramstyle=None – Стиль paramstyle, который следует использовать при отображении связанных параметров. По умолчанию используется стиль, рекомендованный самим DBAPI, который извлекается из атрибута .paramstyle в DBAPI. Однако большинство DBAPI принимают более одного paramstyle, и, в частности, может быть желательно изменить «именованный» paramstyle на «позиционный», или наоборот. Когда передается этот атрибут, он должен быть одним из значений "qmark", "numeric", "named", "format" или "pyformat", и должен соответствовать стилю параметра, который, как известно, поддерживается используемым DBAPI.

  • pool=None – уже созданный экземпляр Pool, например, экземпляр QueuePool. Если значение не None, этот пул будет использоваться непосредственно в качестве основного пула соединений для движка, минуя любые параметры соединения, присутствующие в аргументе URL. Информацию о создании пулов соединений вручную см. в разделе Объединение соединений.

  • poolclass=None – подкласс Pool, который будет использоваться для создания экземпляра пула соединений с использованием параметров соединения, заданных в URL. Обратите внимание, что это отличается от pool тем, что в этом случае вы не создаете пул, а просто указываете, какой тип пула будет использоваться.

  • pool_logging_name – Строковый идентификатор, который будет использоваться в поле «name» записей журнала, создаваемых в логгере «sqlalchemy.pool». По умолчанию это шестнадцатеричная строка идентификатора объекта. … см. также:: Настройка ведения журнала - более подробную информацию о том, как настроить ведение журнала.

  • pool_pre_ping – boolean, если True, то включается функция «pre-ping» пула соединений, которая проверяет соединения на работоспособность при каждой проверке. … версия добавлена:: 1.2 .. seealso:: Работа с разъединениями - пессимистично

  • pool_size=5 – количество соединений, которые необходимо держать открытыми внутри пула соединений. Используется с QueuePool, а также с SingletonThreadPool. В QueuePool значение pool_size, равное 0, означает отсутствие ограничений; чтобы отключить пул, установите вместо poolclass значение NullPool.

  • pool_recycle=-1 – этот параметр заставляет пул перерабатывать соединения по истечении заданного количества секунд. По умолчанию он равен -1, или тайм-аут отсутствует. Например, значение 3600 означает, что соединения будут удаляться через один час. Обратите внимание, что MySQL, в частности, будет автоматически отключаться, если в течение восьми часов не будет обнаружено никакой активности на соединении (хотя это настраивается в самом соединении MySQLDB и в конфигурации сервера). … см. также:: Настройка утилизации пула

  • pool_reset_on_return='rollback' – установить параметр Pool.reset_on_return базового объекта Pool, который может быть установлен в значения "rollback", "commit" или None. … см. также:: Сброс при возврате

  • pool_timeout=30 – количество секунд ожидания перед отказом от получения соединения из пула. Это используется только с QueuePool. Это может быть число с плавающей точкой, но оно подвержено ограничениям функций времени Python, которые могут быть ненадежными в десятках миллисекунд. … примечание: не используйте 30.0 выше, это, кажется, нарушает тег :param.

  • pool_use_lifo=False – использовать LIFO (last-in-first-out) при извлечении соединений из QueuePool вместо FIFO (first-in-first-out). Используя LIFO, схема тайм-аута на стороне сервера может уменьшить количество соединений, используемых в непиковые периоды использования. При планировании тайм-аутов на стороне сервера убедитесь, что используется стратегия рециркуляции или предварительного пинга для изящной обработки устаревших соединений. … версия добавлена:: 1.3 .. seealso:: Использование FIFO против LIFO Работа с разъединениями

  • plugins – строковый список имен плагинов для загрузки. Смотрите CreateEnginePlugin для справки. … versionadded:: 1.2.3

  • query_cache_size – размер кэша, используемого для кэширования строковой формы запросов SQL. Установите нулевое значение, чтобы отключить кэширование. Кэш очищается от последних использованных элементов, когда его размер достигает N * 1,5. По умолчанию установлено значение 500, что означает, что кэш всегда будет хранить не менее 500 SQL-запросов при заполнении, и будет расти до 750 элементов, после чего его размер будет уменьшен до 500 путем удаления 250 последних использованных элементов. Кэширование осуществляется на основе каждого утверждения путем генерации ключа кэша, который представляет структуру утверждения, затем генерируется строка SQL для текущего диалекта, только если этот ключ не присутствует в кэше. Все операторы поддерживают кэширование, однако некоторые функции, такие как INSERT с большим набором параметров, будут намеренно обходить кэш. Журнал SQL будет показывать статистику для каждого оператора, независимо от того, был ли он извлечен из кэша или нет. … примечание:: некоторые функции ORM, связанные с сохранением единицы работы, а также некоторые стратегии загрузки атрибутов будут использовать отдельные кэши для каждого отображателя вне основного кэша. … см. также:: Кэширование компиляции SQL … версия добавлена:: 1.4

  • use_insertmanyvalues – True по умолчанию, по умолчанию используется стиль выполнения «insertmanyvalues» для операторов INSERT..RETURNING. … версия добавлена:: 2.0 .. seealso:: Поведение «Вставка многих значений» для операторов INSERT

function sqlalchemy.engine_from_config(configuration: Dict[str, Any], prefix: str = 'sqlalchemy.', **kwargs: Any) Engine

Создайте новый экземпляр Engine, используя словарь конфигурации.

Словарь обычно создается из конфигурационного файла.

Ключи, представляющие интерес для engine_from_config(), должны иметь префикс, например sqlalchemy.url, sqlalchemy.echo и т.д. Аргумент „prefix“ указывает префикс, по которому будет производиться поиск. Каждый найденный ключ (после удаления префикса) рассматривается так, как если бы он был соответствующим аргументом ключевого слова в вызове create_engine().

Единственным необходимым ключом является (при условии префикса по умолчанию) sqlalchemy.url, который обеспечивает database URL.

Выбранный набор аргументов ключевых слов будет «принудительно приведен» к ожидаемому типу на основе строковых значений. Набор аргументов расширяется в каждом диалекте с помощью аксессора engine_config_types.

Параметры:
  • configuration – Словарь (обычно создается из конфигурационного файла, но это не является обязательным условием). У элементов, ключи которых начинаются со значения „prefix“, этот префикс будет удален, а затем передан в create_engine().

  • prefix – Префикс для соответствия и последующего удаления из ключей в „configuration“.

  • kwargs – Каждый аргумент ключевого слова в engine_from_config() сам переопределяет соответствующий элемент, взятый из словаря „configuration“. Аргументы ключевых слов не должны иметь префикс.

function sqlalchemy.create_mock_engine(url: URL, executor: Any, **kw: Any) MockConnection

Создайте «макет» движка, используемого для эха DDL.

Это служебная функция, используемая для отладки или хранения вывода DDL-последовательностей, генерируемых MetaData.create_all() и связанными с ним методами.

Функция принимает URL, который используется только для определения типа используемого диалекта, а также вызываемую функцию «исполнитель», которая получает объект выражения SQL и параметры, которые затем могут быть выведены эхом или другим способом. Возвращаемое значение исполнителя не обрабатывается, также механизм не позволяет вызывать регулярные строковые операторы, и поэтому он полезен только для DDL, который отправляется в базу данных без получения каких-либо результатов.

Например:

from sqlalchemy import create_mock_engine

def dump(sql, *multiparams, **params):
    print(sql.compile(dialect=engine.dialect))

engine = create_mock_engine('postgresql+psycopg2://', dump)
metadata.create_all(engine, checkfirst=False)
Параметры:
  • url – Строковый URL, который обычно должен содержать только имя бэкенда базы данных.

  • executor – вызываемый объект, который получает аргументы sql, *multiparams и **params. Параметр sql обычно является экземпляром ExecutableDDLElement, который затем может быть скомпилирован в строку с помощью ExecutableDDLElement.compile().

Добавлено в версии 1.4: - the create_mock_engine() function replaces the previous «mock» engine strategy used with create_engine().

function sqlalchemy.engine.make_url(name_or_url: Union[str, URL]) URL

Учитывая строку, создайте новый экземпляр URL.

Формат URL обычно соответствует RFC-1738, с некоторыми исключениями, включая то, что в части «схема» принимаются подчеркивания, а не тире или периоды.

Если передан объект URL, то он возвращается как есть.

function sqlalchemy.create_pool_from_url(url: Union[str, URL], **kwargs: Any) Pool

Создание экземпляра пула из заданного url.

Если poolclass не указано, используемый класс пула выбирается с помощью диалекта, указанного в URL.

Аргументы, передаваемые в create_pool_from_url(), идентичны аргументу pool, передаваемому в функцию create_engine().

Добавлено в версии 2.0.10.

class sqlalchemy.engine.URL

Представляют собой компоненты URL-адреса, используемого для подключения к базе данных.

URL обычно строятся из полностью отформатированной строки URL, где функция make_url() используется внутри функции create_engine() для разбора строки URL на отдельные компоненты, которые затем используются для построения нового объекта URL. При разборе отформатированной строки URL формат разбора обычно следует RFC-1738, за некоторыми исключениями.

Объект URL может быть также создан напрямую, либо с помощью функции make_url() с полностью сформированной строкой URL, либо с помощью конструктора URL.create() для создания URL программно, задавая отдельные поля. Полученный объект URL можно передать непосредственно в create_engine() вместо строкового аргумента, что позволит обойти использование make_url() в процессе создания движка.

Изменено в версии 1.4: Объект URL теперь является неизменяемым объектом. Чтобы создать URL, используйте функцию/метод make_url() или URL.create(). Чтобы изменить URL, используйте такие методы, как URL.set() и URL.update_query_dict(), чтобы вернуть новый объект URL с изменениями. См. примечания к этому изменению в Объект URL теперь является неизменяемым.

URL содержит следующие атрибуты:

  • URL.drivername: бэкэнд базы данных и имя драйвера, например postgresql+psycopg2

  • URL.username: строка имени пользователя

  • URL.password: строка пароля

  • URL.host: строка hostname

  • URL.port: целочисленный номер порта

  • URL.database: строковое имя базы данных

  • URL.query: неизменяемое отображение, представляющее строку запроса. содержит строки для ключей и либо строки, либо кортежи строк для значений.

Классная подпись

класс sqlalchemy.engine.URL (builtins.tuple)

classmethod sqlalchemy.engine.URL.create(drivername: str, username: Optional[str] = None, password: Optional[str] = None, host: Optional[str] = None, port: Optional[int] = None, database: Optional[str] = None, query: Mapping[str, Union[Sequence[str], str]] = {}) URL

Создайте новый объект URL.

Параметры:
  • drivername – имя бэкенда базы данных. Это имя будет соответствовать модулю в sqlalchemy/databases или стороннему плагину.

  • username – Имя пользователя.

  • password – пароль базы данных. Обычно это строка, но может быть и объектом, который можно строчить с помощью str(). … примечание:: Объект, генерирующий пароль, будет строфицирован только один раз для каждого объекта Engine. Для динамической генерации пароля для каждого соединения смотрите Генерация динамических маркеров аутентификации.

  • host – Имя хоста.

  • port – Номер порта.

  • database – Имя базы данных.

  • query – Словарь строковых ключей к строковым значениям, которые будут переданы диалекту и/или DBAPI при подключении. Чтобы указать нестроковые параметры для Python DBAPI напрямую, используйте параметр create_engine.connect_args для create_engine(). См. также URL.normalized_query для словаря, который последовательно представляет собой string->list of string.

Результат:

новый URL объект.

Добавлено в версии 1.4: Объект URL теперь является ** неизменяемым именованным кортежем**. Кроме того, словарь query также является неизменяемым. Чтобы создать URL, используйте функцию/метод make_url() или URL.create(). Для изменения URL используйте методы URL.set() и URL.update_query().

attribute sqlalchemy.engine.URL.database: Optional[str]

имя базы данных

method sqlalchemy.engine.URL.difference_update_query(names: Iterable[str]) URL

Удалить заданные имена из словаря URL.query, возвращая новый URL.

Например:

url = url.difference_update_query(['foo', 'bar'])

Эквивалентно использованию URL.set() следующим образом:

url = url.set(
    query={
        key: url.query[key]
        for key in set(url.query).difference(['foo', 'bar'])
    }
)

Добавлено в версии 1.4.

attribute sqlalchemy.engine.URL.drivername: str

бэкэнд базы данных и имя драйвера, например postgresql+psycopg2

method sqlalchemy.engine.URL.get_backend_name() str

Возвращает имя бэкенда.

Это имя, которое соответствует используемому бэкенду базы данных, и является частью URL.drivername, которая находится слева от знака плюс.

method sqlalchemy.engine.URL.get_dialect(_is_async: bool = False) Type[Dialect]

Возвращает класс SQLAlchemy Dialect, соответствующий имени драйвера данного URL.

method sqlalchemy.engine.URL.get_driver_name() str

Возвращает имя бэкенда.

Это имя, которое соответствует используемому драйверу DBAPI, и является частью URL.drivername, которая находится справа от знака плюс.

Если URL.drivername не включает знак плюс, то для получения имени драйвера импортируется Dialect по умолчанию для данного URL.

attribute sqlalchemy.engine.URL.host: Optional[str]

имя хоста или номер IP-адреса. Может также быть именем источника данных для некоторых драйверов.

attribute sqlalchemy.engine.URL.normalized_query

Возвращает словарь URL.query со значениями, нормализованными в последовательности.

Поскольку словарь URL.query может содержать либо строковые значения, либо последовательности строковых значений для различения параметров, которые указаны несколько раз в строке запроса, код, который должен обрабатывать несколько параметров в общем виде, захочет использовать этот атрибут, чтобы все присутствующие параметры были представлены в виде последовательностей. За основу взята функция Python urllib.parse.parse_qs. Например:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
>>> url.query
immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})
>>> url.normalized_query
immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': ('/path/to/crt',)})
attribute sqlalchemy.engine.URL.password: Optional[str]

пароль, который обычно является строкой, но также может быть любым объектом, имеющим метод __str__().

attribute sqlalchemy.engine.URL.port: Optional[int]

целочисленный номер порта

attribute sqlalchemy.engine.URL.query: immutabledict[str, Union[Tuple[str, ...], str]]

неизменяемое отображение, представляющее строку запроса. содержит строки для ключей и либо строки, либо кортежи строк для значений, например:

   >>> from sqlalchemy.engine import make_url
   >>> url = make_url("postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
   >>> url.query
   immutabledict({'alt_host': ('host1', 'host2'), 'ssl_cipher': '/path/to/crt'})

To create a mutable copy of this mapping, use the ``dict`` constructor::

   mutable_query_opts = dict(url.query)

См.также

URL.normalized_query - нормализует все значения в последовательности для последовательной обработки

Методы изменения содержимого URL.query:

URL.update_query_dict()

URL.update_query_string()

URL.update_query_pairs()

URL.difference_update_query()

method sqlalchemy.engine.URL.render_as_string(hide_password: bool = True) str

Вернуть этот объект URL в виде строки.

Этот метод используется, когда применяются методы __str__() или __repr__(). Метод непосредственно включает дополнительные опции.

Параметры:

hide_password – По умолчанию имеет значение True. Пароль не отображается в строке, если значение параметра не установлено в False.

method sqlalchemy.engine.URL.set(drivername: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, host: Optional[str] = None, port: Optional[int] = None, database: Optional[str] = None, query: Optional[Mapping[str, Union[Sequence[str], str]]] = None) URL

возвращает новый объект URL с изменениями.

Значения используются, если они не равны None. Чтобы явно установить значение в None, используйте метод URL._replace(), адаптированный из namedtuple.

Параметры:
  • drivername – новое имя водителя

  • username – новое имя пользователя

  • password – новый пароль

  • host – новое имя хоста

  • port – новый порт

  • query – новые параметры запроса, передаваемые дикту строковых ключей, ссылающихся на строку или последовательность строковых значений. Полностью заменяет предыдущий список аргументов.

Результат:

новый URL объект.

Добавлено в версии 1.4.

См.также

URL.update_query_dict()

method sqlalchemy.engine.URL.translate_connect_args(names: Optional[List[str]] = None, **kw: Any) Dict[str, Any]

Перевести атрибуты url в словарь аргументов соединения.

Возвращает атрибуты этого url (host, database, username, password, port) в виде обычного словаря. По умолчанию в качестве ключей используются имена атрибутов. Неустановленные или ложные атрибуты опускаются из конечного словаря.

Параметры:
  • **kw – Необязательные, альтернативные имена ключей для атрибутов url.

  • names – Утративший силу. Назначение то же, что и у альтернативных имен на основе ключевых слов, но позиционно соотносит имя с оригиналом.

method sqlalchemy.engine.URL.update_query_dict(query_parameters: Mapping[str, Union[str, List[str]]], append: bool = False) URL

Возвращает новый объект URL со словарем параметров URL.query, обновленным заданным словарем.

Словарь обычно содержит строковые ключи и строковые значения. Чтобы представить параметр запроса, который выражается несколько раз, передайте последовательность строковых значений.

Например:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
>>> url = url.update_query_dict({"alt_host": ["host1", "host2"], "ssl_cipher": "/path/to/crt"})
>>> str(url)
'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
Параметры:
  • query_parameters – Словарь со строковыми ключами и значениями, которые являются либо строками, либо последовательностями строк.

  • append – если True, параметры в существующей строке запроса не будут удалены; новые параметры будут добавлены к имеющимся. Если оставить значение по умолчанию False, то ключи, присутствующие в заданных параметрах запроса, заменят ключи из существующей строки запроса.

Добавлено в версии 1.4.

method sqlalchemy.engine.URL.update_query_pairs(key_value_pairs: Iterable[Tuple[str, Union[str, List[str]]]], append: bool = False) URL

Возвращает новый объект URL со словарем параметров URL.query, обновленным заданной последовательностью пар ключ/значение

Например:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
>>> url = url.update_query_pairs([("alt_host", "host1"), ("alt_host", "host2"), ("ssl_cipher", "/path/to/crt")])
>>> str(url)
'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
Параметры:
  • key_value_pairs – Последовательность кортежей, содержащих по две строки.

  • append – если True, параметры в существующей строке запроса не будут удалены; новые параметры будут добавлены к имеющимся. Если оставить значение по умолчанию False, то ключи, присутствующие в заданных параметрах запроса, заменят ключи из существующей строки запроса.

Добавлено в версии 1.4.

method sqlalchemy.engine.URL.update_query_string(query_string: str, append: bool = False) URL

Возвращает новый объект URL со словарем параметров URL.query, обновленным по заданной строке запроса.

Например:

>>> from sqlalchemy.engine import make_url
>>> url = make_url("postgresql+psycopg2://user:pass@host/dbname")
>>> url = url.update_query_string("alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt")
>>> str(url)
'postgresql+psycopg2://user:pass@host/dbname?alt_host=host1&alt_host=host2&ssl_cipher=%2Fpath%2Fto%2Fcrt'
Параметры:
  • query_string – строка запроса, преобразованная в URL, не включая вопросительный знак.

  • append – если True, параметры в существующей строке запроса не будут удалены; новые параметры будут добавлены к имеющимся. Если оставить значение по умолчанию False, то ключи, присутствующие в заданных параметрах запроса, заменят ключи из существующей строки запроса.

Добавлено в версии 1.4.

attribute sqlalchemy.engine.URL.username: Optional[str]

строка имени пользователя

Объединение

Engine будет запрашивать у пула соединений соединение, когда будут вызваны методы connect() или execute(). Пул соединений по умолчанию, QueuePool, будет открывать соединения с базой данных по мере необходимости. По мере выполнения параллельных операторов, QueuePool будет увеличивать свой пул соединений до размера по умолчанию в пять, и допускать «переполнение» по умолчанию в десять. Поскольку Engine является по сути «домашней базой» для пула соединений, из этого следует, что вы должны держать один Engine на базу данных, установленную в приложении, а не создавать новый для каждого соединения.

Примечание

QueuePool не используется по умолчанию для движков SQLite. Подробнее об использовании пула соединений SQLite смотрите SQLite.

Для получения дополнительной информации о пуле соединений смотрите Объединение соединений.

Пользовательские аргументы DBAPI connect() / процедуры включения соединения

Для случаев, когда требуются специальные методы соединения, в подавляющем большинстве случаев наиболее целесообразно использовать один из нескольких крючков на уровне create_engine(), чтобы настроить этот процесс. Они описаны в следующих подразделах.

Специальные ключевые аргументы, передаваемые в dbapi.connect()

Все Python DBAPI принимают дополнительные аргументы, выходящие за рамки основных параметров подключения. К обычным параметрам относятся параметры для задания кодировок наборов символов и значений тайм-аута; более сложные данные включают специальные константы и объекты DBAPI и подпараметры SSL. Существует два элементарных способа передачи этих аргументов без усложнения.

Добавление параметров в строку запроса URL

Простые строковые значения, а также некоторые числовые значения и булевы флаги часто могут быть указаны в строке запроса URL напрямую. Частым примером этого являются DBAPI, которые принимают аргумент encoding для кодировок символов, например, большинство MySQL DBAPI:

engine = create_engine("mysql+pymysql://user:pass@host/test?charset=utf8mb4")

Преимущество использования строки запроса заключается в том, что дополнительные параметры DBAPI могут быть указаны в конфигурационных файлах способом, переносимым на DBAPI, указанный в URL. Конкретные параметры, передаваемые на этом уровне, зависят от диалекта SQLAlchemy. Некоторые диалекты передают все аргументы в виде строк, другие анализируют определенные типы данных и перемещают параметры в различные места, например, в DSN на уровне драйвера и строки подключения. Поскольку в настоящее время поведение в этой области зависит от диалекта, следует обратиться к документации по конкретному используемому диалекту, чтобы узнать, поддерживаются ли определенные параметры на этом уровне.

Совет

Общая техника отображения точных аргументов, переданных DBAPI для данного URL, может быть выполнена с помощью метода Dialect.create_connect_args() непосредственно следующим образом:

>>> from sqlalchemy import create_engine
>>> engine = create_engine(
...     "mysql+pymysql://some_user:some_pass@some_host/test?charset=utf8mb4"
... )
>>> args, kwargs = engine.dialect.create_connect_args(engine.url)
>>> args, kwargs
([], {'host': 'some_host', 'database': 'test', 'user': 'some_user', 'password': 'some_pass', 'charset': 'utf8mb4', 'client_flag': 2})

Приведенная выше пара args, kwargs обычно передается в DBAPI как dbapi.connect(*args, **kwargs).

Используйте параметр словаря connect_args

Более общей системой передачи любого параметра в функцию dbapi.connect(), которая гарантированно передает все параметры в любое время, является параметр словаря create_engine.connect_args. Он может использоваться для параметров, которые иначе не обрабатываются диалектом при добавлении в строку запроса, а также когда в DBAPI должны быть переданы специальные подструктуры или объекты. Иногда бывает, что определенный флаг должен быть отправлен в виде символа True, а диалект SQLAlchemy не знает об этом ключевом аргументе, чтобы вырвать его из строковой формы, представленной в URL. Ниже показано использование «фабрики соединений» psycopg2, которая заменяет базовую реализацию connection:

engine = create_engine(
    "postgresql+psycopg2://user:pass@hostname/dbname",
    connect_args={"connection_factory": MyConnectionFactory},
)

Другим примером является параметр pyodbc «timeout»:

engine = create_engine(
    "mssql+pyodbc://user:pass@sqlsrvr?driver=ODBC+Driver+13+for+SQL+Server",
    connect_args={"timeout": 30},
)

Приведенный выше пример также иллюстрирует, что одновременно могут использоваться как параметры «строки запроса» URL, так и create_engine.connect_args; в случае с pyodbc ключевое слово «driver» имеет особое значение в URL.

Управление передачей параметров в функцию DBAPI connect()

Помимо манипулирования параметрами, передаваемыми в connect(), мы можем дополнительно настроить вызов самой функции DBAPI connect() с помощью крючка событий DialectEvents.do_connect(). Этому крючку передается полный *args, **kwargs, который диалект будет посылать в connect(). Затем эти коллекции могут быть изменены на месте, чтобы изменить способ их использования:

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user:pass@hostname/dbname")


@event.listens_for(engine, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    cparams["connection_factory"] = MyConnectionFactory

Генерация динамических маркеров аутентификации

DialectEvents.do_connect() также является идеальным способом динамической вставки маркера аутентификации, который может меняться в течение жизни Engine. Например, если маркер генерируется get_authentication_token() и передается в DBAPI в параметре token, это можно реализовать следующим образом:

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user@hostname/dbname")


@event.listens_for(engine, "do_connect")
def provide_token(dialect, conn_rec, cargs, cparams):
    cparams["token"] = get_authentication_token()

См.также

Подключение к базам данных с помощью маркеров доступа - более конкретный пример с участием SQL Server

Изменение соединения DBAPI после подключения или выполнение команд после подключения

Для DBAPI-соединения, которое SQLAlchemy создает без проблем, но когда мы хотим изменить созданное соединение до его использования, например, для установки специальных флагов или выполнения определенных команд, наиболее подходящим является хук события PoolEvents.connect(). Этот хук вызывается для каждого нового созданного соединения, прежде чем оно будет использовано SQLAlchemy:

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user:pass@hostname/dbname")


@event.listens_for(engine, "connect")
def connect(dbapi_connection, connection_record):
    cursor_obj = dbapi_connection.cursor()
    cursor_obj.execute("SET some session variables")
    cursor_obj.close()

Полная замена функции DBAPI connect()

Наконец, крючок события DialectEvents.do_connect() может также позволить нам полностью взять на себя процесс соединения, устанавливая соединение и возвращая его:

from sqlalchemy import event

engine = create_engine("postgresql+psycopg2://user:pass@hostname/dbname")


@event.listens_for(engine, "do_connect")
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    # return the new DBAPI connection with whatever we'd like to
    # do
    return psycopg2.connect(*cargs, **cparams)

Хук DialectEvents.do_connect() заменяет предыдущий хук create_engine.creator, который остается доступным. Преимущество DialectEvents.do_connect() заключается в том, что все аргументы, разобранные из URL, также передаются в пользовательскую функцию, чего нельзя сказать о create_engine.creator.

Настройка ведения журнала

Стандартный модуль Python logging используется для реализации вывода информационных и отладочных журналов в SQLAlchemy. Это позволяет журналу SQLAlchemy интегрироваться стандартным образом с другими приложениями и библиотеками. Также в модуле create_engine() присутствуют два параметра create_engine.echo и create_engine.echo_pool, которые позволяют немедленно записывать логи в sys.stdout для целей локальной разработки; эти параметры в конечном итоге взаимодействуют с обычными логгерами Python, описанными ниже.

Этот раздел предполагает знакомство с вышеупомянутым модулем протоколирования. Все логирование, выполняемое SQLAlchemy, существует в пространстве имен sqlalchemy, используемом logging.getLogger('sqlalchemy'). Если логирование настроено (например, через logging.basicConfig()), общее пространство имен SA-логгеров, которые могут быть включены, выглядит следующим образом:

  • sqlalchemy.engine - управляет эхом SQL. Установите значение logging.INFO для вывода SQL-запроса, logging.DEBUG для вывода запроса + набора результатов. Эти настройки эквивалентны echo=True и echo="debug" на create_engine.echo соответственно.

  • sqlalchemy.pool - управляет протоколированием пула соединений. Установите значение logging.INFO, чтобы регистрировать события аннулирования и восстановления соединения; установите значение logging.DEBUG, чтобы дополнительно регистрировать все регистрации и выгрузки пула. Эти настройки эквивалентны pool_echo=True и pool_echo="debug" на create_engine.echo_pool соответственно.

  • sqlalchemy.dialects - управляет пользовательским протоколированием для диалектов SQL, в той степени, в которой протоколирование используется в конкретных диалектах, что обычно минимально.

  • sqlalchemy.orm - управляет протоколированием различных функций ORM в той степени, в которой протоколирование используется внутри ORM, что обычно минимально. Установите значение logging.INFO для записи в журнал некоторой информации верхнего уровня о конфигурациях маппера.

Например, для регистрации SQL-запросов с использованием Python logging вместо флага echo=True:

import logging

logging.basicConfig()
logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)

По умолчанию уровень журнала установлен на logging.WARN во всем пространстве имен sqlalchemy, так что никаких операций с журналом не происходит, даже в приложении, в котором журнал включен.

Примечание

SQLAlchemy Engine экономит накладные расходы на вызов функций Python, выдавая отчеты журнала только тогда, когда текущий уровень регистрации определяется как logging.INFO или logging.DEBUG. Он проверяет этот уровень только при получении нового соединения из пула соединений. Поэтому при изменении конфигурации протоколирования для уже работающего приложения любой активный в данный момент Connection или, что более распространено, активный в транзакции объект Session не будет протоколировать SQL в соответствии с новой конфигурацией, пока не будет получено новое Connection (в случае Session это происходит после завершения текущей транзакции и начала новой).

Подробнее о Флаг Эхо

Как упоминалось ранее, параметры create_engine.echo и create_engine.echo_pool являются ярлыком для немедленной записи в журнал sys.stdout:

>>> from sqlalchemy import create_engine, text
>>> e = create_engine("sqlite://", echo=True, echo_pool="debug")
>>> with e.connect() as conn:
...     print(conn.scalar(text("select 'hi'")))
2020-10-24 12:54:57,701 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Created new connection <sqlite3.Connection object at 0x7f287819ac60>
2020-10-24 12:54:57,701 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Connection <sqlite3.Connection object at 0x7f287819ac60> checked out from pool
2020-10-24 12:54:57,702 INFO sqlalchemy.engine.Engine select 'hi'
2020-10-24 12:54:57,702 INFO sqlalchemy.engine.Engine ()
hi
2020-10-24 12:54:57,703 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Connection <sqlite3.Connection object at 0x7f287819ac60> being returned to pool
2020-10-24 12:54:57,704 DEBUG sqlalchemy.pool.impl.SingletonThreadPool Connection <sqlite3.Connection object at 0x7f287819ac60> rollback-on-return

Использование этих флагов примерно эквивалентно:

import logging

logging.basicConfig()
logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)
logging.getLogger("sqlalchemy.pool").setLevel(logging.DEBUG)

Важно отметить, что эти два флага работают независимо от любой существующей конфигурации логирования, и будут использовать logging.basicConfig() безоговорочно. Это имеет эффект настройки в дополнение к любым существующим конфигурациям логгеров. Поэтому при явной настройке логирования убедитесь, что все флаги echo всегда установлены в False, чтобы избежать дублирования строк журнала.

Настройка имени регистрации

Имя регистратора экземпляра, такого как Engine или Pool, по умолчанию использует усеченную строку шестнадцатеричного идентификатора. Чтобы задать конкретное имя, используйте create_engine.logging_name и create_engine.pool_logging_name с sqlalchemy.create_engine():

>>> from sqlalchemy import create_engine
>>> from sqlalchemy import text
>>> e = create_engine("sqlite://", echo=True, logging_name="myengine")
>>> with e.connect() as conn:
...     conn.execute(text("select 'hi'"))
2020-10-24 12:47:04,291 INFO sqlalchemy.engine.Engine.myengine select 'hi'
2020-10-24 12:47:04,292 INFO sqlalchemy.engine.Engine.myengine ()

Настройка токенов для каждого соединения / суб-инженера

Добавлено в версии 1.4.0b2.

В то время как имя регистрации целесообразно устанавливать на долгоживущем объекте Engine, оно недостаточно гибко для произвольно большого списка имен в случае отслеживания отдельных соединений и/или транзакций в сообщениях журнала.

Для этого случая само сообщение журнала, генерируемое объектами Connection и Result, может быть дополнено дополнительными маркерами, такими как идентификаторы транзакций или запросов. Параметр Connection.execution_options.logging_token принимает строковый аргумент, который может быть использован для установки маркеров отслеживания каждого соединения:

>>> from sqlalchemy import create_engine
>>> e = create_engine("sqlite://", echo="debug")
>>> with e.connect().execution_options(logging_token="track1") as conn:
...     conn.execute("select 1").all()
2021-02-03 11:48:45,754 INFO sqlalchemy.engine.Engine [track1] select 1
2021-02-03 11:48:45,754 INFO sqlalchemy.engine.Engine [track1] [raw sql] ()
2021-02-03 11:48:45,754 DEBUG sqlalchemy.engine.Engine [track1] Col ('1',)
2021-02-03 11:48:45,755 DEBUG sqlalchemy.engine.Engine [track1] Row (1,)

Параметр Connection.execution_options.logging_token также может быть установлен на движки или поддвижки через create_engine.execution_options или Engine.execution_options(). Это может быть полезно для применения различных маркеров протоколирования к различным компонентам приложения без создания новых двигателей:

>>> from sqlalchemy import create_engine
>>> e = create_engine("sqlite://", echo="debug")
>>> e1 = e.execution_options(logging_token="track1")
>>> e2 = e.execution_options(logging_token="track2")
>>> with e1.connect() as conn:
...     conn.execute("select 1").all()
2021-02-03 11:51:08,960 INFO sqlalchemy.engine.Engine [track1] select 1
2021-02-03 11:51:08,960 INFO sqlalchemy.engine.Engine [track1] [raw sql] ()
2021-02-03 11:51:08,960 DEBUG sqlalchemy.engine.Engine [track1] Col ('1',)
2021-02-03 11:51:08,961 DEBUG sqlalchemy.engine.Engine [track1] Row (1,)

>>> with e2.connect() as conn:
...     conn.execute("select 2").all()
2021-02-03 11:52:05,518 INFO sqlalchemy.engine.Engine [track2] Select 1
2021-02-03 11:52:05,519 INFO sqlalchemy.engine.Engine [track2] [raw sql] ()
2021-02-03 11:52:05,520 DEBUG sqlalchemy.engine.Engine [track2] Col ('1',)
2021-02-03 11:52:05,520 DEBUG sqlalchemy.engine.Engine [track2] Row (1,)

Скрытие параметров

Журнал, создаваемый Engine, также показывает выдержку из параметров SQL, которые присутствуют для конкретного оператора. Чтобы предотвратить регистрацию этих параметров в целях конфиденциальности, включите флаг create_engine.hide_parameters:

>>> e = create_engine("sqlite://", echo=True, hide_parameters=True)
>>> with e.connect() as conn:
...     conn.execute(text("select :some_private_name"), {"some_private_name": "pii"})
2020-10-24 12:48:32,808 INFO sqlalchemy.engine.Engine select ?
2020-10-24 12:48:32,808 INFO sqlalchemy.engine.Engine [SQL parameters hidden due to hide_parameters=True]
Вернуться на верх