ditto.yaml.example

# ditto.yaml — configuration for the ditto CLI
#
# Copy this file to ditto.yaml (or ~/.ditto/ditto.yaml) and fill in your values.
# Environment variables with the prefix DITTO_ override any field here:
#   DITTO_SOURCE_HOST=other.db.example.com

source:
  # Option A — database URL (engine, host, port, database, user, and password
  # are all inferred from the URL). Supported schemes: postgres, postgresql,
  # mysql, mariadb. Individual fields below override URL values if both are set.
  #
  # url: postgres://ditto_dump:secret@db.example.com:5432/myapp

  # Option B — individual fields.

  # Database engine. Supported: "postgres", "mysql"
  engine: postgres

  # Database host
  host: db.example.com
  port: 5432
  database: myapp

  # Dump user — SELECT privileges only.
  user: ditto_dump

  # One of password or password_secret must be set.
  # Use password for local development only — never commit real passwords.
  # password_secret accepts any of these formats:
  #   env:MY_SECRET_VAR                         — environment variable
  #   file:/run/secrets/db_password             — Docker secret or mounted file
  #   arn:aws:secretsmanager:us-east-1:...:...  — AWS Secrets Manager
  #
  # password: localdevpassword
  # password_secret: env:DB_PASSWORD
  password_secret: arn:aws:secretsmanager:us-east-1:123456789012:secret:ditto-rds-password

dump:
  # Cron schedule for automatic dumps. Default: hourly.
  schedule: "0 * * * *"

  # Local path where the compressed dump file is stored.
  # The scheduler writes to <path>.tmp then atomically renames to <path>.
  # Leave this unset to use ditto's built-in default. If you set it explicitly,
  # use an absolute path; "~" is not expanded inside YAML values.
  # Default for local use: your home directory's .ditto/latest.gz
  # Default in server context: /data/dump/latest.gz
  # path: /absolute/path/to/latest.gz

  # Warn (but don't error) if the dump file is older than this many seconds.
  # Default: 7200 (2 × the default hourly schedule).
  stale_threshold: 7200

  # Optional helper image used for dump operations.
  # Defaults to the engine's built-in image (postgres:16-alpine or mysql:8.4).
  # Override when the source server needs a different client version:
  #   client_image: "postgres:15-alpine"
  #   client_image: "mysql:5.7"
  # client_image: ""

  # Optional path for a schema-only (DDL) dump run alongside the full dump.
  # Contains CREATE TABLE / CREATE INDEX / etc. but no row data. Useful for:
  #   - Migration dry-runs: ditto copy run --dump /data/dump/schema.gz -- flyway migrate
  #   - ERD generation:     ditto erd --source
  #   - CI schema checks that don't need production data
  # Leave empty (default) to skip the schema-only dump.
  # schema_path: /data/dump/schema.gz

  # Optional list of tables to include in the dump schema but exclude from row data.
  # Useful for large audit logs, event streams, or analytics tables that inflate the
  # dump without adding development value. The table schema (CREATE TABLE) is preserved
  # so foreign keys and migrations still work correctly.
  # exclude_table_data:
  #   - audit_logs
  #   - raw_events

  # Alert when a scheduled dump fails. Either webhook_url or exec may be set;
  # webhook_url takes precedence. Both are optional.
  # on_failure:
  #   webhook_url: "https://hooks.slack.com/services/..."
  #   exec: "echo 'dump failed' | mail ops@example.com"

# Auto-destroy copies older than this many seconds.
# Individual copies can override this with --ttl on copy create.
copy_ttl_seconds: 7200

# Port range for copy containers. Each copy binds to one port on localhost.
# Ensure this range doesn't conflict with other services on the host.
port_pool_start: 5433
port_pool_end: 5600

# Optional Docker-compatible daemon host override.
# docker_host: "unix:///var/run/docker.sock"

# Docker image used for copy containers.
# Defaults to the engine's built-in image (postgres:16-alpine or mysql:8.4).
# Override to pin a specific version:
#   copy_image: "postgres:15-alpine"
#   copy_image: "mysql:5.7"
# copy_image: ""

