Installation

This guide covers installing DBOS Transact and setting up your development environment.

Requirements

DBOS Transact requires:

Python 3.10 or later (Python 3.10, 3.11, 3.12, and 3.13 are supported)
Postgres 14+ or SQLite 3.35+ for the system database
pip for package installation

Installing DBOS

Install the Package

Install DBOS using pip:

pip install dbos

This installs the core DBOS library with all required dependencies:

pyyaml - Configuration file parsing
python-dateutil - Date and time utilities
psycopg[binary] - PostgreSQL adapter
websockets - WebSocket support
sqlalchemy - Database ORM and query builder

DBOS is compatible with SQLAlchemy 2.0+. If you have an older version, it will be upgraded.

Verify Installation

Verify DBOS is installed correctly:

python -c "import dbos; print(f'DBOS version: {dbos.__name__}')"

You can also check the DBOS CLI is available:

dbos --help

This should display the available DBOS commands.

Optional Dependencies

DBOS provides optional dependencies for additional features:

OpenTelemetry (OTLP)

For distributed tracing and logging with OpenTelemetry:

pip install dbos[otel]

This installs:

opentelemetry-api
opentelemetry-sdk
opentelemetry-exporter-otlp-proto-http

Validation

For request/response validation with Pydantic:

pip install dbos[validation]

This installs:

pydantic (version 2.0+)

All Optional Dependencies

To install all optional dependencies:

pip install dbos[otel,validation]

Database Setup

DBOS stores workflow state in a system database. You can use either Postgres or SQLite.

Option 1: SQLite (Development)

SQLite is perfect for local development and testing. No setup required—DBOS creates the database file automatically.

name: my-app
system_database_url: sqlite:///dbos.db

SQLite is not recommended for production use. Use Postgres for production deployments to ensure better performance, reliability, and concurrent access support.

Option 2: Postgres (Production)

Postgres is recommended for production use. It provides better performance, reliability, and supports advanced features.

Docker
Local Installation
Cloud Providers

Start a Postgres database with Docker:

export PGPASSWORD=dbos
docker run --name dbos-postgres \
  -e POSTGRES_PASSWORD=$PGPASSWORD \
  -p 5432:5432 \
  -d postgres:16

The database will be available at localhost:5432.

Install Postgres using your system’s package manager:

brew install postgresql@16
brew services start postgresql@16

Configuration

DBOS uses a configuration file or Python dictionary to specify database connections and other settings.

Configuration File

Create a file named dbos-config.yaml in your project root:

name: my-app
system_database_url: postgresql://postgres:dbos@localhost:5432/dbos_sys

Then initialize DBOS in your code:

from dbos import DBOS

# Load configuration from dbos-config.yaml
dbos = DBOS()

Python Configuration

Alternatively, configure DBOS directly in Python:

from dbos import DBOS, DBOSConfig

config: DBOSConfig = {
    "name": "my-app",
    "system_database_url": "postgresql://postgres:dbos@localhost:5432/dbos_sys",
    "application_database_url": "postgresql://postgres:dbos@localhost:5432/my_app",
    "log_level": "INFO",
}

dbos = DBOS(config=config)

Configuration Options

Key configuration options:

Option	Type	Description
`name`	`str`	Required. Application name
`system_database_url`	`str`	Connection string for DBOS system database. Defaults to `sqlite:///{name}`
`application_database_url`	`str`	Connection string for application database (used in `@DBOS.transaction()`)
`log_level`	`str`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Default: `INFO`
`admin_port`	`int`	Port for admin server. Default: `8080`
`run_admin_server`	`bool`	Whether to run the admin server. Default: `true`
`enable_otlp`	`bool`	Enable OpenTelemetry tracing/logging. Default: `false`
`max_executor_threads`	`int`	Maximum worker threads for executing steps. Default: `100`
`sys_db_pool_size`	`int`	System database connection pool size
`dbos_system_schema`	`str`	Schema name for DBOS system tables. Default: `dbos`

Environment variables in the format DBOS__OPTION_NAME override configuration file values. For example, DBOS__NAME=my-app overrides the name field.

Database Migrations

