Skip to main content

Configuration

Configuring DBOS​

To configure DBOS, pass a DBOSConfig object to its constructor. For example:

config: DBOSConfig = {
    "name": "dbos-example",
    "database_url": os.environ["DBOS_DATABASE_URL"],
}
DBOS(config=config)

The DBOSConfig object has the following fields. All fields except name are optional.

class DBOSConfig(TypedDict):
    name: str
    database_url: Optional[str]
    sys_db_name: Optional[str]
    sys_db_pool_size: Optional[int]
    db_engine_kwargs: Optional[Dict[str, Any]]
    log_level: Optional[str]
    otlp_traces_endpoints: Optional[List[str]]
    otlp_logs_endpoints: Optional[List[str]]
    admin_port: Optional[int]
    run_admin_server: Optional[bool]
  • name: Your application's name.
  • database_url: A connection string to a Postgres database. DBOS uses this connection string, unmodified, to create a SQLAlchemy engine. A valid connection string looks like:
postgresql://[username]:[password]@[hostname]:[port]/[database name]
info

SQLAlchemy requires passwords in connection strings to be escaped if they contain special characters (e.g., with urllib).

If no connection string is provided, DBOS uses this default:

postgresql://postgres:dbos@localhost:5432/application_name?connect_timeout=10
  • db_engine_kwargs: Additional keyword arguments passed to SQLAlchemy’s create_engine(), applied to both the application and system database engines. Defaults to:
{
  "pool_size": 20,
  "max_overflow": 0,
  "pool_timeout": 30,
}
  • sys_db_pool_size: The size of the connection pool used for the DBOS system database. Defaults to 20.
  • sys_db_name: Name for the system database in which DBOS stores internal state. Defaults to {database name}_dbos_sys.
  • otlp_traces_endpoints: DBOS operations automatically generate OpenTelemetry Traces. Use this field to declare a list of OTLP-compatible trace receivers.
  • otlp_logs_endpoints: the DBOS logger can export OTLP-formatted log signals. Use this field to declare a list of OTLP-compatible log receivers.
  • log_level: Configure the DBOS logger severity. Defaults to INFO.
  • run_admin_server: Whether to run an HTTP admin server for workflow management operations. Defaults to True.
  • admin_port: The port on which the admin server runs. Defaults to 3001.

DBOS Configuration File​

Some tools in the DBOS ecosystem, including DBOS Cloud and the DBOS debugger, are configured by a dbos-config.yaml file.

You can create a dbos-config.yaml with default parameters with:

dbos init <app-name> --config

Configuration File Fields​

info

You can use environment variables for configuration values through the syntax field: ${VALUE}.

Each dbos-config.yaml file has the following fields and sections:

  • name: Your application's name. Must match the name supplied to the DBOS constructor.
  • language: The application language. Must be set to python for Python applications.
  • database_url: A connection string to a Postgres database. This connection string is used by tools such as the DBOS CLI and DBOS debugger. It has the same format as (and should match) the connection string you pass to the DBOS constructor.
  • database: The database section.
  • runtimeConfig: The runtime section.

Database Section​

  • migrate: A list of commands to run to apply your application's schema to the database.

Example:

database:
  sys_db_name: 'my_dbos_system_db'
  migrate:
    - alembic upgrade head

Runtime Section​

  • start: The command(s) with which to start your app. Called from dbos start, which is used to start your app in DBOS Cloud.
  • setup: Setup commands to run before your application is built in DBOS Cloud. Used only in DBOS Cloud. Documentation here.

Example:

runtimeConfig:
  start:
    - "fastapi run"

Configuration Schema File​

There is a schema file available for the DBOS configuration file schema on GitHub. This schema file can be used to provide an improved YAML editing experience for developer tools that leverage it. For example, the Visual Studio Code RedHat YAML extension provides tooltips, statement completion and real-time validation for editing DBOS config files. This extension provides multiple ways to associate a YAML file with its schema. The easiest is to simply add a comment with a link to the schema at the top of the config file:

# yaml-language-server: $schema=https://github.com/dbos-inc/dbos-transact-py/blob/main/dbos/dbos-config.schema.json