Migration Context and Requirements

GitLab 17.x requires PostgreSQL 14.9+ as minimum version, necessitating an upgrade from currrent 13.6 deployment. This guide documents the in-place upgrade process for a production streaming replication enviroment.

Version Specifications

• Source: PostgreSQL 13.6
• Target: PostgreSQL 14.11

Upgrade Procedure

1. Create parallel installation directories for new version
2. Compile and install PostgreSQL 14.11
3. Initialize new database cluster
4. Perform pre-upgrade checks with pg_upgrade
5. Execute in-place upgrade with downtime
6. Migrate configuration files
7. Update service definitions and environment variables

System Environment

CentOS Linux 7.9 (Core)
PostgreSQL 13.6 on x86_64-pc-linux-gnu

Directory Structure

Original paths under /postgresql get reorganized into version-specific directories:

/opt/postgres/
├── pg13/          # Old version 13.6
│   ├── bin/
│   ├── data/
│   └── archive/
└── pg14/          # New version 14.11
    ├── bin/
    ├── data/
    └── archive/

Compilation and Installation

# Create directory structure
mkdir -p /opt/postgres/{pg13,pg14}/{bin,data,archive}

# Compile PostgreSQL 14.11
tar zxvf postgresql-14.11.tar.gz
cd postgresql-14.11
./configure --prefix=/opt/postgres/pg14 --with-openssl
make
make install

Database Migration

# Initialize new cluster
/opt/postgres/pg14/bin/initdb -D /opt/postgres/pg14/data

# Pre-upgrade check
/opt/postgres/pg14/bin/pg_upgrade \
  -b /opt/postgres/pg13/bin \
  -B /opt/postgres/pg14/bin \
  -d /opt/postgres/pg13/data \
  -D /opt/postgres/pg14/data \
  -c

Service Configuration

Updated systemd unit file:

[Service]
ExecStart=/opt/postgres/pg14/bin/pg_ctl start \
  -D ${PGDATA} -s -o "-p ${PGPORT}" -w -t 300
Environment=PGDATA=/opt/postgres/pg14/data

Configuration Migratino

Key parameters in postgresql.conf:

wal_level = replica
archive_mode = on
archive_command = 'cp %p /opt/postgres/pg14/archive/%f'
max_wal_senders = 10

Post-Upgrade Tasks

# Update environment variables
export PGHOME=/opt/postgres/pg14
export PATH=$PGHOME/bin:$PATH

# Install extension backups
make -C contrib/pg_rman install
pg_rman -B /backup init

Version Compatibility Note

While streaming replication between different versions is possible, this procedure opts for full downtime migration to ensure compatibility. Plan maintenance windows based on database size.