extenddb.sample.toml

# Copyright 2026 ExtendDB contributors
# SPDX-License-Identifier: Apache-2.0
# extenddb configuration — sample template
#
# Copy this file to extenddb.toml and edit as needed.
# Or run `extenddb init` to generate one automatically.
#
# SECURITY: This file may contain the encryption key for credential storage.
# Set permissions to 0600 (owner read/write only): chmod 600 extenddb.toml
# The server refuses to start if permissions are more permissive.
#
# All values shown are defaults. Uncomment and change to override.
#
# Environment variable overrides use the EXTENDDB__ prefix with __ as separator:
#   EXTENDDB__SERVER__PORT=9000
#   EXTENDDB__STORAGE__POSTGRES__CONNECTION_STRING="postgresql://..."

# Path to the rendered documentation directory (HTML + PDF files).
# Generated by `python3 docs/build-docs.py`. When set, the web console
# serves documentation at /console/docs. When absent, the docs routes
# show a "not configured" message.
# `extenddb init` auto-discovers this directory if it exists.
# docs_dir = "/path/to/docs/rendered"

[server]
# bind_addr = "127.0.0.1"      # Network interface to bind (default: localhost only)
# port = 18443                 # HTTP port
# region = "us-east-1"         # AWS region for ARN generation
# run_dir = "~/.extenddb/run"  # Directory for PID file (~ is expanded to $HOME)

[storage]
# backend = "postgres"         # Storage backend: "postgres" (default), "mongodb", or "sqlite".

# --- SQLite backend (developer mode) ---
# Select with `extenddb init --backend sqlite`. The database path can be given
# at init time (`extenddb init --sqlite-path <path>`, written into this file)
# or set here. At serve time, the EXTENDDB__STORAGE__SQLITE__PATH environment
# variable overrides this value.
# Use ":memory:" for an ephemeral in-memory database (data lost on shutdown).
# [storage.sqlite]
# path = "extenddb.sqlite"

[storage.postgres]
# Connection string points to the CATALOG database.
# The catalog stores table metadata and the data database connection info.
# Multiple independent catalogs can coexist on one PostgreSQL instance.
# connection_string = "postgresql://extenddb:extenddb-local-dev@localhost:5432/extenddb_catalog"
# pool_size = 20               # Maximum concurrent database connections
                                # for DynamoDB data operations. Default: 20.
                                # Minimum: 10 (smaller values are clamped with
                                # a startup warning). This value sizes TWO
                                # pools: one against the catalog database and
                                # one against the data database, which `init`
                                # always creates separately. Total PostgreSQL
                                # connections used: 2 * pool_size +
                                # catalog_pool_size, plus one per vector index
                                # build running on this server and one while a
                                # schema migration runs. max_connections is
                                # per cluster, not per database, so both pools
                                # draw on the same budget. The build session and
                                # the migration connection sit OUTSIDE every
                                # pool, for two different reasons.
                                # A build's ownership lock is SESSION-scoped, so
                                # it needs a session that ends when the build
                                # ends: a pooled connection returns to the pool
                                # still holding the lock. The migration lock is
                                # TRANSACTION-scoped and needs a pinned
                                # connection instead, because its explicit
                                # transaction must retain one PostgreSQL backend
                                # until COMMIT; a transaction-pooling proxy could
                                # otherwise let the lock move between backends.
                                # Increase for higher concurrency; ensure
                                # PostgreSQL max_connections >= 2 * pool_size
                                # + catalog_pool_size + the number of vector
                                # index builds you expect to overlap. The
                                # defaults already need 60 of PostgreSQL's
                                # default 100.
# catalog_pool_size = 20       # Maximum concurrent connections for the
                                # management/catalog pool (authz, IAM, console).
                                # Defaults to pool_size if not set.
                                # Minimum: 10 (smaller values are clamped with
                                # a startup warning). With auth enabled, each
                                # DynamoDB request makes concurrent authz queries
                                # — size this to match expected concurrency.

[storage.mongodb]
# MongoDB connection string. Requires a replica set (even single-node).
# connection_string = "mongodb://localhost:27017/?replicaSet=rs0"
# max_connections = 50         # Maximum concurrent data-operation connections.
# max_catalog_connections = 20 # Shared catalog/auth pool for management and
                                # authorization traffic; size for their combined
                                # concurrency.
# transaction_read_concern = "snapshot"
                                # Read concern for the multi-document transactions
                                # backing conditional writes, TransactWriteItems,
                                # TransactGetItems, and idempotency tokens. Accepted
                                # values: "snapshot", "majority", and "local".
                                # "snapshot" is the default, fidelity-preserving mode.
                                # Some MongoDB-wire-compatible backends (e.g.
                                # DocumentDB) reject "snapshot" transactions with
                                # CommandNotSupported (115); set this to "majority"
                                # or "local" only when required. Both lose the
                                # single point-in-time guarantee; "local" may read
                                # data later rolled back after failover.

