Skip to main content

Datasources

Datasources wrap a SQLAlchemy engine so that database transactions run inside DBOS workflows are tracked and replayed with exactly-once guarantees. See the Transactions & Datasources tutorial for a full walkthrough.

SQLAlchemyDatasource​

A synchronous datasource backed by a SQLAlchemy Engine. Use this for non-async code.

SQLAlchemyDatasource.create​

SQLAlchemyDatasource.create(
database_url: str,
engine_kwargs: Optional[Dict[str, Any]] = None,
engine: Optional[sa.Engine] = None,
schema: Optional[str] = None,
serializer: Optional[Serializer] = None,
sessionmaker: Optional[sessionmaker] = None,
run_migrations: bool = True,
) -> SQLAlchemyDatasource

Factory method. Creates (or reuses) a SQLAlchemy engine and creates or migrates the datasource's datasource_outputs tracking table, unless run_migrations is False.

Parameters:

  • database_url: A SQLAlchemy-compatible connection URL (e.g., "postgresql+psycopg://..." or "sqlite:///./my.db").
  • engine_kwargs: Optional keyword arguments forwarded verbatim to SQLAlchemy's create_engine.
  • engine: Provide an existing sa.Engine instead of creating one from database_url. When set, engine_kwargs is ignored.
  • schema: The PostgreSQL schema in which the datasource_outputs table is created. Defaults to "dbos". Has no effect for SQLite.
  • serializer: A custom serializer for transaction outputs. Defaults to the DBOS default serializer (pickle, then Base64-encoded), not the serializer set in DBOSConfig.
  • sessionmaker: A custom sqlalchemy.orm.sessionmaker used to create the session for each transaction, for example to use a custom Session subclass, session options, or event hooks. DBOS always binds sessions to the datasource's engine, so any bind you set is ignored, and a sessionmaker that sets binds raises a DBOSException. Defaults to sessionmaker(expire_on_commit=False).
  • run_migrations: Whether to create and migrate the datasource's tables. Defaults to True. Set to False if your application's database role cannot run DDL: the datasource then only verifies that its tables are migrated, raising a DBOSInitializationError if they are not. Migrate them separately with SQLAlchemyDatasource.migrate.

Example:

from dbos import SQLAlchemyDatasource

ds = SQLAlchemyDatasource.create(os.environ["APP_DATABASE_URL"])

SQLAlchemyDatasource.migrate​

SQLAlchemyDatasource.migrate(
database_url: str,
*,
schema: Optional[str] = None,
application_role: Optional[str] = None,
) -> None

Create or migrate a datasource's tables without creating a datasource. Run this with a privileged database role (for example, as part of your deployment's migration step), then create your datasources with run_migrations=False so your application's role needs no DDL privileges.

Parameters:

  • database_url: The connection URL of the datasource's database.
  • schema: The PostgreSQL schema holding the datasource's tables. Defaults to "dbos". Has no effect for SQLite.
  • application_role: A PostgreSQL role to grant the minimal permissions a datasource needs at runtime: usage on the schema, SELECT, INSERT, and DELETE on the datasource_outputs table, and SELECT on the migration version table. Not supported for SQLite.

Example:

from dbos import SQLAlchemyDatasource

# In your migration script, run with a privileged role:
SQLAlchemyDatasource.migrate(os.environ["ADMIN_DATABASE_URL"], application_role="my_app_role")

# In your application, run with my_app_role:
ds = SQLAlchemyDatasource.create(os.environ["APP_DATABASE_URL"], run_migrations=False)

SQLAlchemyDatasource.transaction​

ds.transaction(
func: Optional[Callable] = None,
*,
name: Optional[str] = None,
isolation_level: IsolationLevel = "SERIALIZABLE",
)

Decorator that registers a synchronous function as a datasource transaction step.

The decorated function must not be a coroutine (async def). Decorating an async def function raises DBOSException at decoration time.

Parameters:

  • name: Step name recorded in the workflow log. Defaults to the function's qualified name (__qualname__).
  • isolation_level: SQL transaction isolation level. Must be one of "SERIALIZABLE" (default), "REPEATABLE READ", or "READ COMMITTED". SQLite supports only "SERIALIZABLE".

Example:

@ds.transaction()
def insert_row(name: str, value: int) -> None:
session = ds.sql_session()
session.execute(text("INSERT INTO t VALUES (:n, :v)"), {"n": name, "v": value})

@ds.transaction(isolation_level="READ COMMITTED", name="read_row")
def get_row(name: str) -> Optional[int]:
session = ds.sql_session()