[Proposal] Upgrade the PostgreSQL version from 14 to 16

[chenjinbao1989]

Proposers

No response

Proposal Status

Under Discussion

Abstract

We plan to upgrade the PostgreSQL version from 14 to 16 to leverage the latest features. Maintaining CloudberryDB's kernel version alignment ensures its dependent PostgreSQL components stay within the official maintenance cycle, thereby ensuring continuous access to bug fixes from the PostgreSQL community.

Motivation

The PostgreSQL community, home to the world's foremost database engineers, delivers substantial feature enhancements with each release. Sustaining version parity enables us to consistently benefit from PostgreSQL innovations, whose strategic value may parallel our own feature development efforts.

CloudberryDB's current kernel implementation (PostgreSQL 14) will reach end of life (EOL) next year, after which official security patches and bug fixes will no longer be available from PostgreSQL upstream.

PostgreSQL 15 contains many new features and enhancements, including:

Support for the SQL MERGE command.
Selective publication of tables' contents within logical replication publications, through the ability to specify column lists and row filter conditions.
More options for compression, including support for Zstandard (zstd) compression. This includes support for performing compression on the server side during pg_basebackup.
Support for structured server log output using the JSON format.
Performance improvements, particularly for in-memory and on-disk sorting.

PostgreSQL 16 contains many new features and enhancements, including:

Allow parallelization of FULL and internal right OUTER hash joins
Allow logical replication from standby servers
Allow logical replication subscribers to apply large transactions in parallel
Allow monitoring of I/O statistics using the new pg_stat_io view
Add SQL/JSON constructors and identity functions
Improve performance of vacuum freezing
Add support for regular expression matching of user and database names in pg_hba.conf, and user names in pg_ident.conf

Implementation

Based on historical upgrade patterns, we will execute a dual-phase upgrade process covering both versions 15 and 16. The technical workflow includes:

Merge new version:

git merge REL_16_STABLE && git add -u && git merge --continue

Conflict Resolution:

Manual resolution of merge conflicts from Phase 1
(Estimated: 1 month)

Cluster Initialization:

Bootstrap CloudberryDB clusters and debug fatal errors/panics
(Estimated: 0.5 months)

Test Suite Validation:

Remediate all regression test failures
(Estimated: 3 months)

This kernel modernization initiative is projected to complete within 4-5 months.

Rollout/Adoption Plan

No response

Are you willing to submit a PR?

• Yes I am willing to submit a PR!

[tuhaihe]

I have two questions from here:

• For Cloudberry 2.x, will it also be EOF by 2026, following the PostgreSQL versioning policy¹?
• Will the Cloudberry 3.x be the PG16 built-in, and will it be EOF by 2028?

Moreover, should one GitHub project or Google Sheet be created to help manage the upgrade progress for better transparency?

Footnotes

1. https://www.postgresql.org/support/versioning/ ↩

[chenjinbao1989]

Cloudberry 2.0 will maintain support regardless of PostgreSQL 14s end-of-life (EOL). Both versions 2.0 and 3.0 are committed to long-term support cycles.

[chenjinbao1989]

Greate idea !

I think GitHub Projects is a good tool for PostgreSQL version upgrade work.

A new project named 'Merge postgres 16' has been created for traking the upgrade work.

Merge postgres 16 (view)

[edespino]

Thanks for initiating this important proposal. I fully support the goal of aligning Apache Cloudberry with upstream PostgreSQL enhancements. That said, there are several foundational areas that need clarification and community discussion to ensure the upgrade is successful, maintainable, and inclusive of all stakeholders.

---

🚩 Release Lifecycle Policy: Unclear

The proposal asserts:

"Apache Cloudberry 2.0 will remain supported beyond PostgreSQL 14’s EOL."
"Both 2.0 and 3.0 are planned for long-term support."

However, the project has not yet published or discussed a formal release lifetime policy. This makes it difficult for users, downstream integrators, and commercial adopters to plan around version stability and upgrade timelines.

