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

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

Поскольку URL-адрес похож на любой другой URL-адрес, специальные символы, такие как те, которые могут использоваться в пользователе и пароле, должны быть закодированы в 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-адреса, специфичные для бэкенда¶

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

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

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

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

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://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},
)

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

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

from sqlalchemy import event

engine = create_engine("postgresql://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://user@hostname/dbname")


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

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

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

from sqlalchemy import event

engine = create_engine("postgresql://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://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.

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

Как упоминалось ранее, параметры 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 ()

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

Хотя имя регистрации целесообразно устанавливать на объект 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]