---
title: "Configuration"
description: "Every config section and key Galleon's own modules read."
canonical_url: "https://docs.galleon.thec1oud.uk/docs/reference/config"
markdown_url: "https://docs.galleon.thec1oud.uk/docs/reference/config.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
---

# Configuration
URL: /docs/reference/config
LLM index: /llms.txt
Description: Every config section and key Galleon's own modules read.

{/* Generated by `go generate ./...` in site/ from Galleon's source. Don't edit it by hand. */}

# Configuration

Each section is a key of the JSON config file. See [Modules and wiring](/docs/concepts/modules#configuration) for how config is loaded.

A key marked **env** can also be set with the environment variable `<APP>_<SECTION>_<KEY>`, in upper case. The environment wins over the file. A key marked **secret** is redacted in `App.ConfigReport()`.

A `time.Duration` key is a number of nanoseconds in the file, as `encoding/json` reads it, and a string with a unit, such as `30s`, in the environment. The `migrate` section's durations are strings with a unit in both. Defaults are shown with a unit. A blank default is the type's zero value: empty, `false` or `0`.

## client

Read by package `client`.

| Key | Type | Default | Description |
|---|---|---|---|
| `timeout` **env** | `time.Duration` | `10s` | Timeout bounds each attempt, from sending the request until the response body is closed, so it covers reading the whole body: a streamed response needs zero, which turns it off, or a longer one. |
| `retries` **env** | `int` | `2` | Retries is how many times a failed idempotent request is retried. |
| `retry_backoff` **env** | `time.Duration` | `100ms` | RetryBackoff is the first retry's backoff ceiling; each later retry doubles it, up to RetryBackoffMax. The wait is a random fraction of it. |
| `retry_backoff_max` **env** | `time.Duration` | `2s` | RetryBackoff is the first retry's backoff ceiling; each later retry doubles it, up to RetryBackoffMax. The wait is a random fraction of it. |
| `max_retry_after` **env** | `time.Duration` | `10s` | MaxRetryAfter is the longest Retry-After a retry waits for; a longer one ends the retries and returns the response. |
| `retry_budget` **env** | `float64` | `0.2` | RetryBudget is the share of requests that may be retries, so retries can't multiply load on a struggling server. Each request earns this many retry tokens, up to RetryBudgetBurst, and each retry spends one. |
| `retry_budget_burst` **env** | `float64` | `10` | RetryBudget is the share of requests that may be retries, so retries can't multiply load on a struggling server. Each request earns this many retry tokens, up to RetryBudgetBurst, and each retry spends one. |
| `breaker_failures` **env** | `int` | `5` | BreakerFailures consecutive failures to a host open its breaker for BreakerOpenFor. Zero failures turns the breaker off. |
| `breaker_open_for` **env** | `time.Duration` | `30s` | BreakerFailures consecutive failures to a host open its breaker for BreakerOpenFor. Zero failures turns the breaker off. |
| `max_concurrent` **env** | `int` |  | MaxConcurrent bounds requests in flight; zero is unbounded. |
| `allow_networks` | `[]string` |  | AllowNetworks are CIDRs the egress guard lets through, such as an internal service's range. AllowPrivate turns the guard off. |
| `allow_private` **env** | `bool` |  | AllowNetworks are CIDRs the egress guard lets through, such as an internal service's range. AllowPrivate turns the guard off. |
| `max_response_bytes` **env** | `int64` | `10485760` | MaxResponseBytes bounds a response body Send decodes. |

## http

Read by package `server`.

| Key | Type | Default | Description |
|---|---|---|---|
| `addr` **env** | `string` | `:8080` | Addr is where to listen: "host:port", ":port", or "unix:/path". |
| `read_header_timeout` **env** | `time.Duration` | `10s` | ReadHeaderTimeout, ReadTimeout, WriteTimeout and IdleTimeout are those of net/http.Server: how long a client may take to send the request's headers, to send the whole request, and to read the response, and how long an idle keep-alive connection stays open. |
| `read_timeout` **env** | `time.Duration` | `1m` | ReadHeaderTimeout, ReadTimeout, WriteTimeout and IdleTimeout are those of net/http.Server: how long a client may take to send the request's headers, to send the whole request, and to read the response, and how long an idle keep-alive connection stays open. |
| `write_timeout` **env** | `time.Duration` | `1m` | ReadHeaderTimeout, ReadTimeout, WriteTimeout and IdleTimeout are those of net/http.Server: how long a client may take to send the request's headers, to send the whole request, and to read the response, and how long an idle keep-alive connection stays open. |
| `idle_timeout` **env** | `time.Duration` | `2m` | ReadHeaderTimeout, ReadTimeout, WriteTimeout and IdleTimeout are those of net/http.Server: how long a client may take to send the request's headers, to send the whole request, and to read the response, and how long an idle keep-alive connection stays open. |
| `max_header_bytes` **env** | `int` | `1048576` | MaxHeaderBytes bounds the size of a request's headers. |
| `body_limit` **env** | `int64` | `4194304` | BodyLimit applies to operations that don't set their own. |
| `h2c` **env** | `bool` | `true` | H2C accepts HTTP/2 without TLS, which gRPC clients use inside a cluster. |
| `tls_cert` **env** | `string` |  | TLSCert and TLSKey are PEM files. Both or neither must be set. |
| `tls_key` **env** **secret** | `string` |  | TLSCert and TLSKey are PEM files. Both or neither must be set. |
| `trusted_proxies` | `[]string` |  | TrustedProxies are the CIDRs whose X-Forwarded-For header is believed when working out the caller's address. "unix" trusts connections on a Unix socket, from a proxy on the same host. Without it, callers on a Unix socket have no address, so rate limits keyed by address skip them. |
| `access_log` **env** | `bool` |  | AccessLog logs one line per request. |

## migrate

Read by package `galleon`. Its keys, other than `recheck` and `apply_timeout`, override the app's migration policy. A key left unset keeps the policy's value, which is the environment profile's unless the app changes it (see [Migrations](/docs/concepts/migrations#the-deploy-policy)).

| Key | Type | Default | Description |
|---|---|---|---|
| `mode` **env** | `string` | `verify` in production, `apply` otherwise | Mode is off, verify or apply. |
| `max_risk` **env** | `string` | `caution` in production, `manual` otherwise | MaxRisk is safe, caution, destructive or manual. |
| `allow_unknown` **env** | `bool` | `false` in production, `true` otherwise | AllowUnknown lets steps of unknown risk run, and migrators that can't plan apply at all. |
| `tolerate_ahead` **env** | `bool` | `false` | TolerateAhead counts a database newer than this build as ready, for the old nodes of a rolling deploy. |
| `approve` **env** | `string` |  | Approve pins approved plan fingerprints, as name=fingerprint pairs separated by commas: each the online plan's, of the changes pending on the database (see migrate.Policy.Approved). |
| `lock_ttl` **env** | `string` | `30s` | The durations are strings with a unit, such as "30s" or "10m". LockTTL is at least 1s (the default is 30s); LockWait is 0, waiting as long as the apply may, or at least 1s. |
| `lock_wait` **env** | `string` |  | The durations are strings with a unit, such as "30s" or "10m". LockTTL is at least 1s (the default is 30s); LockWait is 0, waiting as long as the apply may, or at least 1s. |
| `recheck` **env** | `string` | `5s` | Recheck is how often the readiness gate reads each migrator's status again: at least 100ms, and 5s by default. |
| `apply_timeout` **env** | `string` | `10m` | ApplyTimeout bounds applying at boot, waiting for the lock included: at least 1s, and 10m by default. |
| `debug` **env** | `bool` |  | Debug records step descriptions, which may hold SQL, in spans and logs. |

## pg

Read by package `pg`.

| Key | Type | Default | Description |
|---|---|---|---|
| `primary` | `Source` |  | Primary is the database writes go to, and reads unless they name a source. |
| `primary.dsn` | `string` |  | DSN is a postgres:// URL or a keyword/value string. "postgres://" alone takes everything from the PG\* environment variables, as libpq does. It is required. |
| `primary.max_conns` | `int32` |  | MaxConns and MinConns size the pool; zero takes pgx's defaults (at most the greater of 4 and the number of CPUs, at least none), or pool\_max\_conns and pool\_min\_conns in the DSN. |
| `primary.min_conns` | `int32` |  | MaxConns and MinConns size the pool; zero takes pgx's defaults (at most the greater of 4 and the number of CPUs, at least none), or pool\_max\_conns and pool\_min\_conns in the DSN. |
| `primary.connect_timeout` | `time.Duration` |  | ConnectTimeout bounds opening one connection; zero takes the DSN's connect\_timeout, or none. |
| `primary.max_conn_lifetime` | `time.Duration` |  | MaxConnLifetime and MaxConnIdleTime retire connections; zero takes pgx's defaults of an hour and 30 minutes. |
| `primary.max_conn_idle_time` | `time.Duration` |  | MaxConnLifetime and MaxConnIdleTime retire connections; zero takes pgx's defaults of an hour and 30 minutes. |
| `primary.name` | `string` |  | Name and Zone apply to replicas only: the name spans, logs and metrics call the replica by, in lower snake case, and the zone it runs in, for the Nearest strategy. |
| `primary.zone` | `string` |  | Name and Zone apply to replicas only: the name spans, logs and metrics call the replica by, in lower snake case, and the zone it runs in, for the Nearest strategy. |
| `named` | `map[string]Source` |  | Named are further databases, such as one a module owns or an analytics store, chosen with data.Source(name). They have no replicas: a named source's reads and writes all go to it. |
| `named.<name>.dsn` | `string` |  | DSN is a postgres:// URL or a keyword/value string. "postgres://" alone takes everything from the PG\* environment variables, as libpq does. It is required. |
| `named.<name>.max_conns` | `int32` |  | MaxConns and MinConns size the pool; zero takes pgx's defaults (at most the greater of 4 and the number of CPUs, at least none), or pool\_max\_conns and pool\_min\_conns in the DSN. |
| `named.<name>.min_conns` | `int32` |  | MaxConns and MinConns size the pool; zero takes pgx's defaults (at most the greater of 4 and the number of CPUs, at least none), or pool\_max\_conns and pool\_min\_conns in the DSN. |
| `named.<name>.connect_timeout` | `time.Duration` |  | ConnectTimeout bounds opening one connection; zero takes the DSN's connect\_timeout, or none. |
| `named.<name>.max_conn_lifetime` | `time.Duration` |  | MaxConnLifetime and MaxConnIdleTime retire connections; zero takes pgx's defaults of an hour and 30 minutes. |
| `named.<name>.max_conn_idle_time` | `time.Duration` |  | MaxConnLifetime and MaxConnIdleTime retire connections; zero takes pgx's defaults of an hour and 30 minutes. |
| `named.<name>.name` | `string` |  | Name and Zone apply to replicas only: the name spans, logs and metrics call the replica by, in lower snake case, and the zone it runs in, for the Nearest strategy. |
| `named.<name>.zone` | `string` |  | Name and Zone apply to replicas only: the name spans, logs and metrics call the replica by, in lower snake case, and the zone it runs in, for the Nearest strategy. |
| `replicas` | `[]Source` |  | Replicas are streaming replicas of the primary. Reads that begin a transaction on the primary may run on one, as their read consistency allows (see Consistency); writes never do, and data.Source can't name one. Each has a Name, by default replica\_1, replica\_2 and so on in order, and an optional Zone. |
| `replicas[].dsn` | `string` |  | DSN is a postgres:// URL or a keyword/value string. "postgres://" alone takes everything from the PG\* environment variables, as libpq does. It is required. |
| `replicas[].max_conns` | `int32` |  | MaxConns and MinConns size the pool; zero takes pgx's defaults (at most the greater of 4 and the number of CPUs, at least none), or pool\_max\_conns and pool\_min\_conns in the DSN. |
| `replicas[].min_conns` | `int32` |  | MaxConns and MinConns size the pool; zero takes pgx's defaults (at most the greater of 4 and the number of CPUs, at least none), or pool\_max\_conns and pool\_min\_conns in the DSN. |
| `replicas[].connect_timeout` | `time.Duration` |  | ConnectTimeout bounds opening one connection; zero takes the DSN's connect\_timeout, or none. |
| `replicas[].max_conn_lifetime` | `time.Duration` |  | MaxConnLifetime and MaxConnIdleTime retire connections; zero takes pgx's defaults of an hour and 30 minutes. |
| `replicas[].max_conn_idle_time` | `time.Duration` |  | MaxConnLifetime and MaxConnIdleTime retire connections; zero takes pgx's defaults of an hour and 30 minutes. |
| `replicas[].name` | `string` |  | Name and Zone apply to replicas only: the name spans, logs and metrics call the replica by, in lower snake case, and the zone it runs in, for the Nearest strategy. |
| `replicas[].zone` | `string` |  | Name and Zone apply to replicas only: the name spans, logs and metrics call the replica by, in lower snake case, and the zone it runs in, for the Nearest strategy. |
| `select` **env** | `string` | `least_lag` | Select is how a read chooses among the replicas that qualify: "least\_lag" (LeastLag, the default), "random", "round\_robin", or "nearest", which prefers replicas in Zone and takes the least lagging of those. |
| `zone` **env** | `string` |  | Zone is this node's zone, which Nearest compares with each replica's. |
| `max_lag` **env** | `time.Duration` | `2s` | MaxLag takes a replica out of rotation while it is further behind the primary than this; it returns once it has caught up. The default is 2s. MaxLagBytes, when set, also takes out a replica more than that many bytes of WAL behind. |
| `max_lag_bytes` **env** | `int64` |  | MaxLag takes a replica out of rotation while it is further behind the primary than this; it returns once it has caught up. The default is 2s. MaxLagBytes, when set, also takes out a replica more than that many bytes of WAL behind. |
| `lag_poll` **env** | `time.Duration` | `50ms` | LagPoll is how often each replica's replay position, health and lag are read, in the background; the default is 50ms. Choosing a replica for a read only compares the latest readings. |
| `consistency` **env** | `string` | `read_your_writes` | Consistency is the read consistency of reads that neither ask for one nor run in an operation that declares one, as data.ParseLevel reads it. The default is "read\_your\_writes". |
| `token_key` **env** **secret** | `string` |  | TokenKey signs the causal tokens sent in the Galleon-Consistency response header after a request commits a write, and verifies the ones requests bring back; it must be at least 32 bytes. Without it, read-your-writes holds within a request only. TokenPreviousKey is still accepted, for rotating keys: move the old key there, set a new TokenKey, and drop the old one once tokens signed with it have expired. Nodes sharing a database must share the keys. |
| `token_previous_key` **env** **secret** | `string` |  | TokenKey signs the causal tokens sent in the Galleon-Consistency response header after a request commits a write, and verifies the ones requests bring back; it must be at least 32 bytes. Without it, read-your-writes holds within a request only. TokenPreviousKey is still accepted, for rotating keys: move the old key there, set a new TokenKey, and drop the old one once tokens signed with it have expired. Nodes sharing a database must share the keys. |
| `token_ttl` **env** | `time.Duration` | `10m` | TokenTTL is how long a token is honored; the default is 10m. An older one is ignored, as a forged or malformed one is. |
| `retry_attempts` **env** | `int` |  | RetryAttempts, RetryBackoff and RetryBackoffMax are the default retry policy of Read and Write closures (see data.RetryPolicy); zero takes that policy's defaults. |
| `retry_backoff` **env** | `time.Duration` |  | RetryAttempts, RetryBackoff and RetryBackoffMax are the default retry policy of Read and Write closures (see data.RetryPolicy); zero takes that policy's defaults. |
| `retry_backoff_max` **env** | `time.Duration` |  | RetryAttempts, RetryBackoff and RetryBackoffMax are the default retry policy of Read and Write closures (see data.RetryPolicy); zero takes that policy's defaults. |
| `leaks` **env** | `string` | `error` | Leaks says what happens to a root transaction still open when the operation that began it ends. It is always rolled back. With "error", the default, the call also fails with an Internal error whose cause has the stack of where the transaction began, and it is logged; with "log" it is only logged, and the call's own result stands. Use "error" in development and tests; "log" suits production, where a leaked read shouldn't fail a request that otherwise worked. |

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).