---
title: Configuration Reference
description: Exhaustive reference for the Fabriq Config struct, functional Options, environment variables, and validation rules.
---

This is the exhaustive reference for every `Config` field, functional `Option`, and `FABRIQ_*` environment variable. For the task-oriented walkthrough of how to assemble and pass configuration, see [Getting Started · Configuration](/docs/fabriq/(getting-started)/configuration).

`Config` is Fabriq's declarative configuration: which stores exist and which projections run. It carries `yaml` and `json` struct tags (the same schema the `fabriq` binary loads from YAML). Entities are **not** configured here — they are registered in code via the registry.

```go
type Config struct {
	Postgres      PostgresConfig
	Shards        []ShardConfig
	Redis         RedisConfig
	FalkorDB      FalkorDBConfig
	Elasticsearch ElasticsearchConfig
	Storage       StorageConfig
	Projections   ProjectionsConfig
	Subscriptions SubscriptionsConfig
	Cache         CacheConfig
	Encryption    EncryptionConfig
}
```

## PostgresConfig

Locates the source of truth. Required unless `shards` is set (a single `postgres` block is the one-shard shorthand). YAML/JSON key: `postgres`.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `DSN` | `string` | `dsn` | `""` | Postgres connection string. Required when `shards` is empty (the single-shard case). |
| `PoolSize` | `int` | `pool_size` | `0` | Connection pool size passed to the adapter via `postgres.WithPoolSize`. Zero leaves the adapter default. |

## ShardConfig

Locates one source-of-truth shard. YAML/JSON key: `shards` (a list). When `shards` is non-empty, tenants are routed across these shards and the top-level `postgres` block is ignored. See [Sharding](/docs/fabriq/(concepts)/sharding).

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `ID` | `string` | `id` | `""` | Stable shard identifier. Required and unique within `shards`. |
| `DSN` | `string` | `dsn` | `""` | Postgres connection string for this shard. Required. |
| `PoolSize` | `int` | `pool_size` | `0` | Connection pool size for this shard. Zero leaves the adapter default. |

<Callout type="warn">
`shards` is a list of structs and cannot be set through the `FABRIQ_*` environment overlay — multi-shard deployments must mount a `config.yaml`, and the shard count is fixed at deploy time. See [Sharding](/docs/fabriq/(concepts)/sharding).
</Callout>

## RedisConfig

Locates the event fan-out / cache store. YAML/JSON key: `redis`. Required when any projection is enabled and for live subscriptions.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `Addr` | `string` | `addr` | `""` | Redis address. Empty disables Redis (no live subscriptions, no projection event stream). |
| `DB` | `int` | `db` | `0` | Redis logical database number. |
| `Username` | `string` | `username` | `""` | Redis ACL username. |
| `Password` | `string` | `password` | `""` | Redis password. |

## FalkorDBConfig

Locates the graph projection engine. YAML/JSON key: `falkordb`. Required when `projections.graph` is enabled.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `Addr` | `string` | `addr` | `""` | FalkorDB address. Empty leaves `Graph()` returning `ErrStoreNotConfigured`. |
| `Username` | `string` | `username` | `""` | FalkorDB username. |
| `Password` | `string` | `password` | `""` | FalkorDB password. |

## ElasticsearchConfig

Locates the search projection engine. YAML/JSON key: `elasticsearch`. Required when `projections.search` is enabled.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `Addrs` | `[]string` | `addrs` | `nil` | Elasticsearch node addresses. Empty leaves `Search()` returning `ErrStoreNotConfigured`. |
| `Username` | `string` | `username` | `""` | Elasticsearch username. |
| `Password` | `string` | `password` | `""` | Elasticsearch password. |

## ProjectionsConfig

Switches projection planes on. YAML/JSON key: `projections`.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `Graph` | `bool` | `graph` | `false` | Enable the graph projection. Requires `falkordb.addr` and `redis.addr`. |
| `Search` | `bool` | `search` | `false` | Enable the search projection. Requires `elasticsearch.addrs` and `redis.addr`. |

## SubscriptionsConfig

