Skip to the page
KilbyDocs
Data View as Markdown
On this page

Databases

Kilby runs managed Postgres for you, with the vector extension (pgvector) already enabled. A database lives inside your workspace and is reachable from your services, workers and cron jobs, and from nowhere else.

A workspace can have up to 2 databases. A database counts toward the workspace's CPU, memory and disk limits.

Create a database#

Click New, then Postgres, or call POST /api/v1/databases. The form shows the list price per month in a bar at the bottom as you pick the instance type and the disk size, and the Size card of an existing database shows the change in price before you save.

SettingChoices
Name3 to 30 characters: lowercase letters, digits and hyphens, starting with a letter. It cannot be changed.
Postgres version17 and 18, and 18 is recommended. Minor updates are applied for you.
Instance typeStarter, Standard or Pro. See Services for CPU, memory and list prices.
Disk1, 5, 10 and 20 GB. It can grow later but never shrink. It can also grow by itself.
Grow the disk automaticallyOff unless you turn it on, with the largest size it may grow to. See Disk growth.

A database is ready in about a minute. Its status goes from Creating to Available.

Postgres versions#

PostgreSQL supports each major version for five years: 17 until November 8, 2029 and 18 until November 14, 2030. After that date a version gets no more fixes, so the creation form tells you when the version you choose stops being supported. Every version has the vector extension (pgvector) already enabled, and the same settings otherwise.

  • A backup is restored to the version it came from. A restore never changes the major version.
  • A database cannot be upgraded to a newer major version in place. To move to one, create a new database of that version and copy your data with pg_dump and pg_restore.
  • A request to the API that names no version creates version 17. The versions this Kilby offers are in postgres_versions of GET /api/v1/workspace.

Connect#

A database called main is reached at db-main-rw on port 5432. It has one database and one user, both called app, and a generated password.

text
postgresql://app:<password>@db-main-rw:5432/app

The page shows the connection URL (and the password) to roles that may see secrets. The fastest way to use it: on the database's page, Connect a service adds the URL to a service as an environment variable (DATABASE_URL unless you change the name) and starts a new deploy of that service.

There is no public address. Only services of the same workspace can connect, so you cannot reach a database from your laptop.

A database runs as a single instance. If its machine is replaced or you change its instance type, it restarts and connections drop for a few seconds. Change the instance type from the Size card: the disk can grow but not shrink.

Disk growth#

A disk grows by hand from the Size card of the database: bigger, never smaller. A volume can be changed once every 6 hours (an AWS rule), and a change made by hand counts too.

Kilby can also grow the disk for you, so a database does not stop because its disk filled up. Grow the disk automatically is off unless you turn it on, when you create the database or later in its Disk growth card (in the API: autogrow and autogrow_max_gb when you create it, and PUT /api/v1/databases/<id>/autogrow later). It needs a largest size, so a bigger bill never comes as a surprise.

  • Kilby measures how full the disk is every 5 minutes while the database is available.
  • When the disk is 90% full or more, Kilby makes it bigger by the larger of 20% and 1 GB, rounded up to a whole GB.
  • It never grows above the largest size you set, and never above what the workspace's disk limit leaves after its other disks and databases (the form shows both numbers). It never shrinks.
  • If the disk fills again within 6 hours of the last change, the next growth is queued and the card says when it will happen. In the meantime the disk can fill: choose a largest size and a starting size that leave room for a busy day.
  • Each growth is in the activity log with the old and the new size, and sends the database.storage_grown event to your webhooks and an email to the members of the workspace (turn the email off under Notifications).
  • When the disk is 90% full or more and cannot grow, because it is at the largest size or the workspace has no room, the overview's Needs attention list says which, with what to do: raise the largest size, free space, or ask for a higher limit.
  • The disk is read from inside the database's own container, with the standard df command: the numbers are what the volume reports, not an estimate. If Kilby cannot read it, it does nothing and says so on the card.

The extra space is billed like the rest of the disk, by the second at the size it has: $0.30 per GB a month at list prices. Kilby is free during the beta and nothing is billed today; the Usage page already counts the new size from the moment the volume has it.

pgvector#

The vector extension is already created in the app database. Use it straight away:

sql
CREATE TABLE items (id bigserial PRIMARY KEY, body text, embedding vector(3));
INSERT INTO items (body, embedding) VALUES ('hello', '[1,2,3]');
SELECT body FROM items ORDER BY embedding <-> '[1,2,4]' LIMIT 5;

High availability#

Note

High availability, a standby on another node with automatic failover, is not available yet on this Kilby. Until it is, a database runs as a single instance: if its machine fails it is down until it restarts on another one. Backups are the way back from a lost disk.

Backups and point-in-time restore#

