Dolt SQL Server Design

Date: 2026-02-07 Status: Draft Author: Sean + Claude Opus 4.6

Purpose

Deploy a Dolt SQL server on the self-hosted cluster to provide a version-controlled database backend for Beads, Gastown, and AI agent workflows. Dolt’s Git-like branching, diffing, and merging semantics make it a natural fit for agent-driven data operations that benefit from full audit trails and rollback.

Architecture

┌──────────────────────────────────────────────────┐
│  K8s Cluster                                     │
│                                                  │
│  ┌──────────────┐     ┌──────────────────┐       │
│  │ In-cluster   │────▶│  dolt-server     │       │
│  │ agents/svcs  │     │  (StatefulSet)   │       │
│  └──────────────┘     │  Port 3306       │       │
│                       │  Longhorn PVC    │       │
│  ┌──────────────┐     └────────┬─────────┘       │
│  │ ExternalSecret│             │                  │
│  │ → Vault      │─────────────┘ (credentials)    │
│  └──────────────┘                                │
│                       ┌──────────────────┐       │
│                       │ Service:         │       │
│                       │  ClusterIP:3306  │       │
│                       │  LoadBalancer:   │       │
│                       │   3306 (MetalLB) │       │
│                       └──────────────────┘       │
└──────────────────────────────────────────────────┘
                              ▲
                              │ MetalLB IP
                              │ doltdb.fzymgc.house
                              │ (router-hosts DNS)
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
  ┌─────┴──────┐   ┌─────────┴───┐   ┌────────────┴┐
  │ Beads CLI  │   │  Gastown    │   │  AI Agents  │
  │ (dev local)│   │  (anywhere) │   │  (anywhere) │
  └────────────┘   └─────────────┘   └─────────────┘

Clients may be inside or outside the Kubernetes cluster. In-cluster pods connect via dolt.dolt.svc.cluster.local:3306. External clients (dev machines, remote agents) connect via doltdb.fzymgc.house:3306, which resolves to a MetalLB LoadBalancer IP reachable over the local network and Tailscale.

Decisions

Decision	Choice	Rationale
Access mode	SQL server (MySQL wire protocol)	Multi-agent concurrency, standard MySQL drivers
Storage	Longhorn PVC, 20Gi, 3 replicas	Consistent with CNPG and other stateful workloads
Deployment	StatefulSet, raw kustomize manifests	No official Helm chart; matches existing app-configs pattern
Credentials	Vault-managed via ExternalSecret	Consistent with cluster secret management pattern
Exposure	LoadBalancer (MetalLB) + router-hosts DNS	Covers both in-cluster and external clients
Image	dolthub/dolt-sql-server:1.81.6	Latest GA release at time of design
Replicas	1	Dolt has no native replication; Longhorn provides storage redundancy

Components

Namespace

Dedicated dolt namespace.

StatefulSet

Single-replica StatefulSet running dolthub/dolt-sql-server:1.81.6.

• Volume: 20Gi Longhorn PVC at /var/lib/dolt
• Config: Mounted from ConfigMap at /etc/dolt
• Credentials: Injected as environment variables from ExternalSecret-created Secret dolt-credentials
• Port: 3306 (MySQL)

User Initialization

The Dolt Docker entrypoint supports /docker-entrypoint-initdb.d/ scripts that run once on first boot (after DOLT_USER creation). A shell script mounted from the ConfigMap handles:

1. Creates beads and agent databases
2. Grants the agent user (created by entrypoint) scoped privileges on both databases
3. Creates the beads user and grants database-scoped privileges

The script runs only once (entrypoint uses a marker file). IF NOT EXISTS guards provide additional safety.

ConfigMap

Dolt server configuration and init script:

log_level: info
behavior:
  read_only: false
  autocommit: true
listener:
  host: "0.0.0.0"
  port: 3306
  max_connections: 100

Service

LoadBalancer service with MetalLB IP allocation and router-hosts DNS registration:

annotations:
  router-hosts.fzymgc.house/enabled: "true"
  router-hosts.fzymgc.house/hostname: "doltdb.fzymgc.house"

No IngressRoute or Traefik involvement — this is raw TCP, not HTTP.

Health Probes

Both probes use TCP socket checks on port 3306. No credentials required, no root login for health checks.

livenessProbe:
  tcpSocket:
    port: 3306
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  tcpSocket:
    port: 3306
  initialDelaySeconds: 15
  periodSeconds: 10

Secrets

Vault Path

secret/fzymgc-house/cluster/dolt

Key	Purpose
root_password	Dolt root user password
agent_user	Username for general agent connections
agent_password	Password for general agent connections
beads_user	Username for Beads clients
beads_password	Password for Beads clients

ExternalSecret

Syncs all credentials from Vault to a Kubernetes Secret named dolt-credentials in the dolt namespace. Refresh interval: 15 minutes.

Vault Policy

New Terraform resource in tf/vault/policy-dolt.tf granting the ESO service account read access to secret/data/fzymgc-house/cluster/dolt.

Backup Strategy

Layer	Mechanism	Coverage
Application	Dolt built-in commit log	Every data change versioned (branch, diff, revert)
Storage	Longhorn snapshots via Velero	PVC-level snapshots (daily 30d, weekly 90d)

Dolt’s own versioning provides logical data protection (time-travel, rollback). Velero provides infrastructure-level protection against PVC loss. No additional backup CronJob needed at this time.

Connection Reference

Client Location	Connection String
In-cluster pod	mysql://agent_user:***@dolt.dolt.svc.cluster.local:3306/<db>
Local network	mysql://beads_user:***@doltdb.fzymgc.house:3306/<db>
Tailscale remote	mysql://beads_user:***@doltdb.fzymgc.house:3306/<db>

Files to Create

File	Purpose
argocd/app-configs/dolt/kustomization.yaml	Kustomize entry point
argocd/app-configs/dolt/namespace.yaml	Namespace definition
argocd/app-configs/dolt/statefulset.yaml	Dolt server StatefulSet
argocd/app-configs/dolt/service.yaml	LoadBalancer + router-hosts
argocd/app-configs/dolt/configmap.yaml	Dolt server config
argocd/app-configs/dolt/external-secret.yaml	Vault credential sync
argocd/cluster-app/templates/dolt.yaml	ArgoCD Application
tf/vault/policy-dolt.tf	Vault policy for ESO

Future Considerations

• Per-agent credentials: Add individual Vault paths per agent for granular audit trails via Dolt’s MySQL GRANT system.
• Prometheus metrics: Add mysqld_exporter sidecar for Grafana dashboards if query performance monitoring is needed.
• SQL dump export: Add CronJob for dolt dump to object storage for cross-site disaster recovery.
• Dolt remotes: Configure Dolt to push to DoltHub or another Dolt remote for off-cluster replication.