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

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

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 «по умолчанию», если он доступен - по умолчанию обычно используется наиболее известный драйвер, доступный для данного бэкенда.

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

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

from sqlalchemy import create_engine

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

from sqlalchemy import URL

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

from sqlalchemy import create_engine

engine = create_engine(url_object)

# 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")

# 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")

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

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

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

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

# 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")

engine = create_engine("sqlite://")

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

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().

См.также

Как получить вывод CREATE TABLE/ DROP TABLE в виде строки?

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

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

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

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

См.также

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 содержит следующие атрибуты:

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

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

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

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

• URL.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.

См.также

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.

См.также

URL.query

URL.update_query_dict()

URL.set()

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.

См.также

URL.query

URL.update_query_string()

URL.update_query_pairs()

URL.difference_update_query()

URL.set()

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.

См.также

URL.query

URL.difference_update_query()

URL.set()

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.

См.также

URL.query

URL.update_query_dict()

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

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

Объединение¶

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

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

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

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

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

>>> 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})

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

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

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

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()

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()

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)

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

Стандартный модуль 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, так что никаких операций с журналом не происходит, даже в приложении, в котором журнал включен.

>>> 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)

>>> 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 ()

>>> 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,)

>>> 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,)

>>> 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]