DBOSConfig

Overview

DBOS Transact is configured using a DBOSConfig dictionary or a dbos-config.yaml file. This page documents all available configuration options.

Configuration File

The default configuration file is dbos-config.yaml in your project root. DBOS automatically loads this file when you call DBOS.launch() or use the CLI.

Basic Example

dbos-config.yaml

name: my-app
system_database_url: postgresql://user:password@localhost:5432/myapp_dbos
application_database_url: postgresql://user:password@localhost:5432/myapp

runtimeConfig:
  start:
    - uvicorn main:app --host 0.0.0.0 --port 8000
  admin_port: 3001

telemetry:
  logs:
    logLevel: INFO

DBOSConfig Class

The DBOSConfig TypedDict class defines all available configuration options. You can pass this directly to DBOS() or use a YAML file.

name

str

required

Application name. Must be 3-30 characters, lowercase letters, numbers, dashes, and underscores only.

Database Configuration

system_database_url

str

Connection string for the DBOS system database. Defaults to sqlite:///{name}.sqlite if not provided.Format:

SQLite: sqlite:///path/to/database.sqlite
PostgreSQL: postgresql://user:password@host:port/database

application_database_url

str

Connection string for your application database where @Transaction functions run. Optional.Must be the same database type (SQLite or Postgres) as the system database.

database_url

str

deprecated

Deprecated. Use application_database_url instead.

sys_db_pool_size

int

default:"20"

Connection pool size for the system database.

db_engine_kwargs

Dict[str, Any]

SQLAlchemy engine keyword arguments for database connections.See SQLAlchemy create_engine documentation.Default values:

{
    "pool_timeout": 30,
    "max_overflow": 0,
    "pool_size": 20,
    "pool_pre_ping": True,
    "connect_args": {
        "application_name": "dbos_transact",
        "connect_timeout": 10
    }
}

dbos_system_schema

str

default:"dbos"

Schema name for DBOS system tables.

system_database_engine

sa.Engine

A custom system database engine. If provided, DBOS will use this instead of creating its own.

Runtime Configuration

admin_port

int

default:"3001"

Port for the DBOS admin server.

run_admin_server

bool

default:"true"

Whether to run the DBOS admin server.

max_executor_threads

int

Maximum number of executor threads for running workflows and steps.

notification_listener_polling_interval_sec

float

default:"1.0"

Polling interval in seconds for the notification listener background process.Minimum value: 0.001. Lower values can speed up test execution.

scheduler_polling_interval_sec

float

default:"30.0"

Polling interval in seconds for the scheduler thread to detect new workflow schedules.

Telemetry & Logging

log_level

str

default:"INFO"

Global log level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.

console_log_level

str

Log level specifically for console logging. Must be no less severe than log_level.

otlp_log_level

str

Log level specifically for OTLP logging (if enabled). Must be no less severe than log_level.

enable_otlp

bool

default:"false"

Enable built-in DBOS OTLP tracing and logging.

otlp_traces_endpoints

List[str]

OTLP traces endpoints for exporting telemetry data.

otlp_logs_endpoints

List[str]

OTLP logs endpoints for exporting log data.

otlp_attributes

dict[str, str]

Custom attributes to apply to OTLP-exported logs and traces.

Advanced Configuration

application_version

str

Application version identifier.

executor_id

str

Executor ID, used to identify the application instance in distributed environments.

serializer

Serializer

A custom serializer and deserializer DBOS uses when storing program data in the system database.See the Serialization API for details.

use_listen_notify

bool

default:"true"

Whether to use PostgreSQL LISTEN/NOTIFY or polling for notifications and events.

This affects migrations and cannot be changed after the system database is first created.

conductor_key

str

An API key for DBOS Conductor. Pass this to connect your process to Conductor.

conductor_url

str

The websockets URL for your DBOS Conductor service. Only set if you’re self-hosting Conductor.

Configuration File Schema