Tunes the delta plane. YAML/JSON key: `subscriptions`. Each non-zero field is translated into a functional `Option` by `Config.Options()` (see below).

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `ConflationWindow` | `time.Duration` | `conflation_window` | `0` (unset → option default `150ms`) | Hub last-write-wins flush window. When `> 0`, applied via `WithConflationWindow`. Must be `>= 0` (validated). |
| `StreamMaxLen` | `int64` | `stream_max_len` | `0` (unset → option default `500`) | Approximate `MAXLEN` for per-channel Redis streams. When `> 0`, applied via `WithStreamMaxLen`; also passed to the Redis adapter as `redis.WithChannelMaxLen`. |
| `SubscribeBuffer` | `int` | `subscribe_buffer` | `0` (unset → option default `64`) | Per-subscriber delta buffer. When `> 0`, applied via `WithSubscribeBuffer`. |

<Callout type="info">
A zero value in `SubscriptionsConfig` means "leave the default". `Config.Options()` only emits an `Option` for a field that is strictly greater than zero, so the option defaults in `defaultSettings()` apply otherwise.
</Callout>

## StorageConfig

Configures the object-store backend that fills `f.Blob()` (the [file-plane](/docs/fabriq/(file-plane)/file-plane) byte plane). YAML/JSON key: `storage`. An empty `StorageDriver` leaves the blob port unconfigured — the byte plane ships dark and `Blob()` calls return `ErrStoreNotConfigured`.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `StorageDriver` | `string` | `storageDriver` | `""` | Object-store driver name. Empty leaves the blob port unconfigured. |
| `DefaultBucket` | `string` | `defaultBucket` | `""` | Bucket the byte plane writes to. |
| `EnableCas` | `bool` | `enableCas` | `false` | When true, `Open()` wires a content-addressable store backed by the `blob_cas` ledger (requires a Postgres adapter). |

## CacheConfig

Tunes the optional L1 (per-node LRU) tier of the engine cache. YAML/JSON key: `cache`. The shared read-through cache is enabled by wiring a `cache.Cache` port; these fields add the in-process L1 tier on top.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `L1Enabled` | `bool` | `l1_enabled` | `false` | Gates the per-node LRU tier. Requires `Redis.Addr` (for cross-node L1 eviction). |
| `L1Size` | `int` | `l1_size` | `0` | Max entries the LRU holds. Set a positive value when `L1Enabled` (0 = no entries). |
| `L1TTL` | `time.Duration` | `l1_ttl` | `5m` (when `L1Enabled` and `<= 0`) | Per-entry TTL; also bounds the cold-start cross-node staleness window. |

## EncryptionConfig

Configures field-level encryption for `blob_source` credentials. YAML/JSON key: `encryption`.

| Field | Type | yaml/json key | Default | Meaning |
| --- | --- | --- | --- | --- |
| `Key` | `string` | `key` | `""` | Base64-encoded 32-byte AES-256 data-encryption key. Empty disables encryption — writes that carry credentials then fail closed. |

## Functional Options

`Option` values customize a `Fabriq` and are passed to `Open` or `New`. They mutate the internal `settings` struct. Defaults below come from `defaultSettings()`.

| Option | Signature | Default | Effect |
| --- | --- | --- | --- |
| `WithConflationWindow` | `WithConflationWindow(d time.Duration) Option` | `150ms` | Tunes the hub's LWW flush window (spec range 100–250ms). Ignored when `d <= 0`. |
| `WithSubscribeBuffer` | `WithSubscribeBuffer(n int) Option` | `64` | Sets the per-subscriber delta buffer; full buffers drop (clients refetch + resume by `Last-Event-ID`). Ignored when `n <= 0`. |
| `WithWaitPollInterval` | `WithWaitPollInterval(d time.Duration) Option` | `25ms` | Tunes `WaitForProjection`'s poll cadence. Ignored when `d <= 0`. |
| `WithStreamMaxLen` | `WithStreamMaxLen(n int64) Option` | `500` | Approximate `MAXLEN` for per-channel Redis streams (catch-up depth before clients must refetch). Ignored when `n <= 0`. |
| `WithAuthz` | `WithAuthz(fn subscribe.AuthzFunc) Option` | none | Installs the subscribe-time authorization hook. |
| `WithDocumentAuthz` | `WithDocumentAuthz(fn func(ctx context.Context, docID string) error) Option` | none | Installs the document-plane authorization hook, consulted for both `ApplyUpdate` (writes) and `SubscribeDocument` (reads). Without it, any authenticated member of the tenant may touch any of the tenant's documents. |
| `WithUpcasters` | `WithUpcasters(chain *event.UpcasterChain) Option` | `nil` | Registers the event payload upcaster chain. Projection engines apply it at decode, so appliers only see the latest payload shape. |
| `WithTraceparent` | `WithTraceparent(fn func(context.Context) string) Option` | `otel.TraceparentFromContext` | Supplies the W3C traceparent extractor stamped into event envelopes. Appended to the executor options. |
| `WithClock` | `WithClock(now func() time.Time) Option` | system clock | Overrides the command-plane clock (tests). Appended to the executor options. |

