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.
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: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:
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:
dataDurability and failoverQuorum apply at different times:
dataDurabilityapplies while the primary runs, when fewer thannumberreplicas 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 setssynchronous_committolocaloroff.preferred: CoreWeave Database waits for fewer replicas so writes continue. Commits confirmed during that time can exist only on the primary.
failoverQuorumapplies 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.
dataDurability: required and failoverQuorum: true.
Logical replication slot high availability
To sync logical replication slots from the primary to the replicas, setspec.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
failoverargument ofpg_create_logical_replication_slot()or the Debeziumslot.failoverconnector property. CoreWeave Database syncs only failover-enabled slots.
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.
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:
- Set
spec.postgres.logicalReplicationSlotHA.enabledtotrue. - On the primary, drop the slots you no longer need with
pg_drop_replication_slot(). - Wait until a query of
pg_replication_slotson a replica no longer lists those slots. - Set
spec.postgres.logicalReplicationSlotHA.enabledtofalse.
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.maxcaps their total. - Poolers: in
transactionandsessionmodes, the operator runs one PgBouncer pooler Pod per database instance, up to three, and splitsmaxevenly across them. Innonemode, 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.
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 ofspec.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 whatmax 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.
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 intransaction 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:
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:
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:
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:
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:
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:
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 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 andpgvector enabled:
Database status
The operator manages thestatus 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:
status section reports the following information:
For the
CWDBBackup field reference and the spec.postgres.restore field reference, see Manage backups.