[auth]
# provider = "builtin"          # Auth provider:
                                #   "builtin" — SigV4 verification with local credential
                                #               store and IAM policy evaluation.
                                # Authentication is mandatory. The server refuses to start
                                # with provider = "none". Run `extenddb init` to create the
                                # encryption key and admin user before first start.

[auth.cache]
# In-memory stale-while-revalidate caches sit between the request hot path
# and the catalog database. Each request would otherwise issue ~6 catalog
# queries during auth/authz; caching reduces this to ~0 in steady state.
#
# Self-induced changes (admin API mutations) propagate instantly via
# write-through invalidation. Off-instance changes (multi-node deployments
# or direct DB writes) take up to `ttl_seconds` to propagate.
# enabled = true                # Master kill switch. When false, the
                                # cache wrappers bypass moka entirely
                                # (no lookup, no insert, no LRU pressure)
                                # and forward every request to the catalog.
                                # Use during incident response.
# ttl_seconds = 60              # Hard TTL — entries older than this trigger
                                # a fresh, request-blocking load.
# soft_ttl_seconds = 30         # Stale-but-usable threshold. Older entries
                                # are returned immediately while a background
                                # task refreshes them. Set equal to
                                # ttl_seconds to disable refresh-ahead.
# negative_ttl_seconds = 5      # Negative-cache TTL for "not found" results.
                                # Short by design so newly-created entities
                                # become usable quickly.
# max_entries = 10000           # Per-cache LRU cap.

# Management web console is served at /console/ on the same port as the
# DynamoDB API. No separate configuration needed — it uses the same bind
# address and port as [server]. The console requires auth.provider = "builtin"
# (it authenticates against the admin_users and iam_users tables).

# Provisioned throughput throttling via in-memory token buckets.
# When enabled, tables with provisioned capacity are rate-limited to their
# configured RCU/WCU. On-demand tables use default ceilings (12,000 RCU /
# 4,000 WCU). Account-level aggregate limits also apply.
# Disabled by default — enable for production-like behavior.
# throttling_enabled = false

[server.tls]
# TLS is mandatory. The server refuses to start with enabled = false.
# cert_path = "~/.extenddb/tls/cert.pem"   # PEM certificate file
# key_path = "~/.extenddb/tls/key.pem"     # PEM private key file
# `extenddb init` generates a self-signed certificate automatically.
# Replace with a CA-signed certificate for production use.

[limits]
# All defaults match real DynamoDB limits.
# Override only for testing edge cases.
#
# max_attribute_name_bytes = 65535  # REQ-LIM-004: 64 KB
#
# Preview extension: allow multi-part (composite) keys on base tables.
# GSIs always support multi-part keys regardless of this setting.
# allow_multipart_table_keys = false

[logging]
# level = "info"               # Log level: trace, debug, info, warn, error
# format = "pretty"            # Log format: "pretty" (human) or "json" (structured)
#
# Logging output is determined by the launch mode:
#   extenddb serve → syslog (facility: daemon, ident: extenddb)
#   Read logs with: journalctl -t extenddb
# No configuration needed — output always goes to syslog.

# Import/Export file operations are disabled by default (secure default).
# Configure allowed directories separately for imports and exports.
# All file paths are canonicalized and must resolve under one of the
# configured roots. Symlinks escaping a root are rejected.
#
# Files are namespaced per account beneath each root: a caller in account
# 111122223333 may only read and write under <root>/111122223333. A path that
# resolves elsewhere is rejected, so tenants sharing an instance cannot read or
# overwrite each other's files. Export refuses to overwrite an existing file.
#
# [import]
# paths = ["/var/lib/extenddb/imports"]
#
# [export]
# paths = ["/var/lib/extenddb/exports"]
#
# max_import_bytes = 10737418240  # 10 GB default
#
# Deprecated: import_export_root sets a single root for both import and export.
# It fills only a list that the sections leave empty, so with both [import] and
# [export] present it does nothing, and with neither present it makes the import
# and export roots the same directory. The server logs which of those happened at
# startup. Prefer the sections above; this key will be removed.
#
# It is a top-level key, so it has to appear before the first [section] header of
# this file. Uncommenting it here would place it inside the preceding table and
# the server would refuse to start with "unknown field import_export_root".
#     import_export_root = "/var/lib/extenddb/data"

# Runtime settings are managed via `extenddb settings set <key> <value>`, not this file.
# See docs/getting-started.md for available runtime settings and their defaults.

# --- Production Configuration Example ---
# Uncomment and adapt the following for production deployments:
#
# [server]
# bind_addr = "0.0.0.0"
# port = 18443
#
# [server.tls]
# cert_path = "/etc/extenddb/tls/cert.pem"
# key_path = "/etc/extenddb/tls/key.pem"
#
# [storage.postgres]
# connection_string = "postgresql://extenddb:<password>@db.example.com:5432/extenddb_catalog?sslmode=require"
# pool_size = 50
# catalog_pool_size = 50
#
# [auth]
# provider = "builtin"
#
# [logging]
# level = "info"
# format = "json"