config.toml.example

# Marmot v2.9.16-beta Configuration
# Leaderless SQLite Replication

# ==============================================================================
# NODE IDENTITY
# ==============================================================================

# Unique identifier for this node (0 = auto-generate from machine ID)
node_id = 0

# Directory for node data (logs, state, etc.)
# Place existing SQLite .db files here - they will be imported on first startup
data_dir = "./marmot-data"

# ==============================================================================
# TRANSACTION MANAGER
# ==============================================================================

[transaction]
# Transaction timeout without heartbeat (seconds)
heartbeat_timeout_seconds = 10

# Time window for Last-Write-Wins conflict resolution (seconds)
conflict_window_seconds = 10

# Lock wait timeout (seconds) - matches MySQL innodb_lock_wait_timeout
lock_wait_timeout_seconds = 50

# MySQL has no transactional DDL: CREATE/ALTER/DROP implicitly commit the open
# transaction, then run on their own. Keep true for MySQL-compatible behaviour so
# DML can see a schema change made earlier in the same transaction.
# Set false to keep DDL inside the transaction and replicate it atomically with
# the surrounding statements.
ddl_implicit_commit = true

# ==============================================================================
# CLUSTER MEMBERSHIP
# ==============================================================================

[cluster]
# Address to bind gRPC server (0.0.0.0 = all interfaces)
grpc_bind_address = "0.0.0.0"

# Address other nodes use to connect to this node
# Leave empty to auto-detect (hostname:grpc_port)
# Override for NAT/Docker: "public-ip:8080" or "service-name:8080"
grpc_advertise_address = ""

# gRPC port for cluster communication
grpc_port = 8080

# List of seed nodes to join cluster (empty = start as first node)
# Example: ["node1.example.com:8080", "node2.example.com:8080"]
seed_nodes = []

# PSK for cluster authentication (or set MARMOT_CLUSTER_SECRET env var)
# Leave empty to disable authentication
cluster_secret = ""

# Gossip protocol interval (milliseconds)
gossip_interval_ms = 1000

# Number of random peers to gossip with each round
gossip_fanout = 3

# Time before marking unresponsive node as suspect (milliseconds)
suspect_timeout_ms = 5000

# Time before declaring suspect node as dead (milliseconds)
dead_timeout_ms = 10000

# Node promotion settings (JOINING -> ALIVE state transition)
[cluster.promotion]
check_interval_seconds = 2      # How often to check for promotion
min_healthy_duration_sec = 3    # Must be healthy for this long before promotion
require_all_databases = true    # All databases must exist before promotion

# Backpressure settings for snapshot streaming
[cluster.backpressure]
max_queue_depth = 1000          # Max apply queue depth before pausing
check_interval_ms = 100         # How often to check queue depth

# ==============================================================================
# REPLICATION
# ==============================================================================

[replication]
# Default write consistency level
# How many nodes must ACK before write is considered successful:
# - ONE: Any single node ACKs (fastest, least durable)
# - QUORUM: Majority of nodes ACK (recommended - balances speed & durability)
# - ALL: All alive nodes ACK (slowest, most durable)
default_write_consistency = "QUORUM"

# Default read consistency level
# How many nodes to read from:
# - LOCAL_ONE: Read from coordinator node only (fastest, may be stale)
# - ONE: Read from any single node (fast, may be stale)
# - QUORUM: Read from majority of nodes (consistent, slower)
# - ALL: Read from all nodes (most consistent, slowest)
default_read_consistency = "LOCAL_ONE"

# Timeout for write operations (milliseconds)
write_timeout_ms = 5000

# Timeout for read operations (milliseconds)
read_timeout_ms = 2000

# Enable anti-entropy background sync
# Automatically catches up lagging nodes by replaying missed transactions
enable_anti_entropy = true

# Anti-entropy sync interval (seconds)
# How often to check for and repair replication lag
# Lower values = fresher watermarks for GC, but more network overhead
anti_entropy_interval_seconds = 30

# GC interval (seconds)
# How often garbage collection runs to clean up old transaction records
# MUST be >= anti_entropy_interval_seconds to ensure fresh watermarks before GC
gc_interval_seconds = 60

# Delta sync threshold (transactions)
# If a node lags by more than this many transactions, use snapshot instead of delta sync
delta_sync_threshold_transactions = 10000

# Delta sync threshold (seconds)
# If a node lags by more than this duration, use snapshot instead of delta sync
delta_sync_threshold_seconds = 3600

# Minimum GC retention (hours)
# Transaction logs kept for at least this long to support replication catch-up
# MUST be >= delta_sync_threshold_seconds in hours
gc_min_retention_hours = 2

# Maximum GC retention (hours)
# Force GC after this duration even if peers lagging (prevents unbounded growth)
# Should be at least 2x delta_sync_threshold_seconds in hours (or 0 for unlimited)
gc_max_retention_hours = 24

# ==============================================================================
# METADATA STORAGE (PebbleDB)
# Uses CockroachDB-tested defaults for high throughput
# ==============================================================================

[metastore]
# Block cache size in MB (default: 64)
cache_size_mb = 64

# MemTable size in MB (default: 64, CockroachDB-style)
memtable_size_mb = 64

# Number of MemTables (default: 2)
memtable_count = 2

# L0 compaction trigger threshold (default: 500, CockroachDB-style)
# Higher values reduce write latency at cost of read amplification
l0_compaction_threshold = 500

# L0 stop writes threshold (default: 1000, CockroachDB-style)
# When L0 files exceed this, writes stall until compaction catches up
l0_stop_writes = 1000

