Skip to main content
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. For day-2 actions like editing, resizing, and deleting a database, see Manage database. For the CWDBBackup field reference and the spec.postgres.restore field reference, see Manage backups.
By default, CoreWeave Database only has password authentication. For the modes it supports and how to configure clients, see 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:
This manifest omits spec.resources, so each instance gets the default compute described in 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:
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. In the following example, the primary waits for one of the two replicas:
The following table describes the synchronous replication fields: 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() 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 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.
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:
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: Replica scale-out (increasing or decreasing spec.postgres.instances after creation) is supported. To change per-instance CPU or memory, restore the database into a new one with the desired sizing. See Manage database and Manage backups.

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: In none mode, applications connect to the direct database Services. To find the Service each credentials Secret routes to, see 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: For example, with max: 1000, a transaction database needs at least 3500Mi per instance, and a session or none database needs at least 10500Mi.
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. For failed memory checks, see 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:
The following table describes the connections fields: 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:
The following table describes the storage field: 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. 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: The following example enables pg_duckdb:
The following table describes the extension fields: 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:
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.

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: The following example raises the lock table size and turns on audit logging for data definition language (DDL) and write statements:
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:
Like other Pod logs, audit records are also collected in CoreWeave Logs.

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:
The following table describes the affinity field:
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:
The following table describes both fields: 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:

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:
The status section reports the following information: For the CWDBBackup field reference and the spec.postgres.restore field reference, see Manage backups.
Last modified on November 13, 2026