The YAML configuration file is parsed into a ConfigFile TypedDict with the following structure:

YAML File Structure

name: string

system_database_url: string
application_database_url: string  # or database_url (deprecated)

runtimeConfig:
  start:
    - command1
    - command2
  setup:  # Optional setup commands
    - setup_command
  admin_port: 3001
  run_admin_server: true
  max_executor_threads: 10
  notification_listener_polling_interval_sec: 1.0
  scheduler_polling_interval_sec: 30.0

database:
  sys_db_pool_size: 20
  db_engine_kwargs:
    pool_size: 20
    pool_timeout: 30
  migrate:
    - alembic upgrade head

telemetry:
  logs:
    logLevel: INFO
    consoleLogLevel: DEBUG
    otlpLogLevel: INFO
  OTLPExporter:
    tracesEndpoint:
      - https://otel-collector:4318/v1/traces
    logsEndpoint:
      - https://otel-collector:4318/v1/logs
  otlp_attributes:
    environment: production
    service: my-service
  disable_otlp: false

dbos_system_schema: dbos
use_listen_notify: true

env:
  MY_VAR: value

Environment Variable Substitution

You can use environment variables in your configuration file with ${VAR_NAME} syntax:

system_database_url: ${DATABASE_URL}
application_database_url: ${APP_DATABASE_URL}

Docker Secrets

For Docker secrets, use ${DOCKER_SECRET:SECRET_NAME} syntax:

system_database_url: postgresql://user:${DOCKER_SECRET:db_password}@localhost/myapp

Secrets are read from /run/secrets/SECRET_NAME.

Database URL Format

SQLite

system_database_url = "sqlite:///path/to/database.sqlite"
# Or relative path
system_database_url = "sqlite:///./myapp.sqlite"

PostgreSQL

system_database_url = "postgresql://username:password@hostname:port/database_name"

# With query parameters
system_database_url = "postgresql://user:pass@host:5432/db?connect_timeout=10"

Required fields:

database: Database name must be specified

Common query parameters:

connect_timeout: Connection timeout in seconds (default: 10)
sslmode: SSL mode (e.g., require, disable)
application_name: Application name visible in pg_stat_activity

Loading Configuration

DBOS provides several ways to load configuration:

From File

from dbos import DBOS

# Loads dbos-config.yaml by default
dbos = DBOS.launch()

From DBOSConfig Dict

from dbos import DBOS, DBOSConfig

config: DBOSConfig = {
    "name": "my-app",
    "system_database_url": "postgresql://localhost/myapp_dbos",
    "log_level": "DEBUG",
}

dbos = DBOS(config=config)

Programmatic Loading

from dbos import load_config

config = load_config("path/to/config.yaml")
print(config["name"])

Validation

DBOS validates your configuration on startup:

Application name: Must be 3-30 characters, lowercase letters, numbers, dashes, and underscores only
Database URLs: Must include required fields (database name for PostgreSQL)
Log levels: Must be valid Python logging levels
Intervals: Must meet minimum value requirements

Invalid configuration raises DBOSInitializationError at startup.

Configuration in YAML File

In the YAML file, configuration is organized into sections:

runtimeConfig Section

runtimeConfig:
  start:
    - python -m uvicorn app:app
  setup:
    - python setup.py
  admin_port: 3001

runtimeConfig.start

List[str]

required

Commands to start your application. Used by dbos start.

runtimeConfig.setup

List[str]

Optional setup commands run before starting.

database Section

database:
  sys_db_pool_size: 20
  db_engine_kwargs:
    pool_size: 20
  migrate:
    - alembic upgrade head

database.migrate

List[str]

Migration commands to run with dbos migrate. Executed after DBOS system migrations.

telemetry Section

telemetry:
  logs:
    logLevel: INFO
  OTLPExporter:
    tracesEndpoint:
      - https://collector:4318/v1/traces
  disable_otlp: false

