Конфигурация двигателя¶
Engine
является отправной точкой для любого приложения SQLAlchemy. Это «домашняя база» для реальной базы данных и ее DBAPI, доставляемой приложению SQLAlchemy через пул соединений и Dialect
, который описывает, как общаться с определенным видом базы данных/комбинацией DBAPI.
Общая структура может быть проиллюстрирована следующим образом:
Там, где указано выше, 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-адреса, специфичные для бэкенда¶
Примеры распространенных стилей соединения приведены ниже. Полный указатель с подробной информацией обо всех включенных диалектах, а также ссылки на диалекты сторонних производителей см. в разделе Диалекты.
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) |
Создайте новый экземпляр |
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-адреса, используемого для подключения к базе данных. |
- 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
можно изменить в любое время, чтобы включить или выключить ведение журнала; прямое управление ведением журнала также доступно с помощью стандартного модуля Pythonlogging
. … см. также:: Настройка ведения журнала - более подробно о том, как настроить ведение журнала.echo_pool=False – если True, пул соединений будет записывать в журнал информационные данные, например, когда соединения аннулируются, а также когда соединения перерабатываются в обработчик журнала по умолчанию, который по умолчанию использует для вывода значение
sys.stdout
. Если установлено значение строки"debug"
, в журнал будут записываться данные о выбытии и регистрации пула. Прямое управление логированием также доступно с помощью стандартного модуля Pythonlogging
. … см. также:: Настройка ведения журнала - более подробно о том, как настроить ведение журнала.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 Autocommitjson_deserializer – для диалектов, поддерживающих тип данных
JSON
, это вызываемая функция Python, которая преобразует строку JSON в объект Python. По умолчанию используется функция Pythonjson.loads
. … versionchanged:: 1.3.7 В диалекте SQLite эта функция переименована из_json_deserializer
.json_serializer – для диалектов, поддерживающих тип данных
JSON
, это вызываемая функция Python, которая выводит заданный объект в формате JSON. По умолчанию используется функция Pythonjson.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.3query_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 withcreate_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
: строка hostnameURL.port
: целочисленный номер портаURL.database
: строковое имя базы данныхURL.query
: неизменяемое отображение, представляющее строку запроса. содержит строки для ключей и либо строки, либо кортежи строк для значений.
Members
create(), database, difference_update_query(), drivername, get_backend_name(), get_dialect(), get_driver_name(), host, normalized_query, password, port, query, render_as_string(), set(), translate_connect_args(), update_query_dict(), update_query_pairs(), update_query_string(), username
Классная подпись
класс
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
может содержать либо строковые значения, либо последовательности строковых значений для различения параметров, которые указаны несколько раз в строке запроса, код, который должен обрабатывать несколько параметров в общем виде, захочет использовать этот атрибут, чтобы все присутствующие параметры были представлены в виде последовательностей. За основу взята функция Pythonurllib.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
:
-
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.
См.также
-
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]