PostgreSQL
kcore declares one PostgreSQL database on a node from the NixOS postgresql package. The service runs on kcoreOS itself. It does not run inside a VM.
Version 1 listens on the node's Unix socket. TCP is not enabled. On the node, connect as the postgres superuser: sudo -u postgres psql -d app.
Declare a database
The first apply creates the database. A later apply can change the port. Changing the package, database name, or target node is rejected.
kctl create postgresql app \
--database app \
--package postgresql \
--port 5432 \
--target-node <NODE_ID>
kind: Postgresql
metadata:
name: app
spec:
database: app
package: postgresql
port: 5432
Apply: kctl apply -f postgresql.yaml. kind: postgres is accepted as well.
Declare the database with kcore_postgresql. Only port changes in place.
Commands
| Operation | Command |
|---|---|
| Apply | kctl apply -f postgresql.yaml |
| Create | kctl create postgresql app --database app --package postgresql --port 5432 |
| Get | kctl get postgresql app |
| List | kctl get postgresql |
| Describe | kctl describe postgresql app |
| Delete | kctl delete postgresql app |
postgres is an alias of postgresql on create, get, describe, and delete.
Fields
| Field | Description |
|---|---|
metadata.name | Instance name. Letters, digits, hyphen, and underscore, up to 63 characters, starting with a letter or digit. |
spec.database | Database name. A PostgreSQL identifier. Defaults to the instance name when that name is a valid identifier. Immutable. |
spec.package | Nixpkgs attribute: postgresql (default), postgresql_14, postgresql_15, postgresql_16, or postgresql_17. Immutable. |
spec.port | Port recorded for the service. Default 5432. Mutable. Clients still use the local Unix socket in v1. |
spec.targetNode | Node that hosts the database. Optional. The controller picks a ready node that does not already host PostgreSQL. Immutable. CLI flag: --target-node. |
Re-apply
kctl apply -f and kctl create postgresql upsert. Create and delete require vm-admin. Get and list are read-only.
Connect
After the node applies the NixOS config, the database is available on that node's Unix socket. Deleting the resource removes the NixOS service definition and leaves /var/lib/postgresql on disk.
Current limits
- One database per node. A second instance on the same node is rejected.
- No TCP listener and no password setup in v1. Reach the database from the node.
- The package cannot change in place. A major upgrade needs a delete and a new database.
- A multi-node PostgreSQL cluster is planned for Q1 2027. This page covers the single database.