telemetry.disable_otlp

bool

default:"true"

Disable OTLP export. Set to false to enable.

Examples

Minimal SQLite Configuration

name: simple-app

runtimeConfig:
  start:
    - python main.py

This uses the default SQLite database: simple_app.sqlite

Production PostgreSQL Configuration

name: production-app

system_database_url: postgresql://dbos_user:${DB_PASSWORD}@db.example.com:5432/prod_dbos
application_database_url: postgresql://app_user:${DB_PASSWORD}@db.example.com:5432/prod_app

runtimeConfig:
  start:
    - gunicorn -w 4 app:app
  admin_port: 3001
  max_executor_threads: 20

database:
  sys_db_pool_size: 50
  db_engine_kwargs:
    pool_size: 50
    pool_timeout: 30
    max_overflow: 10
  migrate:
    - alembic upgrade head

telemetry:
  logs:
    logLevel: INFO
    consoleLogLevel: WARNING
  OTLPExporter:
    tracesEndpoint:
      - https://otel.example.com:4318/v1/traces
    logsEndpoint:
      - https://otel.example.com:4318/v1/logs
  disable_otlp: false
  otlp_attributes:
    environment: production
    region: us-east-1

dbos_system_schema: dbos
use_listen_notify: true

Development Configuration with Custom Serializer

from dbos import DBOS, DBOSConfig, Serializer

class CustomSerializer(Serializer):
    def serialize(self, data: Any) -> str:
        # Custom serialization logic
        return json.dumps(data)
    
    def deserialize(self, serialized_data: str) -> Any:
        # Custom deserialization logic
        return json.loads(serialized_data)
    
    def name(self) -> str:
        return "custom_json"

config: DBOSConfig = {
    "name": "dev-app",
    "system_database_url": "sqlite:///dev.sqlite",
    "log_level": "DEBUG",
    "serializer": CustomSerializer(),
}

dbos = DBOS(config=config)

Core API

Configuration

CLI

Overview

Configuration File

Basic Example

DBOSConfig Class

Database Configuration

Runtime Configuration

Telemetry & Logging

Advanced Configuration

Configuration File Schema

YAML File Structure

Environment Variable Substitution

Docker Secrets

Database URL Format

SQLite

PostgreSQL

Loading Configuration

From File

From DBOSConfig Dict

Programmatic Loading

Validation

Configuration in YAML File

runtimeConfig Section

database Section

telemetry Section

Examples

Minimal SQLite Configuration

Production PostgreSQL Configuration

Development Configuration with Custom Serializer

See Also

Build docs developers (and LLMs) love

Core API

Configuration

CLI

​Overview

​Configuration File

​Basic Example

​DBOSConfig Class

​Database Configuration

​Runtime Configuration

​Telemetry & Logging

​Advanced Configuration

​Configuration File Schema

​YAML File Structure

​Environment Variable Substitution

​Docker Secrets

​Database URL Format

​SQLite

​PostgreSQL

​Loading Configuration

​From File

​From DBOSConfig Dict

​Programmatic Loading

​Validation

​Configuration in YAML File

​runtimeConfig Section

​database Section

​telemetry Section

​Examples

​Minimal SQLite Configuration

​Production PostgreSQL Configuration

​Development Configuration with Custom Serializer

​See Also

Build docs developers (and LLMs) love

Overview

Configuration File

Basic Example

DBOSConfig Class

Database Configuration

Runtime Configuration

Telemetry & Logging

Advanced Configuration

Configuration File Schema

YAML File Structure

Environment Variable Substitution

Docker Secrets

Database URL Format

SQLite

PostgreSQL

Loading Configuration

From File

From DBOSConfig Dict

Programmatic Loading

Validation

Configuration in YAML File

runtimeConfig Section

database Section

telemetry Section

Examples

Minimal SQLite Configuration

Production PostgreSQL Configuration

Development Configuration with Custom Serializer

See Also