> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure database

> Field reference for the CWDBCluster resource: topology, compute, storage, and extensions

This page is the field reference for the `CWDBCluster` resource. Use it to tune topology, compute, storage, extensions, affinity, and the initial database name and owner.

For the creation workflow, see [Create a database](https://docs.coreweave.com/products/storage/cwdb/create.md). For day-2 actions like editing, resizing, and deleting a database, see [Manage database](https://docs.coreweave.com/products/storage/cwdb/manage.md). For the `CWDBBackup` field reference and the `spec.postgres.restore` field reference, see [Manage backups](https://docs.coreweave.com/products/storage/cwdb/backups.md).

> [!NOTE]
>
> CoreWeave Database supports password authentication only. For how to configure clients, see [Authentication modes](https://docs.coreweave.com/products/storage/cwdb/connect.md#authentication-modes).

All CoreWeave Database resources live in the `data.coreweave.com/v1` API group and are namespaced.

## Minimal manifest

The following manifest sets only the fields the operator requires: the database type, the number of instances, and the storage size per instance:

```yaml theme={"system"}
apiVersion: data.coreweave.com/v1
kind: CWDBCluster
metadata:
  name: my-db
spec:
  type: postgres
  postgres:
    instances: 3
  storage:
    resources:
      requests:
        storage: 5Gi
```

This manifest omits `spec.resources`, so each instance gets the default compute described in [Compute](#compute). Every other configuration knob layers on top of this manifest.

## Topology

`spec.postgres.instances` controls how many PostgreSQL instances the operator runs. The operator places one primary and all replicas across distinct nodes through pod anti-affinity, assuming the CoreWeave Kubernetes Service (CKS) cluster has enough nodes to spread out on.

The following table describes the instances field:

| Field | Required | Description |
| - | - | - |
| `spec.postgres.instances` | Yes | Number of database instances. CoreWeave recommends `3` or more for production workloads (one primary plus two or more replicas). |

> [!WARNING]
>
> Choose three or more instances for production workloads.
>
> A single instance can't tolerate any disruption: maintenance, configuration changes, node failure, or a database crash result in a definitive outage.
>
> Two instances make quorum harder to establish and can cause availability issues under some failure modes.

For most workloads, 3 instances is the right balance of availability and cost. Scaling beyond 3 instances primarily adds read capacity, not durability. Set `spec.postgres.instances` to 5 or more when your workload is read-heavy and benefits from spreading reads across additional replicas.

### Synchronous replication

`spec.postgres.synchronousReplication` makes the primary wait until a set number of replicas confirm each commit. By default, replication is asynchronous: the primary confirms each commit without waiting for replicas, so a failover can lose the most recent commits.

Synchronous replication requires each instance to run on a different Node. When `synchronousReplication` is set, the operator requires this placement instead of only preferring it. If the CKS cluster doesn't have enough CPU Nodes, the instances that can't be placed stay `Pending` until you add CPU Nodes. For diagnosis, see [Database never becomes `Ready`](https://docs.coreweave.com/products/storage/cwdb/troubleshooting#database-never-becomes-ready).

In the following example, the primary waits for one of the two replicas:

```yaml highlight={4-7} theme={"system"}
spec:
  postgres:
    instances: 3
    synchronousReplication:
      number: 1
      dataDurability: required
      failoverQuorum: true
```

The following table describes the synchronous replication fields:

| Field | Required | Description |
| - | - | - |
| `spec.postgres.synchronousReplication.number` | Yes | Number of replicas that must confirm each commit. Any replica can count toward it. Must be at least `1` and less than `spec.postgres.instances`. |
| `spec.postgres.synchronousReplication.dataDurability` | Yes | What happens when fewer than `number` replicas are healthy: `required` or `preferred`. |
| `spec.postgres.synchronousReplication.failoverQuorum` | No | When `true`, CoreWeave Database runs a quorum-based safety check before failover and doesn't promote a replica that it can't prove is current. Defaults to `false`. |

`dataDurability` and `failoverQuorum` apply at different times:

* `dataDurability` applies while the primary runs, when fewer than `number` replicas are healthy. It trades durability against write availability:
  * `required`: Writes block until enough replicas are healthy again. No confirmed commit exists only on the primary, unless a session sets `synchronous_commit` to `local` or `off`.
  * `preferred`: CoreWeave Database waits for fewer replicas so writes continue. Commits confirmed during that time can exist only on the primary.
* `failoverQuorum` applies when the primary fails. It trades availability against durability during promotion:
  * `true`: CoreWeave Database promotes a replica only if it can prove the replica is current. Otherwise, the database stays without a primary until enough replicas are reachable to prove one is current, or until the primary recovers.
  * `false`, the default: CoreWeave Database can promote a replica that it can't prove is current.

To keep every confirmed commit through a failover, use both `dataDurability: required` and `failoverQuorum: true`.

### Logical replication slot high availability

To sync logical replication slots from the primary to the replicas, set `spec.postgres.logicalReplicationSlotHA.enabled` to `true`. Change data capture (CDC) clients such as Debezium can then resume from their slot after a switchover or failover. Without it, logical slots exist only on the primary.

The feature has the following requirements:

* PostgreSQL 17 or later. The default, `18`, qualifies.
* At least two instances.
* CDC clients must create their slots with failover enabled, for example with the `failover` argument of [`pg_create_logical_replication_slot()`](https://www.postgresql.org/docs/17/functions-admin.html#FUNCTIONS-REPLICATION) or the Debezium `slot.failover` connector property. CoreWeave Database syncs only failover-enabled slots.

To sync a slot that already exists, recreate it with failover enabled, or enable failover on it with the [`ALTER_REPLICATION_SLOT`](https://www.postgresql.org/docs/17/protocol-replication.html#PROTOCOL-REPLICATION-ALTER-REPLICATION-SLOT) replication command.

Changing this field reloads PostgreSQL parameters without a rolling restart. CoreWeave Database manages `hot_standby_feedback` and `sync_replication_slots` for this feature, so you can't set them in `spec.postgres.parameters`.

> [!WARNING]
>
> Disabling `logicalReplicationSlotHA` stops syncing slots but doesn't remove slots already synced to the replicas. PostgreSQL doesn't let you drop a synced slot on a replica. Those slots keep retaining write-ahead log (WAL) on the replicas and use storage.

Before you disable the feature, drop the slots you no longer need on the primary. The replicas then remove their copies.

If you already disabled the feature and synced slots remain on the replicas, remove them:

1. Set `spec.postgres.logicalReplicationSlotHA.enabled` to `true`.
2. On the primary, drop the slots you no longer need with `pg_drop_replication_slot()`.
3. Wait until a query of `pg_replication_slots` on a replica no longer lists those slots.
4. Set `spec.postgres.logicalReplicationSlotHA.enabled` to `false`.

## Compute

`spec.resources` sets the CPU and memory requests and limits for each instance in the database. The following example configures every instance with 2 CPU requested, 4 GiB of memory, and an 8 GiB memory limit:

```yaml theme={"system"}
spec:
  resources:
    requests:
      cpu: "2"
      memory: 4Gi
    limits:
      memory: 8Gi
```

`spec.resources` is optional. If you omit the entire `spec.resources` object, each instance requests 1 CPU and 1 GiB of memory, with a 2 GiB memory limit. If you set `spec.resources`, the operator uses it as written and doesn't fill in missing fields from these defaults.

The following table describes each `spec.resources` field:

| Field | Required | Description |
| - | - | - |
| `spec.resources.requests.cpu` | No | CPU request per instance, in standard Kubernetes units (for example, `"1"`, `"2"`). Must be at least `1`. |
| `spec.resources.requests.memory` | No | Memory request per instance (for example, `1Gi`, `4Gi`). Must be at least `1Gi`. |
| `spec.resources.limits.memory` | No | Memory limit per instance. Should comfortably exceed `requests.memory` to absorb query bursts. |

To change instance count or per-instance compute after creation, see [Edit a database](https://docs.coreweave.com/products/storage/cwdb/manage.md#edit-a-database).

## Connections and pooling

`spec.postgres.connections` sets how many connections your applications can open and whether a PgBouncer connection pooler sits between them and PostgreSQL. From these values, the operator derives PostgreSQL `max_connections`, the pooler limits, and the minimum memory each instance must request.

### How connections relate

A connection from your application can pass through three layers:

* **Client connections**: the connections your applications open. `spec.postgres.connections.max` caps their total.
* **Poolers**: in `transaction` and `session` modes, the operator runs one PgBouncer pooler Pod per database instance, up to three, and splits `max` evenly across them. In `none` mode, there's no pooler.
* **Server connections**: the connections PostgreSQL accepts, capped by PostgreSQL `max_connections`. The operator reserves 50 of them for management, monitoring, and backups.

In `transaction` mode, client connections share up to 300 server connections. In `session` and `none` modes, each client connection uses its own server connection, so PostgreSQL `max_connections` is `max` + 50.

### Choose a pooler mode

The following table describes when to use each value of `spec.postgres.connections.pooler.mode`:

| Mode | Pooler | Session state | Use when |
| - | - | - | - |
| `transaction` | Yes | Not kept. Consecutive transactions from a client can use different server connections. | Your application doesn't rely on session state. Client connections survive database switchovers. We recommend this mode. |
| `session` | Yes | Kept for the life of the client connection. | Your application relies on session state, such as session-level advisory locks, session-level `SET` commands, or `LISTEN`. |
| `none` | No | Kept for the life of the client connection. | Your application relies on session state and connects directly to the database Services. Can't be combined with `spec.postgres.enableCrossZoneAccess`. |

In `none` mode, applications connect to the direct database Services. To find the Service each credentials Secret routes to, see [Choose a connection Service](https://docs.coreweave.com/products/storage/cwdb/connect.md#choose-a-connection-service).

### Connection limits and memory requirements

The pooler mode determines what `max` limits, the resulting PostgreSQL `max_connections`, the minimum memory, and what happens when you change `max`:

| Mode | What `max` limits | PostgreSQL `max_connections` | Minimum `spec.resources.requests.memory` | When you change `max` |
| - | - | - | - | - |
| `transaction` | Client connections to the poolers | `350` | `3500Mi`, regardless of `max` | The poolers reload their configuration without disrupting connections. |
| `session` | Client connections to the poolers | `max` + 50 | (`max` + 50) × 10 MiB | The PostgreSQL instances restart one at a time to apply the new `max_connections`. |
| `none` | Client connections to the database | `max` + 50 | (`max` + 50) × 10 MiB | The PostgreSQL instances restart one at a time to apply the new `max_connections`. |

For example, with `max: 1000`, a `transaction` database needs at least `3500Mi` per instance, and a `session` or `none` database needs at least `10500Mi`.

> [!WARNING]
>
> In `session` or `none` mode, changing `max` restarts the PostgreSQL instances. The primary restarts in place, which interrupts writes until it's back.

When `spec.postgres.connections` is set, `spec.resources.requests.memory` is required, and the API server rejects a manifest that requests less than the minimum. The minimum is a lower bound, not a sizing recommendation. Actual memory use depends on your workload. Raising `max` in `session` or `none` mode can raise the minimum. On an existing database, raising `requests.memory` is a per-instance compute change. For compute changes, see [Compute](#compute). For failed memory checks, see [Database is rejected for insufficient memory](https://docs.coreweave.com/products/storage/cwdb/troubleshooting.md#database-is-rejected-for-insufficient-memory).

The operator reports the values it derived in `status.connections`, including `mode`, `postgresMaxConnections`, and `poolerInstances`.

### Configure connections

The following example serves up to 1,000 application connections in `transaction` mode:

```yaml highlight={4-7} theme={"system"}
spec:
  postgres:
    instances: 3
    connections:
      max: 1000
      pooler:
        mode: transaction
  resources:
    requests:
      cpu: "2"
      memory: 4Gi
    limits:
      memory: 8Gi
```

The following table describes the connections fields:

| Field | Required | Description |
| - | - | - |
| `spec.postgres.connections.max` | Yes, if `connections` is set | Maximum application connections, from `100` to `100000`. |
| `spec.postgres.connections.pooler.mode` | Yes, if `connections` is set | `transaction`, `session`, or `none`. To choose one, see [Choose a pooler mode](#choose-a-pooler-mode). |

If you omit `spec.postgres.connections`, PostgreSQL `max_connections` defaults to `350` and the pooler defaults to `transaction` mode.

`spec.postgres.connections` replaces `spec.postgres.parameters.max_connections`, which is deprecated. You can't set both, and you can't combine `connections` with the deprecated `spec.postgres.poolMode` or `spec.postgres.connectionPoolerParameters` fields. A database that already sets `parameters.max_connections` can keep its current value, but you can't add or change it. To change the limit, remove `parameters.max_connections` and set `connections`.

## Storage

`spec.storage` configures the per-instance persistent volume on DFS. The following example requests 50 GiB of storage for each instance:

```yaml theme={"system"}
spec:
  storage:
    resources:
      requests:
        storage: 50Gi
```

The following table describes the storage field:

| Field | Required | Description |
| - | - | - |
| `spec.storage.resources.requests.storage` | Yes | Storage size per instance, in standard Kubernetes quantity units (for example, `5Gi`, `100Gi`, `1Ti`). Can be increased after creation. |

A 3-instance database with `storage: 50Gi` provisions 150 GiB of DFS in total (each instance has its own replicated volume). Storage cost is billed as standard DFS usage. Start small and grow as data grows.

## Extensions

For a complete walkthrough, see [Use pgvector with CoreWeave Database](https://docs.coreweave.com/products/cks/tutorials/deploy-vector-databases-on-cks/pgvector.md).

`spec.postgres.extension` selects which curated PostgreSQL image the database runs and which extension the operator creates in the initial database. A database runs one extension at a time.

The following table describes the values `spec.postgres.extension.name` accepts:

| Value | Description |
| - | - |
| `postgresql` | Vanilla PostgreSQL with no extensions. This is the default. |
| `pgvector` | [pgvector](https://github.com/pgvector/pgvector), for storing embeddings and running approximate nearest-neighbor search. The operator creates the `vector` extension. |
| `pgduckdb` | [pg\_duckdb](https://github.com/duckdb/pg_duckdb), which embeds the DuckDB analytical engine in PostgreSQL. The operator creates the `pg_duckdb` extension and adds `pg_duckdb` to `shared_preload_libraries`. |
| `postgis-age` | [PostGIS](https://postgis.net/) for geospatial data and [Apache AGE](https://age.apache.org/) for graph queries, bundled with pgvector. The operator creates the `postgis`, `postgis_raster`, `age`, and `vector` extensions and adds `age` to `shared_preload_libraries`. Available for PostgreSQL 18 only. With any other `majorVersion`, the operator sets the `ConfigurationValid` condition to `False`. |

The following example enables pg\_duckdb:

```yaml theme={"system"}
spec:
  postgres:
    instances: 3
    extension:
      name: pgduckdb
```

The following table describes the extension fields:

| Field | Required | Description |
| - | - | - |
| `spec.postgres.extension.name` | No | Curated extension to enable. Supported values are `postgresql`, `pgvector`, `pgduckdb`, and `postgis-age`. Defaults to `postgresql`. |
| `spec.postgres.extension.majorVersion` | No | PostgreSQL major version. Supported values are `16`, `17`, and `18`, except `postgis-age`, which supports only `18`. Defaults to `18`. |

`spec.postgres.extension.majorVersion` sets the PostgreSQL major version for every database, including databases that run vanilla PostgreSQL. It is the only field that sets the major version. The following example pins a pg\_duckdb database to PostgreSQL 17:

```yaml theme={"system"}
spec:
  postgres:
    instances: 3
    extension:
      name: pgduckdb
      majorVersion: 17
```

The operator creates the extensions in the initial database, so no `CREATE EXTENSION` statement is needed there. For `postgis-age`, the operator also grants the owner role access to the `ag_catalog` schema and adds `ag_catalog` to the database's `search_path`, which Apache AGE needs. The operator doesn't set up extensions in any other database. None of these extensions is a trusted PostgreSQL extension, so only a superuser can create one, and the owner role isn't a superuser. To use an extension in another database, contact CoreWeave through your customer Slack channel. For pg\_duckdb query syntax and functions, see the [pg\_duckdb documentation](https://github.com/duckdb/pg_duckdb/tree/main/docs).

## PostgreSQL parameters

`spec.postgres.parameters` overrides a small set of PostgreSQL settings. Values are strings, so quote numbers and include unit suffixes such as `MB` or `GB` where PostgreSQL accepts them.

The following table describes the parameters `spec.postgres.parameters` accepts:

| Parameter | Description |
| - | - |
| `max_locks_per_transaction` | Size of the shared lock table, which limits how many objects transactions can lock at once. Must be an integer greater than or equal to `64`, the default. Changing it causes a rolling restart. See [`max_locks_per_transaction`](https://www.postgresql.org/docs/current/runtime-config-locks.html#GUC-MAX-LOCKS-PER-TRANSACTION) in the PostgreSQL documentation. |
| `temp_file_limit` | Maximum disk space a single process can use for temporary files. See [`temp_file_limit`](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-TEMP-FILE-LIMIT) in the PostgreSQL documentation. |
| `pgaudit.*` | Any [pgAudit](https://github.com/pgaudit/pgaudit) setting, such as `pgaudit.log` or `pgaudit.role`. |

The following example raises the lock table size and turns on audit logging for data definition language (DDL) and write statements:

```yaml highlight={4-6} theme={"system"}
spec:
  postgres:
    instances: 3
    parameters:
      max_locks_per_transaction: "256"
      pgaudit.log: "ddl, write"
```

If you set any other parameter, an empty value, or a `max_locks_per_transaction` value below `64`, the operator doesn't apply the change. It sets the `ConfigurationValid` condition to `False` with reason `SpecInvalid` and a message that describes the problem. For an unsupported parameter, the message lists the allowed ones. Correct the spec to resume reconciliation.

Any configured `pgaudit.*` parameter turns on managed pgAudit, which is off by default. The operator adds `pgaudit` to `shared_preload_libraries`, manages the extension, and performs a rolling restart. To turn pgAudit off, remove every `pgaudit.*` entry from `spec.postgres.parameters`. The operator then removes `pgaudit` from `shared_preload_libraries` and performs another rolling restart. Changes to `pgaudit.*` values while pgAudit is on apply without a restart. Changes to `temp_file_limit` also apply without a restart.

The pgAudit extension writes audit records to the `postgres` container's log as JSON with `logger` set to `pgaudit`. Replace `[CLUSTER-NAME]` with the name of your `CWDBCluster` and `[NAMESPACE]` with its namespace. To read the audit records, run:

```bash theme={"system"}
kubectl logs -l cnpg.io/cluster=[CLUSTER-NAME] -c postgres --tail=-1 --namespace [NAMESPACE] | grep '"logger":"pgaudit"'
```

Like other Pod logs, audit records are also collected in [CoreWeave Logs](https://docs.coreweave.com/observability/logs-metrics/data-sources.md).

## Affinity overrides

`spec.affinity` overrides the default Kubernetes affinity rules for the database. By default, every database carries Node-affinity rules that prefer CPU Nodes and Nodes labeled `cks.coreweave.cloud/system-critical`, and Pod anti-affinity rules that spread instances across distinct Nodes. The following example hard-requires CPU Nodes rather than preferring them:

```yaml theme={"system"}
spec:
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: node.coreweave.cloud/class
                operator: In
                values: ["cpu"]
```

The following table describes the affinity field:

| Field | Required | Description |
| - | - | - |
| `spec.affinity` | No | Kubernetes affinity overrides. The operator applies CPU node-affinity and pod anti-affinity by default. Override only when necessary. |

> [!WARNING]
>
> Affinity overrides can prevent the operator from spreading instances across nodes, which weakens the failure model. Override only when necessary and validate that pods still land on distinct nodes by running `kubectl get pods -o wide -l cnpg.io/cluster=[CLUSTER-NAME]`.

## Database name and owner

`spec.postgres.dbName` and `spec.postgres.owner` set the initial database name and owner role. By default, CoreWeave Database creates a database named `app` with an owner role named `app`. The following example names the database `orders` and the owner role `orders_app`:

```yaml theme={"system"}
spec:
  postgres:
    instances: 3
    dbName: orders
    owner: orders_app
```

The following table describes both fields:

| Field | Required | Description |
| - | - | - |
| `spec.postgres.dbName` | No | Name of the initial database. Defaults to `app`. |
| `spec.postgres.owner` | No | Name of the owner role created for the initial database. Defaults to `app`. |

The operator names the database's two credentials Secrets after `dbName`. See [Credentials Secrets](https://docs.coreweave.com/products/storage/cwdb/connect.md#credentials-secrets).

A built-in `postgres` superuser role is always created alongside the owner role. The `postgres` role is reserved for break-glass access and database maintenance. Use the owner role for application traffic.

## Complete example

A 3-instance database sized for a moderate application workload, with a custom database name and `pgvector` enabled:

```yaml theme={"system"}
apiVersion: data.coreweave.com/v1
kind: CWDBCluster
metadata:
  name: my-db
spec:
  type: postgres
  postgres:
    instances: 3
    dbName: orders
    owner: orders_app
    extension:
      name: pgvector
  storage:
    resources:
      requests:
        storage: 50Gi
  resources:
    requests:
      cpu: "2"
      memory: 4Gi
    limits:
      memory: 8Gi
```

## Database status

The operator manages the `status` section of a `CWDBCluster`. To inspect it, run the following command from a terminal with `kubectl` access to your CKS cluster. Replace `[CLUSTER-NAME]` with the name of your `CWDBCluster` and `[NAMESPACE]` with the namespace it runs in:

```bash theme={"system"}
kubectl describe cwdbcluster [CLUSTER-NAME] --namespace [NAMESPACE]
```

The `status` section reports the following information:

| Status field | Description |
| - | - |
| `conditions` | `Ready`, `Provisioning`, and other lifecycle conditions. |
| `instances` | Per-instance status including role (primary or replica), pod name, and persistent volume. |
| `maintenance` | Pending or in-progress maintenance:<ul><li>`type`: `MajorVersionUpgrade` or `MinorVersionUpgrade`.</li><li>`phase`: `Scheduled`, `Running`, `Succeeded`, `Aborted`, or `Error`.</li><li>`startingAfter` and `cutoffTime`: the earliest and latest times the maintenance can run.</li><li>`upgrade`: `versionFrom` and `versionTo`.</li></ul>To configure maintenance, see [Schedule maintenance](https://docs.coreweave.com/products/storage/cwdb/manage.md#schedule-maintenance). |

For the `CWDBBackup` field reference and the `spec.postgres.restore` field reference, see [Manage backups](https://docs.coreweave.com/products/storage/cwdb/backups.md).
