Log inSign upBook a demo
Tines Stories
  1. Docs
  2. Self-Hosted
  3. Upgrading Tines
  1. Docs
  2. Self-Hosted
  3. Upgrading Tines

Upgrading from PostgreSQL 14 to PostgreSQL 18

Last updated

PostgreSQL 14 reaches end of life on November 12, 2026. We recommend that you begin migrating to PostgreSQL 18 as soon as possible.

Migrating from PostgreSQL 14 to 18 requires downtime. How long that downtime lasts depends on how much data you have and on the size of the database instance. Larger databases take longer to migrate.

New installs

As of version 43.7.1, Tines supports PostgreSQL 18.

New Helm and Docker Compose installs use the PostgreSQL 18 container we supply. Put a maintenance and backup strategy in place for the database. Use a managed or cloud database for production workloads.

If a cloud provider hosts the database, choose PostgreSQL 18.x. We recommend 18.6 when it is available, or the latest minor version.

Migrating from PostgreSQL 14 to 18

We recommend that you keep three times the size of your database free on the hosts where you run these operations.

The larger the database, the longer the migration takes. Review the size of your database on the Database overview page. If the database is multiple gigabytes, or a terabyte or more, consider reducing retention before you migrate.

Back up PostgreSQL 14

Take a current backup of your PostgreSQL 14 database before you migrate. How you take that backup depends on how you deployed Tines:

  1. Take a virtual machine snapshot of the infrastructure that runs Tines.

  2. Take a backup with your cloud provider:

  3. Take a backup of the docker volume of the database. Back up, restore, or migrate data volumes

Migrate data

pg_upgrade upgrades a PostgreSQL cluster to a new major version without a dump and restore. Major releases change the system catalogs, but the on-disk format of user data rarely changes, so pg_upgrade creates new system tables for PostgreSQL 18 and reuses the existing data files. Stop both servers, install the PostgreSQL 18 binaries, initialize an empty PostgreSQL 18 data directory, and run the PostgreSQL 18 pg_upgrade binary with the old and new data and executable directories. Copy mode is the default and leaves the PostgreSQL 14 cluster unchanged, which is why the host needs room for a second copy of the data. --link hard-links the data files instead, which is faster and uses less disk, but the old cluster cannot be started after the new cluster starts. Run pg_upgrade --check first to confirm the clusters are compatible.

Dump and restore

Use a dump and restore to move the data to a new PostgreSQL 18 database, such as a new container or a managed database.

On a large database, a dump and restore is much slower than pg_upgrade. pg_upgrade reuses the existing data files. A dump and restore copies every row into the new database, so downtime grows with the size of the data. For a database of multiple gigabytes, or a terabyte or more, prefer pg_upgrade when both data directories can share a host.

pg_dump exports a single database to an archive file. It takes a consistent snapshot without blocking other sessions. Use the PostgreSQL 18 version of pg_dump, which can read from a PostgreSQL 14 server.

pg_restore rebuilds a database from that archive. Restore into an empty database on the PostgreSQL 18 server.

Shut down Tines services in the order in Infrastructure maintenance, leaving PostgreSQL running. Then:

  1. Run a dump of the PostgreSQL 14 database using pg_dump.

  2. Restore to the new PostgreSQL 18 database using pg_restore.

  3. Update the Tines DATABASE_HOST to the new host.

  4. Start Tines services.

See Infrastructure maintenance for example pg_dump and pg_restore commands and for how to change DATABASE_HOST.

Migrate a cloud database

When a cloud provider hosts the database, use that provider's major version upgrade. Amazon RDS, Amazon Aurora, Cloud SQL, and Azure Database for PostgreSQL run pg_upgrade on the instance. The instance name and connection endpoint stay the same, so keep the existing DATABASE_HOST.

The upgrade takes the database offline. How long that lasts depends on the size of the database and on the instance. Choose PostgreSQL 18.x. We recommend 18.6 when the provider offers it, or the latest minor version listed as an upgrade target.

  1. Take a current backup with your cloud provider.

  2. Restore that backup to a separate instance and upgrade the copy to PostgreSQL 18.

  3. Shut down Tines services in the order in Infrastructure maintenance.

  4. Upgrade the production instance to PostgreSQL 18.

  5. Re-index and refresh collation if needed, see Post-Migration section below.

  6. Start Tines services.

To move the data to a new instance, use the dump and restore steps above, then update DATABASE_HOST.

Amazon Web Services

Modify the Amazon RDS instance or Amazon Aurora cluster, allow a major version upgrade, and set the engine version to PostgreSQL 18.

Amazon RDS blue/green deployments

A blue/green deployment copies the production RDS instance into a staging environment that stays in sync. Upgrade the staging environment to PostgreSQL 18 while production continues to serve traffic. Test the staging environment, then switch over. RDS stops writes, waits for replication to catch up, and renames the staging endpoint to the production endpoint, so DATABASE_HOST stays the same. The switchover typically finishes in under a minute. Shut down Tines services before the switchover, check if an index rebuild/collation refresh is needed, and start them again after it completes. The previous production instance remains read-only.

Google Cloud

Cloud SQL for PostgreSQL upgrades the major version in place. Run the pre-check, then set the database version to PostgreSQL 18. The instance name and IP address stay the same. To move the data onto a new instance, export it and import it into a PostgreSQL 18 instance.

Microsoft Azure

Azure Database for PostgreSQL flexible server upgrades the major version in place. Run the upgrade validation checks, then upgrade the server to PostgreSQL 18. The server name stays the same. Azure applies the latest minor version it supports for that major version.

Post-Migration

Re-index and refresh collation

After upgrading to PostgreSQL 18, you will more than likely need to re-index and refresh the collation version before starting Tines services again if using a method besides dump and restore. This can be done by connecting to the target database and issuing the following commands:

# If you see the following output when connecting, you need to re-index and refresh collation (versions may be different):
# WARNING:  database "tines_production" has a collation version mismatch
# DETAIL:  The database was created using collation version 2.43, but the operating system provides version 2.44.
# HINT:  Rebuild all objects in this database that use the default collation and run ALTER DATABASE postgres REFRESH COLLATION VERSION, or build PostgreSQL with the right library version.
REINDEX DATABASE CONCURRENTLY tines_production;
ALTER DATABASE tines_production REFRESH COLLATION VERSION;

The database name is typically tines_production. Adjust the previous command replacing tines_production if needed.

PostgreSQL 14 container removal

In a later Tines release, we will remove the PostgreSQL 14 container from our installation methods. Your existing database volumes stay in place.

Was this helpful?