gemstone_utils.db

Process-global SQLAlchemy engine, session factory, and declarative base.

class gemstone_utils.db.GemstoneDB(**kwargs)

Bases: DeclarativeBase

Shared declarative base for gemstone_utils ORM models.

Subclass this base in plugin modules, import them before init_db, then call init_db to create any missing tables on GemstoneDB.metadata.

Parameters:

kwargs (Any)

metadata: ClassVar[MetaData] = MetaData()

Refers to the _schema.MetaData collection that will be used for new _schema.Table objects.

See also

Accessing Table and Metadata

registry: ClassVar[_RegistryType] = <sqlalchemy.orm.decl_api.registry object>

Refers to the _orm.registry in use where new _orm.Mapper objects will be associated.

gemstone_utils.db.get_session()

Return a new session bound to the engine from init_db().

Returns:

New Session. Close when done, or use as a context manager: with get_session() as session:.

Raises:

RuntimeError – If init_db() was not called.

Return type:

Session

gemstone_utils.db.init_db(db_url, *, echo=False, **engine_kw)

Configure the process-global engine and create missing tables.

Import every module that defines GemstoneDB subclasses before calling this function so their tables are registered on GemstoneDB.metadata.

Applies dialect-specific defaults (SQLite WAL; MySQL/MariaDB utf8mb4 and pool tuning; PostgreSQL UTC session timezone). Pass **engine_kw to override or extend sqlalchemy.create_engine() arguments.

Schema creation uses an advisory lock on PostgreSQL and MySQL/MariaDB so multiple workers can call init_db at startup without racing on CREATE TABLE.

Parameters:

• db_url (str) – SQLAlchemy database URL.

• echo (bool) – Log SQL when True.

• **engine_kw (Any) – Additional arguments for create_engine().

Returns:

The configured Engine.

Return type:

Engine