# Pre-warm N copies so ditto copy create returns in <1s.
# 0 (default) disables the pool. A value of 2–3 covers most CI parallelism.
# warm_pool_size: 3

# Optional refresh targets for staging or QA databases.
# Target refresh is destructive: ditto cleans user objects inside the configured
# database and restores a dump into it. It does not create or modify RDS
# instances, snapshots, roles, or instance settings.
#
# targets:
#   staging:
#     engine: postgres
#     host: staging.example.com
#     port: 5432
#     database: myapp
#     user: ditto_refresh
#     password_secret: env:DITTO_TARGET_PASSWORD
#     allow_destructive_refresh: true

# PII obfuscation rules baked into the dump during `ditto reseed`.
# That keeps later copies scrubbed by default. `copy create --dump ... --obfuscate`
# and `copy run --dump ... --obfuscate` can also apply the same rules after restore.
#
# Strategies:
#   replace  — deterministic format-preserving substitution (recommended for most PII)
#              type: email | name | phone | ip | url | uuid
#   hash     — one-way SHA-256 hex; preserves uniqueness for JOINs
#   mask     — replace characters with a mask char (default '*'); keep_last preserves suffix
#   redact   — replace with '[redacted]' (or a custom string via with:)
#   nullify  — set to NULL
#
# obfuscation:
#   rules:
#     - table: users
#       column: email
#       strategy: replace
#       type: email           # user483921@example.com
#     - table: users
#       column: full_name
#       strategy: replace
#       type: name            # User74831
#     - table: users
#       column: phone
#       strategy: replace
#       type: phone           # +1-555-0147-3821 (NANP fictional range)
#     - table: users
#       column: ssn
#       strategy: nullify     # set to NULL
#     - table: users
#       column: notes
#       strategy: redact      # [redacted]
#     - table: users
#       column: api_key
#       strategy: hash        # 64-char SHA-256 hex
#     - table: users
#       column: account_uuid
#       strategy: replace
#       type: uuid            # same obfuscated value wherever the raw UUID repeats
#     - table: payment_methods
#       column: card_number
#       strategy: mask
#       keep_last: 4          # ************1234
#       mask_char: "*"
#     - table: payment_methods
#       column: billing_email
#       strategy: replace
#       type: email           # matches users.email for the same raw value
#     - table: audit_logs
#       column: ip_address
#       strategy: replace
#       type: ip              # 10.42.17.3 (RFC1918, never public)
#     - table: audit_logs
#       column: target_url
#       strategy: replace
#       type: url             # https://example.com/r/1a2b3c4d5e6f
#     - table: audit_logs
#       column: actor_uuid
#       strategy: replace
#       type: uuid            # matches users.account_uuid for the same raw value
#
# Optional zero-row exception when a table may be empty:
#     - table: archived_customers
#       column: email
#       strategy: redact
#       warn_only: true       # 0-row match emits a warning instead of failing the dump

# Shared-host settings (used by ditto host).
# server:
#   enabled: true
#   addr: ":8080"
#   advertise_host: ditto.internal      # DNS name reachable from CI runners
#   db_bind_host: 0.0.0.0
#   copy_secret_secret: env:DITTO_COPY_SECRET
#
#   # Authentication:
#   # - If static_token is set, ditto uses it and ignores the OIDC fields below.
#   # - For production, omit static_token and configure the full OIDC block.
#   auth:
#     # Option A — shared secret. All requests share one identity.
#     # Use for evaluation and single-operator setups only.
#     static_token: env:DITTO_STATIC_TOKEN
#
#     # Option B — OIDC bearer-token validation (recommended for production).
#     # issuer: https://issuer.example.com/
#     # audience: ditto-ci
#     # jwks_url: https://issuer.example.com/.well-known/jwks.json
#     # admin_claim: role
#     # admin_value: ditto-admin
#
#   db_tls:
#     # Required in current shared-host mode.
#     cert_file: /etc/ditto/tls/server.crt
#     key_file: /etc/ditto/tls/server.key