Tool Upgrade Guides for GDK

This documentation provides standardized procedures for upgrading critical development tools in GDK.

PostgreSQL

This guide covers updating the default PostgreSQL version in GDK. It is intended to be driven by the requesting team (for example, Database Reliability Engineering), with Development Tooling providing review and release support.

Background

GDK’s .tool-versions file lists PostgreSQL versions in priority order. The first version is the default, used for new database creation and gdk update. Additional versions are installed but not active, which lets users compile and verify them before any data migration happens.

Process

Phase 1: Scheduled pipeline testing

1. Set (or confirm) NEXT_POSTGRES_VERSION in _versions.gitlab-ci.yml to the target version. This may already be set from the previous upgrade cycle (see phase 4).

   This enables a nightly scheduled pipeline that installs the target version, runs support/upgrade-postgresql, starts GDK, and verifies the sign-in endpoint responds. Tests run on Linux (in Docker).

2. Monitor integration:postgres-upgrade runs for failures. Create tracking issues for problems that need fixes.

   Common issues to watch for:

   • New build dependencies. PostgreSQL 17 required flex and bison because it stopped shipping pre-generated parser files. Update packages_debian.txt or installation docs as needed ( example).
   • Extension compatibility. Extensions like pgvector may need build fixes for the new major version ( example).

3. Resolve all identified issues and verify fixes pass in the scheduled pipeline before proceeding.

Phase 2: Roll out as secondary version

This phase installs the new version on every developer’s machine without changing which version is active.

1. Update .tool-versions to append the new version as the second entry. If there are more than two PostgreSQL versions listed, consider removing the oldest. For example:

   postgres 16.11 17.8

2. Add a GDK announcement informing users about the new version.

3. Open the MR and assign a Development Tooling reviewer.

   For example, see Add 17.8 to GDK and Add 16.8 to GDK.

4. After merge, monitor the GDK command failure-rate dashboard for installation regressions over the following week.

Phase 3: Make the new version the default

Wait at least one week after phase 2 (longer if installation issues are still being resolved). Once the failure rate is stable at or below baseline, open a single MR that:

1. Moves the new version to the first position in .tool-versions:

   postgres 17.8 16.11

2. Sets postgresql.active_version in gdk.example.yml to the new version.

3. Updates specs that reference the default version. Typically:

   • spec/lib/gdk/config_spec.rb
   • spec/lib/gdk/postgresql_spec.rb
   • spec/lib/gdk/postgresql_upgrader_spec.rb
   • spec/lib/gdk/diagnostic/postgresql_spec.rb
   • spec/lib/gdk/tool_versions_updater_spec.rb
   • spec/spec_helper.rb

Assign a Development Tooling reviewer. After merge, monitor the failure-rate dashboard for at least one week and communicate the change in #gdk on Slack.

For example, see 16.11 to 17.8 and 14.9 to 16.8.

Phase 4: Prepare for the next upgrade

Update NEXT_POSTGRES_VERSION in _versions.gitlab-ci.yml to the next planned major version so scheduled pipeline testing begins early ( example).

Best practices

• Allow at least one week between phases for monitoring.
• Document issues and resolutions. Add example MRs to this guide.
• Watch for new build dependencies when upgrading major versions. Check compilation logs on both Linux and macOS.