Key open questions include:

• What does “long-term support” mean in practice?
• Will Apache Cloudberry versions follow PostgreSQL’s ~5-year support window?
• Will maintenance continue for EOL'd upstream kernels via backports or security patches?

📌 Recommendation:
A minimal versioning and support policy should be drafted and published. This can be done by any contributor, committer, or PPMC member, and does not need to be authored by the original proposal writer. Even a placeholder policy would help clarify expectations.

Here’s a suggested draft format to seed discussion:

📄 Example: Minimal Versioning and Support Policy

## Apache Cloudberry Versioning and Support Policy (DRAFT)

Apache Cloudberry follows a major.minor.patch format:

- Major: Kernel upgrades or breaking changes (e.g., PG14 → PG16)
- Minor: Backward-compatible feature additions
- Patch: Bug and security fixes

| Version | PG Base | Status   | Maintenance Target           |
|---------|---------|----------|------------------------------|
| 2.0.x   | PG14    | Active   | Through at least 2027¹       |
| 3.0.x   | PG16    | Planned  | PG16 EOL + 1 year (tentative)|

¹ PG14 EOL is in 2026; Cloudberry 2.0 will continue receiving critical fixes beyond that date.

Upgrades will follow standard PostgreSQL tooling (e.g., `pg_upgrade`) where feasible. Changes to this policy will be proposed on the dev@ mailing list.

---

🔄 Upgrade Path for Users: Not Addressed

There is no mention of how users are expected to upgrade from Apache Cloudberry 2.0 (PG14) to 3.0 (PG16).

Key questions:

• Will in-place upgrades using pg_upgrade be supported?
• Will logical dump/restore be required?
• Are any major compatibility caveats expected (e.g., catalog changes, extension rewrites)?

📌 Recommendation: Outline the expected upgrade path or link to a follow-up issue/mailing list thread where this will be clarified.

---

🌿 Development Workflow and Branching: Needs Clarification

At the time of this proposal, Apache Cloudberry 2.0 has not yet been officially released. As such:

• The main branch is currently tracking work for the 2.0 release.
• A REL_2_STABLE branch will be created when 2.0 is cut.
• The PG16 upgrade work is expected to follow immediately on main.

This raises an important question:

If PG16 work begins directly on main, and this work is long-running, how will that impact other contributors and feature development?
Will it effectively "hold main hostage" for months, making it difficult to keep it in a releasable state?

📌 Recommendation:

• Consider doing PG16 upgrade work in a dedicated feature branch (e.g., pg16-integration) to keep main clean and releasable.
• Allow post-2.0 fixes and small enhancements to continue on main.
• Establish a merge/rebase plan for when PG16 work is production-ready.

Keeping main stable supports CI, release planning, and encourages ongoing community engagement outside the upgrade track.

---

🧪 Test Plan: Needs Clarification

While the proposal estimates ~3 months for regression fixes, it doesn’t specify:

• Whether parallel testing against PG14 and PG16 will be done
• If test framework changes will be required
• What success criteria define a “complete” upgrade

📌 Recommendation: Expand the proposal to include:

• Testing scope across extensions and planner/executor behavior
• Integration with CI for continuous validation
• Clear thresholds for test suite compliance

---

🧩 Extension and Component Coordination: Missing

Apache Cloudberry includes many in-core components and bundled extensions (e.g., PXF, gpfdist, PL languages, workload manager). A PostgreSQL upgrade will almost certainly affect:

• Internal APIs
• Plan node compatibility
• System catalog behavior

📌 Recommendation:

• List all bundled extensions and components expected in 3.x.
• Assign or identify maintainers for each.
• Track PG16 compatibility status (via GitHub issues or a shared audit doc).

---

🌐 Downstream Ecosystem Impact: Private and Commercial Components

Apache Cloudberry is widely used in derivative commercial and private deployments. Many such projects include non-public extensions or downstream forks. These groups depend on kernel compatibility and early visibility.