Every change to a database is archived continuously to encrypted storage, and a full backup is taken every day. You can restore any second of the last 7 days into a new database.

  • Archiving lags the database by at most 5 minutes, so the last few minutes before a failure may not be in the backup.
  • The daily backup starts at a time between 00:00 and 05:59 UTC that is the same every day for a database. The database page shows it.
  • A new database has no restore window until its first backup has finished.
  • Back up now takes a full backup at once. A database can be backed up by hand up to 6 times a day.
  • The backups of a deleted database are kept for 30 days, and until then you can restore it from the Databases page.
  • Backups are copies in Amazon S3, apart from the database's disk, and only this workspace's databases can read them.

What is not covered: restoring over the database in place (you restore into a new one and point your services at it), and a copy you can download (use pg_dump for that). Service disks are not backed up.

Restore to a new database#

A restore never touches the database it comes from: it creates a new database that starts from a moment you choose, with its own address, password and backups.

  1. Open the database, go to Backups and click Restore….
  2. Choose Latest, or Point in time and a moment in UTC inside the restore window shown (to the second).
  3. Name the new database, pick its instance type and a disk at least as big as the source's.
  4. Click Restore into a new database. It starts like any new database and its page shows when it is Available.
  5. Point your services at it with Connect a service.

With the API: GET /api/v1/databases/<id>/backups shows the restore window, and:

sh
curl -sS -X POST https://onkilby.com/api/v1/databases/<id>/restore \
  -H "Authorization: Bearer $KILBY_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "main-restored", "target_time": "2026-11-13T09:30:00Z"}'

Leave target_time out for the latest point.

Import data from another Postgres#

Import data on a database's page copies another Postgres database into it: from Render, Heroku, Neon, Supabase or your own server. The copy (pg_dump piped into pg_restore) runs inside your workspace; Kilby's own servers never connect to the source.

  1. Open the database and go to Import data.
  2. Paste the source's URL, postgresql://user:password@host:5432/name. On Render it is the database's External Database URL.
  3. Confirm that the tables the source also has may be replaced, and click Import.

The card follows the copy, then shows the result, the source's version and size, how many tables the database has, and the end of what the copy printed, with the URL and the passwords removed.

What is copied: tables, rows, indexes, constraints, sequences, views, functions, and the extensions a database owner may create (the trusted ones, such as pg_trgm, citext, uuid-ossp, pgcrypto and hstore). Extensions the database already has, such as vector, are left as they are.

What is not copied: roles, owners and privileges (everything belongs to the database's user, app); extensions only a superuser may create, which the result names; publications and subscriptions.

What is replaced: the tables the source brings replace the tables of the same name. Tables only this database has are left as they are.

  • The copy runs in one transaction. If it fails, or runs longer than 3 hours, nothing in the database changes. One import runs at a time per database.
  • The source must run the same Postgres version or an older one. A newer source is refused before anything is copied: create a database of its version and import into that one.
  • The source must be on the public internet and accept encrypted connections: sslmode is require unless the URL says verify-ca or verify-full, and disable, allow and prefer are refused. If the source only accepts some addresses, allow Kilby's outbound addresses, which are listed under Settings. An import cannot copy from another Kilby database, because those have no public address.
  • The disk must hold the source's data next to what the database holds now, with room to spare: until the copy commits, both are on the disk. A disk that is too small is refused before anything is copied, with the size it needs.
  • The copy needs room for a small helper (up to 0.5 CPU and 512 MB) next to what the workspace runs. It is not billed and does not count toward your plan's limits.

Move a database to Kilby#

  1. Import once, early. It tells you how long a copy takes and whether anything is not copied.
  2. Point a test deploy of your app at the database and check it.
  3. At the cut-over, stop the writes to the source (put your app there in maintenance), click Sync again, and once it has succeeded, point your services at this database with Connect a service and move your traffic. Writes made to the source after a copy started are not in it.

Sync again copies from the saved URL again, and replaces the tables it brings, with what was written to them here since the last copy. Kilby keeps the URL encrypted for 7 days after its last use, then deletes it. Forget deletes it at once, and so does deleting the database; an import that is already running keeps its own encrypted copy until it ends, and one still waiting to start fails without changing anything. The URL is never shown again: the page shows only its host, port and database name.

With the API:

sh
curl -sS -X POST https://onkilby.com/api/v1/databases/<id>/imports \
  -H "Authorization: Bearer $KILBY_API_KEY" -H "Content-Type: application/json" \
  -d '{"source_url": "postgresql://user:password@host:5432/name"}'

Send {} to sync again from the saved URL, and follow the copy with GET /api/v1/databases/<id>/imports/<import_id>. DELETE /api/v1/databases/<id>/import-source forgets the URL.

Delete a database#

On the database's page, Delete database asks you to type its name. It deletes the database and its disk. Its backups stay for 30 days.