prefect.server.database.configurations

Classes

ConnectionTracker ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A test utility which tracks the connections given out by a connection pool, to make it easy to see which connections are currently checked out and open.

Methods:

clear ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L109" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

clear(self) -> None

on_close ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

on_close(self, adapted_connection: AdaptedConnection, connection_record: ConnectionPoolEntry) -> None

on_close_detached ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

on_close_detached(self, adapted_connection: AdaptedConnection) -> None

on_connect ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L79" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

on_connect(self, adapted_connection: AdaptedConnection, connection_record: ConnectionPoolEntry) -> None

track_pool ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L74" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

track_pool(self, pool: sa.pool.Pool) -> None

BaseDatabaseConfiguration ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L120" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Abstract base class used to inject database connection configuration into Prefect.

This configuration is responsible for defining how Prefect REST API creates and manages database connections and sessions.

Methods:

begin_transaction ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]

Enter a transaction for a session

create_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Create the database

drop_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Drop the database

engine ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

engine(self) -> AsyncEngine

Returns a SqlAlchemy engine

is_inmemory ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_inmemory(self) -> bool

Returns true if database is run in memory

session ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

session(self, engine: AsyncEngine) -> AsyncSession

Retrieves a SQLAlchemy session for an engine.

unique_key ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

unique_key(self) -> tuple[Hashable, ...]

Returns a key used to determine whether to instantiate a new DB interface.

AsyncPostgresConfiguration ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Methods:

begin_transaction ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L392" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AsyncGenerator[AsyncSessionTransaction, None]

begin_transaction ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]

Enter a transaction for a session

create_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L400" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Create the database

create_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Create the database

drop_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L407" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Drop the database

drop_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Drop the database

engine ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

engine(self) -> AsyncEngine

Retrieves an async SQLAlchemy engine.

Args:

• connection_url: The database connection string. Defaults to self.connection_url
• echo: Whether to echo SQL sent to the database. Defaults to self.echo
• timeout: The database statement timeout, in seconds. Defaults to self.timeout

Returns:

• a SQLAlchemy engine

engine ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

engine(self) -> AsyncEngine

Returns a SqlAlchemy engine

is_inmemory ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L414" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_inmemory(self) -> bool

Returns true if database is run in memory

is_inmemory ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_inmemory(self) -> bool

Returns true if database is run in memory

schedule_engine_disposal ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

schedule_engine_disposal(self, cache_key: _EngineCacheKey) -> None

Dispose of an engine once the event loop is closing.

See caveats at add_event_loop_shutdown_callback.

We attempted to lazily clean up old engines when new engines are created, but if the loop the engine is attached to is already closed then the connections cannot be cleaned up properly and warnings are displayed.

Engine disposal should only be important when running the application ephemerally. Notably, this is an issue in our tests where many short-lived event loops and engines are created which can consume all of the available database connection slots. Users operating at a scale where connection limits are encountered should be encouraged to use a standalone server.

session ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L382" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

session(self, engine: AsyncEngine) -> AsyncSession

Retrieves a SQLAlchemy session for an engine.

Args:

• engine: a sqlalchemy engine

session ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

session(self, engine: AsyncEngine) -> AsyncSession

Retrieves a SQLAlchemy session for an engine.

unique_key ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

unique_key(self) -> tuple[Hashable, ...]

Returns a key used to determine whether to instantiate a new DB interface.

AioSqliteConfiguration ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L420" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Methods:

begin_sqlite_conn ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L564" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_sqlite_conn(self, conn: aiosqlite.AsyncAdapt_aiosqlite_connection) -> None

begin_sqlite_stmt ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L573" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_sqlite_stmt(self, conn: sa.Connection) -> None

begin_transaction ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L586" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AsyncGenerator[AsyncSessionTransaction, None]

begin_transaction ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L205" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

begin_transaction(self, session: AsyncSession, with_for_update: bool = False) -> AbstractAsyncContextManager[AsyncSessionTransaction]

Enter a transaction for a session

create_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L606" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Create the database

create_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

create_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Create the database

drop_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L613" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Drop the database

drop_db ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L195" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

drop_db(self, connection: AsyncConnection, base_metadata: sa.MetaData) -> None

Drop the database

engine ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L423" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

engine(self) -> AsyncEngine

Retrieves an async SQLAlchemy engine.

Args:

• connection_url: The database connection string. Defaults to self.connection_url
• echo: Whether to echo SQL sent to the database. Defaults to self.echo
• timeout: The database statement timeout, in seconds. Defaults to self.timeout

Returns:

• a SQLAlchemy engine

engine ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L179" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

engine(self) -> AsyncEngine

Returns a SqlAlchemy engine

is_inmemory ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L620" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_inmemory(self) -> bool

Returns true if database is run in memory

is_inmemory ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L201" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

is_inmemory(self) -> bool

Returns true if database is run in memory

schedule_engine_disposal ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L489" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

schedule_engine_disposal(self, cache_key: _EngineCacheKey) -> None

Dispose of an engine once the event loop is closing.

See caveats at add_event_loop_shutdown_callback.

We attempted to lazily clean up old engines when new engines are created, but if the loop the engine is attached to is already closed then the connections cannot be cleaned up properly and warnings are displayed.

Engine disposal should only be important when running the application ephemerally. Notably, this is an issue in our tests where many short-lived event loops and engines are created which can consume all of the available database connection slots. Users operating at a scale where connection limits are encountered should be encouraged to use a standalone server.

session ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L597" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

session(self, engine: AsyncEngine) -> AsyncSession

Retrieves a SQLAlchemy session for an engine.

Args:

• engine: a sqlalchemy engine

session ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L183" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

session(self, engine: AsyncEngine) -> AsyncSession

Retrieves a SQLAlchemy session for an engine.

setup_sqlite ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L513" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

setup_sqlite(self, conn: DBAPIConnection, record: ConnectionPoolEntry) -> None

Issue PRAGMA statements to SQLITE on connect. PRAGMAs only last for the duration of the connection. See https://www.sqlite.org/pragma.html for more info.

unique_key ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/server/database/configurations.py#L172" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

unique_key(self) -> tuple[Hashable, ...]

Returns a key used to determine whether to instantiate a new DB interface.