📌 Recommendation:

• Share this PG16 upgrade plan early via:

  • dev@cloudberry.apache.org mailing list
  • GitHub Discussions or project roadmap
  • Website changelogs or release notes

• Encourage downstream users to validate and share PG16 migration blockers.

---

📊 Tracking and Transparency: Suggested

As noted by @tuhaihe, the community would benefit from centralized tracking of the PG16 upgrade effort.

📌 Recommendation:
Use a GitHub Project board, milestone, or Google Sheet to track:

• Merge status
• Extension compatibility
• Test suite progress
• Contributor assignments and review queues

This improves visibility, onboarding, and roadmap clarity.

---

✅ Summary of Actionable Follow-ups

Area	Recommendation
Release Policy	Draft and publish a minimal versioning & support policy
User Upgrade	Define upgrade process from 2.0 → 3.0
Branching Strategy	Avoid holding main hostage — use a PG16 feature branch
Testing Plan	Clarify testing scope and CI validation strategy
Extension Coordination	Audit bundled components for PG16 compatibility
Downstream Impact	Share the plan early with commercial/private adopters
Transparency	Create shared tracking dashboard for upgrade effort

---

Thanks again for initiating this work. With these additional discussions and supporting plans in place, the PG16 upgrade can move forward in a way that benefits the entire Apache Cloudberry community — from committers to downstream integrators.

Let me know if I can help turn any of these topics into individual GitHub issues or mailing list threads.

[chenjinbao1989]

Hi Ed,

Thank you for helping to sort out the remaining issues. Here are my thoughts on these issues

Release Lifecycle Policy: Unclear

• Thanks for making it clearer. It makes sense to have a minimal versioning and support policy for Cloudberry.
• This deserves a dedicated discussion thread, so we can gather more input. I’d suggest starting a new thread on the Dev mailing list (or GitHub discussion). Would you like to help initiate this discussion? Thanks!

Upgrade Path for Users: Not Addressed

We plan to upgrade using the same method as we did from Greenplum 7 to Cloudberry, using cbcopy.
The upgrade steps are as follows：

• Create a new cluster of Cloudberry 3.0
• Cdbcopy from old cluster to new cluster
• Remove the old cluster
  The upgrade path will be discussed as a separate topic and will not be included in this upgrade work.

Development Workflow and Branching: Needs Clarification

• Merge operations are confined to a dedicated branch, ensuring the main branch remains fully operational for ongoing feature development and the 2.0 release cycle.
• Following conflict resolution and mitigation of critical PANIC errors in test suites, a CI pipeline will be instantiated on the merge branch. This pipeline initially executes only baseline installcheck-parallel tests, with additional test suites progressively activated during remediation efforts until parity with the main branch's testing framework is achieved.
• The merge branch undergoes periodic rebasing against main to maintain synchronization, mirroring standard development practices for seamless future integration.

Test Plan: Needs Clarification

A pipeline including the same test modules as the main branch will be initialized on merge branch. The upgrade should be considered as "complete" when all the tests passed.

Extension and Component Coordination: Missing

The goal of this kernel upgrade is to keep the extensions within the pipeline coverage available. Other in-core extensions will be discussed later.

Downstream Ecosystem Impact: Private and Commercial Components

Kernel upgrades can indeed have a significant impact on non-public extensions or downstream forks. The entire upgrade process will be conducted openly to ensure developers of non-public extensions or downstream forks can adapt their code in a timely manner.
The release of new PostgreSQL versions similarly faces the same challenges. A more universal solution would involve maintaining older versions for an extended lifecycle, allowing downstream developers sufficient time to migrate and adapt to newer releases.

Tracking and Transparency: Suggested

A new project has been initialized to track merge progress. Merge postgres 16 (view)
We should work on cbdb-postgres-merge branch in Cloudberry https://github.com/apache/cloudberry/tree/cbdb-postgres-merge