Databases

A box can boot from an image other than the base one. The postgres image is the base image plus PostgreSQL 16, listening on the box's address:

kvbox new db --base postgres -e POSTGRES_PASSWORD=s3cret -e POSTGRES_USER=app -e POSTGRES_DB=app

✓ box db is running at 172.30.0.7: 2 vCPU, 4 GB RAM, 8 GB disk
  reach it at:  postgres://app:s3cret@db.kvbox:5432/app

Leave a variable out and your account's or org's variable of that name applies, else the image's default: POSTGRES_USER is postgres, POSTGRES_DB is the user's name, and a POSTGRES_PASSWORD you don't give is generated. new prints the connection string once. kvbox env ls --box db shows the variables again, except a generated password: it is kept as a secret, so copy it from that connection string. A value that comes from your account's or org's variable stays ${NAME} in that string, never its value.

Reaching itCopy Anchor Link

A box can't reach another until you link them. Make the app's box on the same host, then let it reach port 5432:

kvbox new api --near db
kvbox vm link api db --port 5432
kvbox exec api -- psql postgres://app:s3cret@db.kvbox:5432/app -c 'select 1'

From your laptop, publish the port instead (ports) and use the address it gives.

First boot onlyCopy Anchor Link

The box sets up the user, the database and the password once, at its first boot, from its variables. Changing POSTGRES_PASSWORD later with kvbox env set --box db changes the variable, not the database: change the password with psql inside the box. A snapshot or a fork of the box keeps its data and its variables.

A database box never hibernates on its own (nothing would wake it on a database connection); pass --auto-hibernate to new if you want it to.

Images on a hostCopy Anchor Link

kvbox vm update db moves a box to the newest version of its own image, never to another one. Through kvbox.sh a box of an image goes on a host that has it. On your own host, install-server.sh installs the images in IMAGES (default postgres:v0.1.0; IMAGES="" for none), next to the base image.