<Callout type="info">
`withTailer` is an internal option (wires the hub pump from the Redis transport) and is not part of the public `Option` surface — `Open` selects it automatically when `redis.addr` is set. By default the executor is configured with `command.WithTraceparent(otel.TraceparentFromContext)` so one trace spans command → outbox → relay → projection apply.
</Callout>

## Environment Variables

The `fabriq` binary (`cmd/fabriq`) is environment-first: the deployment injects a secret plus configmap. The `--dsn` global flag overrides `FABRIQ_POSTGRES_DSN` for ad-hoc operator use.

| Variable | Read by | Default | Meaning |
| --- | --- | --- | --- |
| `FABRIQ_POSTGRES_DSN` | serve + every operator command | none | Postgres DSN. Required to serve. Overridden by `--dsn`. |
| `FABRIQ_REDIS_ADDR` | serve | none | Redis address. Required to serve. |
| `FABRIQ_FALKORDB_ADDR` | serve, rebuild, reconcile (inspect) | `""` | FalkorDB address. Optional: enables the graph projection. |
| `FABRIQ_ELASTICSEARCH_ADDRS` | serve, rebuild, reconcile (inspect) | `""` | Comma-separated Elasticsearch addresses. Optional: enables the search projection. |
| `FABRIQ_HTTP_ADDR` | serve | `:8081` | HTTP listen address for the worker (health, metrics). |
| `FABRIQ_RECONCILE_INTERVAL` | serve | `5m` | Go duration string for the reconcile loop cadence. `"0"` disables it. Unparseable values are ignored (default kept). |

<Callout type="warn">
To serve, both `FABRIQ_POSTGRES_DSN` and `FABRIQ_REDIS_ADDR` must be set — the worker extension fails its start otherwise. Operator commands (`migrate`, `inspect`, `rebuild`, `reconcile`) need only the DSN (via `--dsn` or `FABRIQ_POSTGRES_DSN`), plus the relevant store flag/env for graph or search work.
</Callout>

## Validation Rules

`Config.Validate()` checks cross-field consistency only — it does **not** dial any store. `Open` calls it before opening adapters. The rules:

- `postgres.dsn` must be non-empty **unless** `shards` is set. When `shards` is set, every shard needs a non-empty, unique `id` and a non-empty `dsn`.
- If `projections.graph` is enabled, `falkordb.addr` must be non-empty.
- If `projections.search` is enabled, `elasticsearch.addrs` must be non-empty.
- If either projection is enabled, `redis.addr` must be non-empty (projections need the event stream).
- `subscriptions.conflation_window` must be `>= 0`.

Each failed rule returns a `fmt.Errorf` with a `fabriq: config: ...` prefix; none are typed sentinels.

<Cards>
<Card title="Configuration Guide" href="/docs/fabriq/(getting-started)/configuration">Task-oriented walkthrough of assembling and passing configuration.</Card>
<Card title="Errors" href="/docs/fabriq/reference/errors">The typed and sentinel errors Fabriq returns, including ErrStoreNotConfigured.</Card>
<Card title="Decisions" href="/docs/fabriq/reference/decisions">Architecture decision records behind these knobs.</Card>
</Cards>