Version upgrades
How PostgreSQL minor and major upgrades work on CapyDB - what is automatic, what you control, and what we apply on your behalf.
PostgreSQL versions move in two very different ways, and CapyDB treats them differently because the risk is not comparable.
| Minor (17.4 → 17.5) | Major (17 → 18) | |
|---|---|---|
| On-disk format | Identical | Changes |
| What it takes | A restart | A migration |
| Downtime | Seconds | Minutes, scheduled |
| Who starts it | Mostly automatic | You do |
| Reversible | Nothing to reverse | Yes, until you confirm |
Minor upgrades
Minor releases are binary-compatible. Your data is not touched, nothing is rewritten, and no migration runs — the new version is simply a different server binary reading the same files. Security fixes ship as minors, so this is the path that matters most.
If your database uses scale-to-zero, it upgrades itself. A paused database starts on whatever version is current when it next resumes, so most cells pick up a minor with no action and no interruption at all.
A database that is running when a minor lands keeps its current version until it restarts. The dashboard reports this, and you can apply it whenever suits you:
POST /v1/projects/{projectID}/upgrade/minorThe restart interrupts open connections briefly — that is the entire cost, and it is why we do not do it silently underneath you. The platform refuses to restart while queries are actually running, so a busy database is skipped rather than disrupted.
When we apply one on your behalf
For an urgent security release, CapyDB will apply a minor upgrade fleet-wide after a stated deadline, whether or not it has been applied by then. You are told in advance and can apply it earlier at a time you choose; the deadline exists so an unpatched database cannot sit exposed indefinitely. This is the one case where the timing is not entirely yours.
Major upgrades
Major upgrades change the on-disk format, so they are a real migration and always customer-initiated.
Check first
A major upgrade is the one operation that can fail after it has started changing things, so every reason it might fail is checked up front:
POST /v1/projects/{projectID}/upgrade/major/preflight?target_major=18The result is upgradable or blocked, with specific reasons. The blocker that matters most in practice is extensions: if something you use has no build for the target major, migrating would leave your schema referencing types and functions that no longer exist. Better to know before than after.
The check changes nothing and can be re-run as often as you like.
How the migration runs
CapyDB does not upgrade your database in place. It builds a new database on the target version, copies your data into it, verifies the result, and only then points your project at it. Your original database is left untouched throughout.
That matters for rollback: until you confirm the upgrade, reverting means pointing back at the original — instant, and with nothing lost. There is no restore-from-backup step and no window where the old copy is unavailable.
Your connection string does not change.
Extensions
Extensions version independently of PostgreSQL. When a newer build of one you use becomes available, the dashboard offers an Update action on the Extensions page:
POST /v1/projects/{projectID}/extensions/{name}/updateThis is yours to trigger, not something applied automatically, because an extension's upgrade scripts can change behaviour inside your data — a PostGIS upgrade may require reindexing afterwards, for example. Extensions CapyDB installs for its own observability are kept current automatically and are never offered here.
Applying an update when the extension is already current is a no-op, so it is safe to retry.