> ## 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](/products/storage/cwdb/create). For day-2 actions like editing, resizing, and deleting a database, see [Manage database](/products/storage/cwdb/manage). For the `CWDBBackup` field reference and the `spec.postgres.restore` field reference, see [Manage backups](/products/storage/cwdb/backups).

<Note>
  By default, your CoreWeave Database (CWDB) only has password authentication. For the modes CWDB supports and how to configure clients, see [Authentication modes](/products/storage/cwdb/connect#authentication-modes).
</Note>

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

## Minimal manifest

The smallest `CWDBCluster` manifest the operator accepts:

```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
  resources:
    requests:
      memory: 1Gi
      cpu: "1"
    limits:
      memory: 2Gi
```

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.
</Warning>

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.

## 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
```

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

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

Replica scale-out (increasing or decreasing `spec.postgres.instances` after creation) is supported in limited availability. In-place vertical scaling (changing per-instance CPU or memory) hasn't been verified yet. To change per-instance compute, restore the database into a new one with the desired sizing. See [Manage database](/products/storage/cwdb/manage) and [Manage backups](/products/storage/cwdb/backups).

## 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

CWDB supports [pgvector](https://github.com/pgvector/pgvector), letting you use the database as a vector database and to perform approximate nearest-neighbor search. Enable it by adding it to the `spec.postgres.extensions` list:

```yaml theme={"system"}
spec:
  postgres:
    instances: 3
    extensions:
      - name: pgvector
```

The following table describes the extensions field:

| Field                      | Required | Description                           |
| -------------------------- | -------- | ------------------------------------- |
| `spec.postgres.extensions` | No       | List of curated extensions to enable. |

After the database is `Ready`, install the extension per database with `CREATE EXTENSION vector;`.

## 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 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]`.
</Warning>

## Database name and owner

`spec.postgres.dbName` and `spec.postgres.owner` set the initial database name and owner role. By default, CWDB 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 creates two credentials Secrets per database, named after `dbName`: `[CLUSTER-NAME]-[DBNAME]-credentials` for read-write traffic and `[CLUSTER-NAME]-[DBNAME]-credentials-ro` for read-only traffic to replicas. For `dbName: orders`, those are `[CLUSTER-NAME]-orders-credentials` and `[CLUSTER-NAME]-orders-credentials-ro`. The defaults for `dbName: app` are `[CLUSTER-NAME]-app-credentials` and `[CLUSTER-NAME]-app-credentials-ro`.

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
    extensions:
      - 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:

```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.                                  |
| `backupStatus` | Timestamp of the most recent successful base backup and current WAL archive position.     |
| `instances`    | Per-instance status including role (primary or replica), pod name, and persistent volume. |

For the `CWDBBackup` field reference and the `spec.postgres.restore` field reference, see [Manage backups](/products/storage/cwdb/backups).