# WAL sync every N KB (default: 512KB)
# Controls background WAL sync frequency for durability
wal_bytes_per_sync_kb = 512

# Periodic WAL checkpoint interval in milliseconds (default: 10ms)
# Also triggers SQLite WAL checkpoint for consistency
# Set to 0 to disable periodic checkpoints
wal_sync_interval_ms = 10

# ==============================================================================
# CONNECTION POOL
# ==============================================================================

[connection_pool]
# Number of connections per pool
pool_size = 4

# Maximum idle time for connections (seconds)
max_idle_time_seconds = 10

# Maximum lifetime for connections (seconds)
max_lifetime_seconds = 300

# ==============================================================================
# GRPC CLIENT
# ==============================================================================

[grpc_client]
# Send keepalive ping every N seconds
keepalive_time_seconds = 10

# Timeout for keepalive ping response (seconds)
keepalive_timeout_seconds = 3

# Maximum retry attempts for failed requests
max_retries = 3

# Backoff duration between retries (milliseconds)
retry_backoff_ms = 100

# zstd compression level for gRPC messages (0 = disabled)
# Level 1: Fastest (~318 MB/s, 2.88x ratio) - recommended for most deployments
# Level 2: Default (~134 MB/s, 3.0x ratio)
# Level 3: Better compression (~67 MB/s, 3.2x ratio)
# Level 4: Best compression (~12 MB/s, 3.5x ratio) - use for bandwidth-constrained networks
# Note: Decompression is always fast (~1600 MB/s) regardless of level
compression_level = 1

# ==============================================================================
# TRANSACTION COORDINATOR
# ==============================================================================

[coordinator]
# Timeout for 2PC prepare phase (milliseconds)
prepare_timeout_ms = 2000

# Timeout for 2PC commit phase (milliseconds)
commit_timeout_ms = 2000

# Timeout for 2PC abort phase (milliseconds)
abort_timeout_ms = 2000

# ==============================================================================
# DDL REPLICATION
# ==============================================================================

[ddl]
# DDL lock lease duration (seconds)
lock_lease_seconds = 30

# Automatically rewrite DDL for idempotency (IF NOT EXISTS, IF EXISTS)
enable_idempotent = true

# ==============================================================================
# QUERY PIPELINE
# ==============================================================================

[query_pipeline]
# LRU cache size for transpiled queries
transpiler_cache_size = 10000

# SQLite connection pool size for validation
validator_pool_size = 8

# ==============================================================================
# MYSQL PROTOCOL SERVER
# ==============================================================================

[mysql]
# Enable MySQL wire protocol server
enabled = true

# Address to bind MySQL server (0.0.0.0 = all interfaces)
bind_address = "0.0.0.0"

# MySQL protocol port
port = 3306

# Maximum concurrent MySQL connections
max_connections = 1000

# Enable LOAD DATA LOCAL INFILE support (client uploads file contents)
local_infile_enabled = true

# Auto-increment ID generation mode
# "compact" (default) = 53-bit IDs safe for JavaScript (Number.MAX_SAFE_INTEGER)
# "extended" = 64-bit HLC-based IDs for maximum uniqueness
auto_id_mode = "compact"

# ==============================================================================
# SNAPSHOT (Streaming recovery for new/lagging nodes)
# ==============================================================================

[snapshot]
# Enable snapshot streaming
enabled = true

# Snapshot interval (seconds) - for periodic snapshots
interval_seconds = 300

# Snapshot storage type: peer, s3, webdav, sftp, local
store = "peer"

# Snapshot chunk size (MB)
chunk_size_mb = 5

# Number of parallel chunks for snapshot transfer
parallel_chunks = 5

# Number of changes before triggering full snapshot
incremental_threshold = 10000

# ==============================================================================
# READ-ONLY REPLICA MODE
# ==============================================================================

[replica]
# Enable read-only replica mode (follows cluster nodes with transparent failover)
# When enabled, the node does NOT join the cluster - it only streams changes
enabled = false

# Seed nodes for cluster discovery (required when enabled)
# The replica will discover other nodes and failover automatically
# Example: ["node1:8080", "node2:8080", "node3:8080"]
follow_addresses = []

# Discovery interval - how often to poll for cluster membership (seconds)
discovery_interval_seconds = 30

# Failover timeout - max time to find an alive node during failover (seconds)
failover_timeout_seconds = 60

# Initial reconnect interval (seconds)
reconnect_interval_seconds = 5

# Maximum reconnect backoff (seconds)
reconnect_max_backoff_seconds = 30

# Timeout for initial snapshot sync (minutes)
initial_sync_timeout_minutes = 30

# PSK for authenticating with cluster (or set MARMOT_REPLICA_SECRET env var)
# Required when replica mode is enabled
secret = ""

# ==============================================================================
# LOGGING
# ==============================================================================

[logging]
# Enable verbose debug logging
verbose = false

# Log format: "console" (human-readable) or "json" (structured)
format = "console"

# ==============================================================================
# SQLITE EXTENSIONS
# ==============================================================================

[extensions]
# Directory containing SQLite extension libraries (.so, .dylib, .dll)
# Extensions can be loaded via "LOAD EXTENSION <name>" SQL command
# Example: "/opt/sqlite/extensions"
directory = ""

# Extensions to load automatically into every connection
# Example: ["sqlite-vector", "sqlite-vss"]
always_loaded = []

# ==============================================================================
# METRICS
# ==============================================================================

[prometheus]
# Enable Prometheus metrics endpoint
# Metrics are served on the gRPC port at /metrics (no separate port needed)
enabled = true