duckgres.example.yaml

# Duckgres Configuration
# Copy this file to duckgres.yaml and customize as needed

# Server binding
host: "0.0.0.0"
port: 5432

# Control-plane Arrow Flight SQL ingress (optional)
# 0 or omitted disables Flight ingress.
# flight_port: 8815
# flight_session_idle_ttl: "10m"
# flight_session_reap_interval: "1m"
# flight_handle_idle_ttl: "15m"
# flight_session_token_ttl: "1h"

# Directory for DuckDB database files (one per user)
data_dir: "./data"

# TLS configuration (required)
tls:
  cert: "./certs/server.crt"
  key: "./certs/server.key"

# User credentials (username: password)
users:
  postgres: "postgres"
  alice: "alice123"
  bob: "bob123"

# Passthrough users bypass all PostgreSQL compatibility (no transpiler, no pg_catalog).
# Queries are sent directly to DuckDB. Users listed here must also exist in 'users' above.
# passthrough_users:
#   - alice

# DuckDB extensions to load on database initialization
# Extensions are installed (downloaded if needed) and loaded automatically
# Common extensions: httpfs, parquet, json, sqlite, postgres, mysql, excel
# Default: ducklake (loaded even without config file)
extensions:
  - ducklake
  # - "cache_httpfs FROM community"  # Caches S3/HTTP requests locally (requires internet)
  # - parquet

# DuckLake configuration (optional)
# When configured, DuckLake catalog is automatically attached on connection
# See: https://ducklake.select/docs/stable/duckdb/usage/connecting
ducklake:
  # Full connection string for the DuckLake metadata database
  # Examples:
  #   - "postgres:host=localhost user=ducklake password=secret dbname=ducklake"
  #   - "postgres:host=ducklake.example.com user=ducklake password=secret dbname=ducklake"
  # WARNING: Do not use pgbouncer (port 6432) for the metadata store connection.
  # pgbouncer's connection lifecycle management can kill connections that DuckLake
  # depends on, causing cascading failures. Connect directly to PostgreSQL instead.
  # metadata_store: "postgres:host=localhost user=ducklake password=secret dbname=ducklake"

  # Disable postgres_scanner thread-local metadata connection caching before
  # ATTACH creates the hidden DuckLake metadata pool. This is enabled by
  # default to reduce retained metadata connections. Set false to opt back
  # into thread-local warm reuse.
  # disable_metadata_thread_local_cache: false

  # S3-compatible object storage for data files (optional)
  # If not specified, data is stored alongside the metadata
  # object_store: "s3://bucket/path/"

  # S3 credential provider: "config" (explicit) or "credential_chain" (AWS SDK)
  # Default: "config" if s3_access_key is set, otherwise "credential_chain"
  # s3_provider: "config"

  # Option 1: Explicit credentials (for MinIO or when you have access keys)
  # s3_endpoint: "localhost:9000"      # MinIO or custom S3 endpoint
  # s3_access_key: "minioadmin"        # Access key ID
  # s3_secret_key: "minioadmin"        # Secret access key
  # s3_region: "us-east-1"             # AWS region (default: us-east-1)
  # s3_use_ssl: false                  # Use HTTPS for S3 connections
  # s3_url_style: "path"               # "path" or "vhost" (default: path)

  # Option 2: AWS credential chain (for AWS S3 with IAM roles, env vars, etc.)
  # Uses AWS SDK credential chain: env vars -> config files -> instance metadata
  # See: https://duckdb.org/docs/stable/core_extensions/httpfs/s3api#credential_chain-provider
  # s3_provider: "credential_chain"
  # s3_chain: "env;config"             # Which sources to check (env, config, sts, sso, instance, process)
  # s3_profile: "my-profile"           # AWS profile name (for config chain)
  # s3_region: "us-west-2"             # Override auto-detected region

# DuckDB resource limits per session (standalone mode)
# Auto-detected from system memory if not set.
# memory_limit: "4GB"
# threads: 4

# Dynamic memory allocation (control-plane mode only)
# Total memory budget shared across all DuckDB sessions.
# Each session gets budget / active_sessions (floor: 256MB).
# Default: 75% of system RAM.
# memory_budget: "24GB"

# Worker process limits (control-plane mode only)
# process:
#   # min_workers: pre-warm process workers at startup for instant connection handling.
#   # max_workers: cap on total process workers (0 = auto-derived).
#   # retire_on_session_end: retire a process worker immediately after its last
#   # session ends instead of keeping it warm for reuse.
#   min_workers: 0
#   max_workers: 0
#   retire_on_session_end: false

# Kubernetes multi-tenant shared warm-pool settings
# k8s:
#   # Global cap for shared K8s workers. 0 auto-derives from memory_budget.
#   max_workers: 0
#   # Neutral shared warm-worker target. Separate from per-org limits and
#   # process.min_workers. 0 disables shared prewarming. When > 0, the pool
#   # maintains this many idle workers and activates them on-demand per org.
#   shared_warm_target: 0

# Process isolation (default: true)
# Each client connection spawns a separate OS process, so a DuckDB crash
# (e.g., from a failed DuckLake metadata connection) only kills that session,
# not the entire server. Set to false only for debugging or low-resource environments.
process_isolation: true

# Connection idle timeout (optional)
# Connections with no activity for this duration will be closed.
# Default: 24h (24 hours). Set to "-1" to disable.
# idle_timeout: "24h"

# Rate limiting configuration (optional - these are the defaults)
rate_limit:
  # Max failed auth attempts before banning an IP
  max_failed_attempts: 5
  # Time window for counting failed attempts (e.g., "5m", "1h")
  failed_attempt_window: "5m"
  # How long to ban an IP after too many failed attempts
  ban_duration: "15m"
  # Max concurrent connections from a single IP (0 = unlimited)
  max_connections_per_ip: 100
  # Max total concurrent connections (0 = unlimited, default: CPUs * 2)
  # max_connections: 16