Show examples as

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

OperationCommand
Applykctl apply -f postgresql.yaml
Createkctl create postgresql app --database app --package postgresql --port 5432
Getkctl get postgresql app
Listkctl get postgresql
Describekctl describe postgresql app
Deletekctl delete postgresql app

postgres is an alias of postgresql on create, get, describe, and delete.

Fields

FieldDescription
metadata.nameInstance name. Letters, digits, hyphen, and underscore, up to 63 characters, starting with a letter or digit.
spec.databaseDatabase name. A PostgreSQL identifier. Defaults to the instance name when that name is a valid identifier. Immutable.
spec.packageNixpkgs attribute: postgresql (default), postgresql_14, postgresql_15, postgresql_16, or postgresql_17. Immutable.
spec.portPort recorded for the service. Default 5432. Mutable. Clients still use the local Unix socket in v1.
spec.targetNodeNode 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