Skip to content

SQL-движки#

Модуль: restalchemy.storage.sql.engines

Модуль содержит фабрику движков и конкретные реализации SQL-движков для MySQL и PostgreSQL.

AbstractEngine#

AbstractEngine описывает общее поведение всех SQL-движков:

  • Парсит URL подключения к БД.
  • Предоставляет имя БД, хост, порт, логин и пароль.
  • Хранит диалект SQL (mysql.MySQLDialect или pgsql.PgSQLDialect).
  • Предоставляет контекстный менеджер session_manager().

Ключевые члены:

  • URL_SCHEMA (абстрактное свойство): ожидаемая схема URL ("mysql", "postgresql").
  • DEFAULT_PORT (абстрактное свойство): порт по умолчанию.
  • db_name, db_username, db_password, db_host, db_port.
  • dialect: объект диалекта.
  • query_cache: признак включённого кэша запросов.
  • get_connection(): получение соединения (реализуется в подклассах).
  • get_session(): получение сессии (реализуется в подклассах).
  • session_manager(session=None): контекстный менеджер для управления транзакцией и жизненным циклом сессии.
  • get_session_storage(): возвращает хранилище сессий (SessionThreadStorage).

Пример:

from restalchemy.storage.sql import engines

engine = engines.engine_factory.get_engine()
print(engine.db_name)

PostgreSQL-движок#

PgSQLEngine#

  • URL_SCHEMA = "postgresql".
  • Порт по умолчанию берётся из RA_POSTGRESQL_DB_PORT.
  • Использует пул psycopg_pool.ConnectionPool.
  • Диалект: pgsql.PgSQLDialect().
  • Тип сессии: sessions.PgSQLSession.

Конструктор:

PgSQLEngine(db_url, config=None, query_cache=False)

Методы:

  • get_session(): возвращает PgSQLSession(engine=self).
  • get_connection(): берёт соединение из пула.
  • close_connection(conn): возвращает соединение в пул.

Таймауты соединения#

register_postgresql_db_opts() регистрирует настройки таймаутов соединения, сервера и TCP. Продолжительность задаётся в секундах. Если опция не указана, сохраняется соответствующая настройка libpq, PostgreSQL или операционной системы. Явное значение 0 передаётся драйверу; для серверных таймаутов PostgreSQL оно отключает таймаут.

  • connection_connect_timeout: время на установление соединения.
  • connection_statement_timeout: максимальное время выполнения SQL-запроса.
  • connection_transaction_timeout: максимальная длительность транзакции; требуется PostgreSQL 17 или новее.
  • connection_idle_in_transaction_session_timeout: максимальное время простоя сессии внутри транзакции.
  • connection_tcp_user_timeout: максимальное время без подтверждения переданных TCP-данных.
  • connection_keepalives_idle, connection_keepalives_interval и connection_keepalives_count: параметры обнаружения разрыва через TCP keepalive.

Пример ограничивает выполнение запроса и простой транзакции четырьмя минутами, а транзакцию целиком и неподтверждённые TCP-данные — пятью минутами:

[db]
connection_connect_timeout = 30
connection_statement_timeout = 240
connection_transaction_timeout = 300
connection_idle_in_transaction_session_timeout = 240
connection_tcp_user_timeout = 300
connection_keepalives_idle = 60
connection_keepalives_interval = 30
connection_keepalives_count = 5

MySQL-движок#

MySQLEngine#

  • URL_SCHEMA = "mysql".
  • Порт по умолчанию из RA_MYSQL_DB_PORT.
  • Использует mysql.connector.pooling.MySQLConnectionPool.
  • Диалект: mysql.MySQLDialect().
  • Тип сессии: sessions.MySQLSession.

Конструктор:

MySQLEngine(db_url, config=None, query_cache=False)

Методы:

  • get_connection(): возвращает соединение из пула.
  • get_session(): возвращает MySQLSession(engine=self).

EngineFactory и engine_factory#

EngineFactory#

Синглтон, отвечающий за конфигурацию и хранение экземпляров движков.

Основные методы:

  • configure_factory(db_url, config=None, query_cache=False, name="default")
  • Создаёт экземпляр движка на основе db_url и сохраняет его под именем name.
  • configure_postgresql_factory(conf, section, name)
  • Упрощённая настройка PostgreSQL из конфигурационного объекта.
  • configure_mysql_factory(conf, section, name)
  • Упрощённая настройка MySQL.
  • get_engine(name="default")
  • Возвращает настроенный движок.
  • destroy_engine(name="default") / destroy_all_engines()
  • Удаляют один или все движки.

На уровне модуля определён синглтон:

engine_factory = EngineFactory()

Обычно используется так:

from restalchemy.storage.sql import engines

engines.engine_factory.configure_factory(db_url="mysql://...")
engine = engines.engine_factory.get_engine()

DBConnectionUrl#

DBConnectionUrl — небольшой вспомогательный класс для парсинга и безопасного вывода URL подключения к БД.

  • Хранит распарсенный URL.
  • Свойство url возвращает полный URL.
  • __repr__ скрывает пароль, подставляя :<censored>@.

Полезен в основном для логирования и отладки.