Persistence Configuration

Fleans supports two persistence providers: SQLite (default, for local development) and PostgreSQL (for production and load testing). The provider is selected at startup via configuration — no code changes are required to switch.

Provider Selection

Set Persistence__Provider (case-insensitive: Sqlite or Postgres) on every fleans-* workload via your deployment tool. For PostgreSQL, also provide a connection string via ConnectionStrings__fleans. The runtime key is documented in Configuration / Persistence.

Compose bundle

The release pipeline publishes the compose bundle with PostgreSQL as the provider (fleans-postgres ships in the bundle). To switch to SQLite (single-host debug), or to point at an external Postgres, drop a docker-compose.override.yaml next to the bundle’s docker-compose.yaml:

services:
  fleans-core:
    environment:
      Persistence__Provider: Postgres
      ConnectionStrings__fleans: "Host=my-external-pg;Database=fleans;Username=fleans;Password=secret"
  fleans-management:
    environment:
      Persistence__Provider: Postgres
      ConnectionStrings__fleans: "Host=my-external-pg;Database=fleans;Username=fleans;Password=secret"
  fleans-mcp:
    environment:
      Persistence__Provider: Postgres
      ConnectionStrings__fleans: "Host=my-external-pg;Database=fleans;Username=fleans;Password=secret"
  fleans-worker:
    environment:
      Persistence__Provider: Postgres
      ConnectionStrings__fleans: "Host=my-external-pg;Database=fleans;Username=fleans;Password=secret"

docker compose up -d from the bundle directory merges the override automatically. The override file is not regenerated by the post-processor, so it persists across aspire publish re-runs.

Helm

# SQLite (chart default — single-host debug)
helm install fleans nightbaker/fleans

# Bundled PostgreSQL (chart provisions a containerised Postgres + secret)
helm install fleans nightbaker/fleans \
  --set persistence.provider=Postgres

The chart emits Persistence__Provider unconditionally. When persistence.provider=Postgres AND postgres.enabled=true (the default), ConnectionStrings__fleans is injected from the chart-managed secret. When postgres.enabled=false, the chart skips that injection so you can supply the connection string yourself via extraEnv — see below.

External PostgreSQL (managed RDS, Cloud SQL, …):

values-external-pg.yaml

postgres:
  enabled: false
persistence:
  provider: Postgres
extraEnv:
  - name: ConnectionStrings__fleans
    valueFrom:
      secretKeyRef:
        name: my-external-pg-secret
        key: connection-string

kubectl create secret generic my-external-pg-secret \
  --from-literal=connection-string='Host=my-external-pg.example.com;Port=5432;Database=fleans;Username=fleans;Password=...'
helm install fleans nightbaker/fleans -f values-external-pg.yaml

extraEnv accepts either value: "..." (literal — convenient for --set one-liners) or valueFrom.secretKeyRef (GitOps-friendly — recommended for production credentials). Both shapes propagate to every fleans-* workload via the chart’s commonEnv helper.

Manual / non-Compose / non-Helm hosts

If you’re running silos outside Compose or Helm (bare-VM systemd units, ECS task definitions, hand-crafted Kubernetes manifests), set the same runtime keys directly. Either via appsettings.json:

{
  "Persistence": { "Provider": "Postgres" },
  "ConnectionStrings": {
    "fleans": "Host=postgres;Database=fleans;Username=fleans;Password=secret"
  }
}

Or via environment variables (.NET configuration precedence puts env above appsettings.json):

Persistence__Provider=Postgres
ConnectionStrings__fleans="Host=postgres;Database=fleans;Username=fleans;Password=secret"

Accepted values for Persistence__Provider (case-insensitive): Sqlite, Postgres. Default: Sqlite.

SQLite (default)

SQLite requires no extra configuration for local development. The default connection string points to a temp-directory database.

Configuration Key	Description	Default
ConnectionStrings:fleans	SQLite connection string	DataSource=fleans-dev.db
ConnectionStrings:fleans-query	Optional read-side connection string	Same as primary

Startup behaviour: SQLite uses EnsureCreated() — schema is created from the EF Core model on first run. There is no migration runner for SQLite.

PostgreSQL

PostgreSQL requires an accessible Postgres instance and a connection string.

Configuration Key	Description	Required
ConnectionStrings:fleans	Primary PostgreSQL connection string	Yes
ConnectionStrings:fleans-query	Read-replica connection string	No

Example appsettings.json:

{
  "Persistence": {
    "Provider": "Postgres"
  },
  "ConnectionStrings": {
    "fleans": "Host=localhost;Database=fleans;Username=fleans;Password=secret"
  }
}

Startup behaviour: PostgreSQL uses MigrateAsync() — EF Core migrations are applied automatically on Fleans.Api startup. Fleans.Web and Fleans.Mcp share the same database but do not run migrations.

Read replica: When ConnectionStrings:fleans-query is provided, the query DbContext connects to the replica. The replica must be provisioned separately (e.g. a PostgreSQL standby). The chart provisions only the primary fleans database; read-replica wiring is tracked in issue #170.

See also

• Configuration — runtime configuration keys for Persistence__Provider and ConnectionStrings__fleans
• Observability — health checks, metrics, logging, tracing, dashboards, alerting
• Deployment — how to wire the ConnectionStrings__fleans / ConnectionStrings__fleans-query env vars into Docker Compose, Kubernetes, and bare-VM deployments.
• Self-Hosting on Kubernetes — bring-your-own Postgres on the Helm chart.