Upgrade PostgreSQL from 12.0 to 16.8

[atharva-vaish240]

Description

Upgrades the PostgreSQL image used by the local development environment from postgres:12.0 to postgres:16.8.

PostgreSQL 12 has reached end of life and no longer receives security updates. The new version is pinned to a specific minor release to keep the development environment reproducible.

Fixes #791

Migration Note

Important: This update changes PostgreSQL from version 12.0 to 16.8.
PostgreSQL major versions are not compatible at the data-directory level, so
an existing PostgreSQL 12 volume cannot be directly reused with PostgreSQL
16.8.

If you have existing database data that needs to be preserved, back it up
using pg_dump, recreate the PostgreSQL volume, and restore the backup into
the new PostgreSQL 16.8 instance.

Migration Steps

# 1. Create a backup while PostgreSQL 12 is running
docker exec cello-postgres pg_dump -U postgres -d api_engine > backup.sql

# 2. Stop the development environment
docker compose -f docker-compose.dev.yaml down

# 3. Remove the old PostgreSQL data volume
docker volume rm cello_cello-postgres

# 4. Start PostgreSQL 16.8 with a fresh data directory
docker compose -f docker-compose.dev.yaml up -d

# 5. Restore the backup
cat backup.sql | docker exec -i cello-postgres psql -U postgres -d api_engine

Verification

• Update the image tag in docker-compose.dev.yaml

• Run make local and confirm the API engine connects successfully

• Run existing tests with make check-api and confirm no regressions

@yeasy
@snehanair-486

[YoungHypo]

I re-triggered the CI, still failed. Please check it.

[atharva-vaish240]

My branch accidentally included an unrelated Makefile change. I've removed it, fixed the commit, and pushed the updated branch.

I had also verified the PostgreSQL upgrade on a local environment:

make local completed successfully.
PostgreSQL 16.8 started successfully.
make check-api passed on a clean setup.

Kindly re-trigger the CI

If the CI still fails -
From the logs, the first failure is POST /api/v1/nodes returning HTTP 500; the later channel/chaincode failures is a result of it.
Since the PostgreSQL upgrade passes local verification on a clean environment, I'm investigating whether the CI failure is related to the API/Fabric integration rather than the PostgreSQL image change.
@YoungHypo

[yeasy]

Thanks for the upgrade! A few items to address before merging:

1. Title correction: The PR title says '11.1 to 16.8' but the actual change in the files is from postgres:12.0 to postgres:16.8. Please update the title.

2. Migration documentation needed: PostgreSQL major version upgrades are not drop-in replacements. Existing Docker volumes with PG 12 data directories are incompatible with PG 16 and will cause a fatal error on startup. Please add:

   • A note in the PR description about the breaking change for existing users
   • Migration instructions (e.g., pg_dump/pg_restore or pg_upgrade steps)
   • Or at minimum, a warning to delete existing volumes before upgrading

3. Otherwise the change itself is correct and necessary — PG 12 reaches EOL in Nov 2025.

[atharva-vaish240]

@yeasy @YoungHypo
all required tasks done

[yeasy]

Thanks — the original title correction and the basic major-version migration warning are now addressed. I cannot approve this yet because several merge blockers remain.

1. Please update the target from PostgreSQL 16.8 to the current supported PostgreSQL 16 minor release. Version 16.8 has been superseded and remains affected by PostgreSQL issues fixed in later 16.x releases. If reproducibility is the goal, pin the distro variant and multi-architecture digest as well.
2. The migration instructions currently cover only docker-compose.dev.yaml and its named volume, but this PR also changes deployments backed by /opt/cello/pgdata and /opt/cello/postgres. Please document a safe path for every changed deployment: create a new PG16 volume/path, preserve the old PG12 data for rollback, back up databases plus globals/roles, perform a tested restore, check extensions and application/driver compatibility, and remove the old storage only after validation.
3. The current head has not completed CI. Both Lint Check and Integration Tests are action_required with zero jobs. After pushing the fixes, please run both workflows successfully; the previous integration run failed while creating the orderer.
4. Please remove the unrelated cello-hyperledger-fabric-agent network alias change from this PR, or explain why it is required and add corresponding verification.

Once these points are addressed and the current head passes CI, please request another review.

[atharva-vaish240]

@yeasy @YoungHypo
all required tasks done