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'screate_engine.engine: Provide an existingsa.Engineinstead of creating one fromdatabase_url. When set,engine_kwargsis ignored.schema: The PostgreSQL schema in which thedatasource_outputstable 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 theserializerset inDBOSConfig.sessionmaker: A customsqlalchemy.orm.sessionmakerused to create the session for each transaction, for example to use a customSessionsubclass, session options, or event hooks. DBOS always binds sessions to the datasource's engine, so anybindyou set is ignored, and a sessionmaker that setsbindsraises aDBOSException. Defaults tosessionmaker(expire_on_commit=False).run_migrations: Whether to create and migrate the datasource's tables. Defaults toTrue. Set toFalseif your application's database role cannot run DDL: the datasource then only verifies that its tables are migrated, raising aDBOSInitializationErrorif they are not. Migrate them separately withSQLAlchemyDatasource.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, andDELETEon thedatasource_outputstable, andSELECTon 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()