DBOS automatically creates system tables in your system database on first launch. If you’re using an application database for transactions, you’ll need to manage your application schema separately.

Running Migrations

DBOS provides a migration command to set up or update your database schema:

dbos migrate

This creates or updates the DBOS system tables in your system database.

Application Schema

For your application database, define your schema using SQLAlchemy:

from sqlalchemy import Column, Integer, String, Table, MetaData

metadata = MetaData()

users = Table(
    "users",
    metadata,
    Column("id", Integer, primary_key=True, autoincrement=True),
    Column("name", String, nullable=False),
    Column("email", String, nullable=False),
)

Then create the tables:

from dbos import DBOS

dbos = DBOS()
DBOS.launch()

# Create application tables
if DBOS.app_db_engine is not None:
    metadata.create_all(DBOS.app_db_engine)

Or use migration tools like Alembic for more complex schema management.

Verifying Your Setup

Create a simple test to verify everything is working:

test_setup.py

from dbos import DBOS

# Initialize DBOS
dbos = DBOS()

@DBOS.step()
def test_step():
    return "DBOS is working!"

@DBOS.workflow()
def test_workflow():
    result = test_step()
    print(result)
    return result

if __name__ == "__main__":
    DBOS.launch()
    test_workflow()
    DBOS.destroy()
    print("Setup verified successfully!")

Run the test:

python test_setup.py

If you see “DBOS is working!” and “Setup verified successfully!”, your installation is complete!

Next Steps

Quickstart

Build your first durable workflow

Core Concepts

Learn about workflows, steps, and transactions

Workflow Tutorial

Explore advanced features and patterns

Configuration Reference

Complete configuration options reference

Troubleshooting

Import errors after installation

If you get import errors, ensure you’re using the correct Python environment:

which python
pip list | grep dbos

If DBOS isn’t listed, reinstall it:

pip install --upgrade dbos

Postgres connection refused

If you can’t connect to Postgres:

Verify Postgres is running:

# Docker
docker ps | grep postgres

# Local installation
pg_isready

Check your connection string format:

postgresql://username:password@host:port/database

Ensure the database exists or DBOS has permission to create it

SQLite permission errors

If you get permission errors with SQLite:

Ensure the directory exists and is writable

Use an absolute path in your configuration:

system_database_url: sqlite:////absolute/path/to/dbos.db

Version conflicts with SQLAlchemy

DBOS requires SQLAlchemy 2.0+. If you have conflicts:

pip install --upgrade sqlalchemy

If you need to keep an older version for another project, use a virtual environment:

python -m venv dbos-env
source dbos-env/bin/activate  # On Windows: dbos-env\Scripts\activate
pip install dbos

Get Started

Core Concepts

Guides

Integrations

Installation

Installation

Requirements

Installing DBOS

Optional Dependencies

OpenTelemetry (OTLP)

Validation

All Optional Dependencies

Database Setup

Option 1: SQLite (Development)

Option 2: Postgres (Production)

Configuration

Configuration File

Python Configuration

Configuration Options

Database Migrations

Running Migrations

Application Schema

Verifying Your Setup

Next Steps

Quickstart

Core Concepts

Workflow Tutorial

Configuration Reference

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

​Installation

​Requirements

​Installing DBOS

​Optional Dependencies

​OpenTelemetry (OTLP)

​Validation

​All Optional Dependencies

​Database Setup

​Option 1: SQLite (Development)

​Option 2: Postgres (Production)

​Configuration

​Configuration File

​Python Configuration

​Configuration Options

​Database Migrations

​Running Migrations

​Application Schema

​Verifying Your Setup

​Next Steps

Quickstart

Core Concepts

Workflow Tutorial

Configuration Reference

​Troubleshooting

Build docs developers (and LLMs) love

Installation

Requirements

Installing DBOS

Optional Dependencies

OpenTelemetry (OTLP)

Validation

All Optional Dependencies

Database Setup

Option 1: SQLite (Development)

Option 2: Postgres (Production)

Configuration

Configuration File

Python Configuration

Configuration Options

Database Migrations

Running Migrations

Application Schema

Verifying Your Setup

Next Steps

Troubleshooting