Data Connections¶

This guide helps you quickly enable conversation history storage with a backend that matches your environment.

Choose a Backend¶

SMG supports these history backends via --history-backend:

• memory (default): in-process, non-persistent
• none: disable history storage
• postgres: durable relational storage
• redis: fast key-value storage with optional retention
• oracle: enterprise Oracle backend

Quick Start Commands¶

Memory (default)¶

smg \
  --worker-urls http://worker:8000 \
  --history-backend memory

No history¶

smg \
  --worker-urls http://worker:8000 \
  --history-backend none

PostgreSQL¶

smg \
  --worker-urls http://worker:8000 \
  --history-backend postgres \
  --postgres-db-url "postgres://user:password@localhost:5432/smg" \
  --postgres-pool-max-size 16

On a new database, also set DB_AUTO_MIGRATE=true for the first start; see Schema migrations.

Redis¶

smg \
  --worker-urls http://worker:8000 \
  --history-backend redis \
  --redis-url "redis://localhost:6379" \
  --redis-pool-max-size 16 \
  --redis-retention-days 30

Set --redis-retention-days=-1 for persistent retention. Keep the =: the Rust CLI rejects -1 as a separate argument.

Oracle¶

smg \
  --worker-urls http://worker:8000 \
  --history-backend oracle \
  --oracle-wallet-path /path/to/wallet \
  --oracle-tns-alias mydb_high \
  --oracle-user admin \
  --oracle-password "$ORACLE_PASSWORD"

Schema migrations¶

PostgreSQL and Oracle track a schema version and refuse to start while migrations are pending, printing the SQL to apply by hand. A new database has pending migrations, so set DB_AUTO_MIGRATE=true (or 1) to let SMG apply them at startup:

DB_AUTO_MIGRATE=true smg launch \
  --worker-urls http://worker:8000 \
  --history-backend postgres \
  --postgres-db-url "postgres://user:password@localhost:5432/smg"

A --schema-config file can set auto_migrate instead. See Chat History.

Required Flags by Backend¶

Environment Variables¶

You can provide Oracle credentials via environment variables (both the Rust binary and the Python launcher read them):

• ATP_WALLET_PATH
• ATP_TNS_ALIAS
• ATP_DSN
• ATP_USER
• ATP_PASSWORD
• ATP_EXTERNAL_AUTH
• ATP_POOL_MIN
• ATP_POOL_MAX
• ATP_POOL_TIMEOUT_SECS

The Rust smg binary reads no environment variables for PostgreSQL or Redis. Only the Python launcher reads POSTGRES_DB_URL, POSTGRES_POOL_MAX, REDIS_URL, REDIS_POOL_MAX, and REDIS_RETENTION_DAYS, as defaults for its flags.

Verify¶

curl http://localhost:30000/health

If startup fails, SMG returns a config validation error (for example missing DB URL or Oracle credentials). PostgreSQL and Oracle also connect at startup to create tables and check migrations, so an unreachable database or pending migrations stop startup. Redis connects on first use, so a Redis problem shows up on the first request that stores or reads history.

Next Steps¶

• Chat History Concepts — backend architecture and tradeoffs
• Configuration Reference — full storage flag reference