Skip to content

SQL Engines#

Modul: restalchemy.storage.sql.engines

Dieses Modul enthält die Engine-Factory und konkrete Engines für MySQL und PostgreSQL.

AbstractEngine#

AbstractEngine definiert das gemeinsame Verhalten aller SQL-Engines:

  • Parst die Datenbank-URL.
  • Stellt Datenbankname, Host, Port, Benutzername und Passwort bereit.
  • Hält den SQL-Dialekt (mysql.MySQLDialect oder pgsql.PgSQLDialect).
  • Bietet session_manager() als Kontextmanager.

Wichtige Properties und Methoden:

  • URL_SCHEMA (abstrakt): erwartetes URL-Schema, z. B. "mysql", "postgresql".
  • DEFAULT_PORT (abstrakt): Port, der verwendet wird, wenn die URL keinen angibt.
  • db_name, db_username, db_password, db_host, db_port.
  • dialect: das Dialekt-Objekt.
  • query_cache: ob der Query-Cache auf Session-Ebene aktiv ist.
  • get_connection(): liefert eine Verbindung (in Unterklassen implementiert).
  • get_session(): liefert ein Session-Objekt (in Unterklassen implementiert).
  • session_manager(session=None): Kontextmanager, der Commit/Rollback und das Schließen der Session übernimmt.
  • get_session_storage(): liefert den Session-Speicher (SessionThreadStorage).

Beispiel:

from restalchemy.storage.sql import engines

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

PostgreSQL-Engine#

PgSQLEngine#

  • URL_SCHEMA = "postgresql".
  • DEFAULT_PORT stammt aus restalchemy.common.constants.RA_POSTGRESQL_DB_PORT.
  • Nutzt psycopg_pool.ConnectionPool für Verbindungen.
  • Dialekt: pgsql.PgSQLDialect().
  • Session-Typ: sessions.PgSQLSession.

Konstruktor:

PgSQLEngine(db_url, config=None, query_cache=False)
  • db_url: PostgreSQL-Verbindungs-URL.
  • config: wird an psycopg_pool.ConnectionPool durchgereicht.
  • query_cache: aktiviert das Query-Caching.

Methoden:

  • get_session(): liefert PgSQLSession(engine=self).
  • get_connection(): holt eine Verbindung aus dem Pool.
  • close_connection(conn): gibt die Verbindung an den Pool zurück.

Die Engine wird intern von EngineFactory erzeugt.

Verbindungs-Timeouts#

register_postgresql_db_opts() registriert Einstellungen für Verbindungs-, Server- und TCP-Timeouts. Zeiträume werden in Sekunden angegeben. Eine nicht gesetzte Option behält die jeweilige Einstellung von libpq, PostgreSQL oder dem Betriebssystem bei. Ein expliziter Wert von 0 wird an den Treiber übergeben; bei PostgreSQL-Server-Timeouts deaktiviert er den Timeout.

  • connection_connect_timeout: Zeit zum Aufbau einer Verbindung.
  • connection_statement_timeout: maximale Ausführungszeit einer Anweisung.
  • connection_transaction_timeout: maximale Transaktionsdauer; erfordert PostgreSQL 17 oder neuer.
  • connection_idle_in_transaction_session_timeout: maximale Leerlaufzeit einer Sitzung innerhalb einer Transaktion.
  • connection_tcp_user_timeout: maximale Zeit für unbestätigte TCP-Daten.
  • connection_keepalives_idle, connection_keepalives_interval und connection_keepalives_count: Parameter zur TCP-Keepalive-Erkennung.

Beispiel:

[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-Engine#

MySQLEngine#

  • URL_SCHEMA = "mysql".
  • DEFAULT_PORT stammt aus RA_MYSQL_DB_PORT.
  • Nutzt mysql.connector.pooling.MySQLConnectionPool.
  • Dialekt: mysql.MySQLDialect().
  • Session-Typ: sessions.MySQLSession.

Konstruktor:

MySQLEngine(db_url, config=None, query_cache=False)
  • db_url: MySQL-Verbindungs-URL.
  • config: Pool-Konfiguration.
  • query_cache: aktiviert das Query-Caching.

Methoden:

  • get_connection(): liefert eine Verbindung aus dem Pool.
  • get_session(): liefert MySQLSession(engine=self).

EngineFactory und engine_factory#

EngineFactory#

Ein Singleton, das Engine-Instanzen konfiguriert und vorhält.

Wichtige Methoden:

  • configure_factory(db_url, config=None, query_cache=False, name="default")
  • Erzeugt anhand von db_url eine Engine-Instanz und legt sie unter name ab.
  • Leitet die Engine-Klasse aus dem URL-Schema ab ("mysql", "postgresql").
  • configure_postgresql_factory(conf, section, name)
  • Hilfsmethode, um PostgreSQL aus einem Config-Objekt zu konfigurieren.
  • configure_mysql_factory(conf, section, name)
  • Hilfsmethode, um MySQL aus einem Config-Objekt zu konfigurieren.
  • get_engine(name="default")
  • Liefert die konfigurierte Engine-Instanz.
  • destroy_engine(name="default") / destroy_all_engines()
  • Entfernen Engines aus der Factory.

Auf Modulebene:

engine_factory = EngineFactory()

Die meisten Anwendungen verwenden dieses Singleton:

from restalchemy.storage.sql import engines

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

DBConnectionUrl#

DBConnectionUrl ist ein kleiner Helfer, der eine DB-URL parst und eine zensierte String-Darstellung liefert.

  • Speichert die geparste URL.
  • Die Property url liefert den vollständigen URL-String.
  • __repr__ verbirgt das Passwort und ersetzt es durch :<censored>@.

Das ist vor allem für Logging und Debugging nützlich.