Overview

Relevant source files

• doc/src/sgml/catalogs.sgml
• doc/src/sgml/config.sgml
• doc/src/sgml/func.sgml
• doc/src/sgml/high-availability.sgml
• doc/src/sgml/monitoring.sgml
• doc/src/sgml/ref/alter_table.sgml
• doc/src/sgml/ref/create_aggregate.sgml
• doc/src/sgml/ref/create_table.sgml
• src/backend/access/transam/timeline.c
• src/backend/access/transam/xlog.c
• src/backend/access/transam/xlogarchive.c
• src/backend/access/transam/xlogfuncs.c
• src/backend/catalog/Makefile
• src/backend/catalog/partition.c
• src/backend/catalog/pg_aggregate.c
• src/backend/catalog/system_views.sql
• src/backend/cdb/cdbvars.c
• src/backend/commands/aggregatecmds.c
• src/backend/commands/tablecmds.c
• src/backend/gpopt/config/CConfigParamMapping.cpp
• src/backend/gporca/libnaucrates/include/naucrates/traceflags/traceflags.h
• src/backend/nodes/copyfuncs.c
• src/backend/nodes/equalfuncs.c
• src/backend/nodes/outfast.c
• src/backend/nodes/outfuncs.c
• src/backend/nodes/readfast.c
• src/backend/nodes/readfuncs.c
• src/backend/optimizer/path/allpaths.c
• src/backend/optimizer/path/costsize.c
• src/backend/optimizer/path/equivclass.c
• src/backend/optimizer/path/joinpath.c
• src/backend/optimizer/path/joinrels.c
• src/backend/optimizer/path/pathkeys.c
• src/backend/optimizer/plan/analyzejoins.c
• src/backend/optimizer/plan/createplan.c
• src/backend/optimizer/plan/initsplan.c
• src/backend/optimizer/plan/planmain.c
• src/backend/optimizer/plan/planner.c
• src/backend/optimizer/plan/setrefs.c
• src/backend/optimizer/prep/prepjointree.c
• src/backend/optimizer/prep/prepunion.c
• src/backend/optimizer/util/pathnode.c
• src/backend/optimizer/util/relnode.c
• src/backend/parser/gram.y
• src/backend/parser/parse_utilcmd.c
• src/backend/partitioning/partbounds.c
• src/backend/postmaster/pgarch.c
• src/backend/postmaster/pgstat.c
• src/backend/postmaster/postmaster.c
• src/backend/postmaster/syslogger.c
• src/backend/rewrite/rewriteDefine.c
• src/backend/tcop/postgres.c
• src/backend/tcop/utility.c
• src/backend/utils/adt/pgstatfuncs.c
• src/backend/utils/adt/ruleutils.c
• src/backend/utils/cache/partcache.c
• src/backend/utils/cache/relmapper.c
• src/backend/utils/init/globals.c
• src/backend/utils/init/miscinit.c
• src/backend/utils/init/postinit.c
• src/backend/utils/misc/guc-file.l
• src/backend/utils/misc/guc.c
• src/backend/utils/misc/guc_gp.c
• src/backend/utils/misc/postgresql.conf.sample
• src/common/controldata_utils.c
• src/include/access/timeline.h
• src/include/access/xlog.h
• src/include/access/xlog_internal.h
• src/include/catalog/catversion.h
• src/include/catalog/partition.h
• src/include/catalog/pg_aggregate.h
• src/include/catalog/pg_am.h
• src/include/catalog/pg_amop.h
• src/include/catalog/pg_amproc.h
• src/include/catalog/pg_opclass.h
• src/include/catalog/pg_operator.h
• src/include/catalog/pg_opfamily.h
• src/include/catalog/pg_proc.dat
• src/include/catalog/pg_proc.h
• src/include/cdb/cdbvars.h
• src/include/common/controldata_utils.h
• src/include/miscadmin.h
• src/include/nodes/nodes.h
• src/include/nodes/parsenodes.h
• src/include/nodes/plannodes.h
• src/include/optimizer/cost.h
• src/include/optimizer/pathnode.h
• src/include/optimizer/paths.h
• src/include/optimizer/planmain.h
• src/include/optimizer/prep.h
• src/include/parser/kwlist.h
• src/include/partitioning/partbounds.h
• src/include/pgstat.h
• src/include/postmaster/pgarch.h
• src/include/postmaster/postmaster.h
• src/include/postmaster/syslogger.h
• src/include/utils/builtins.h
• src/include/utils/guc.h
• src/include/utils/sync_guc_name.h
• src/include/utils/unsync_guc_name.h
• src/test/regress/expected/alter_table.out
• src/test/regress/expected/create_aggregate.out
• src/test/regress/expected/create_table.out
• src/test/regress/expected/create_table_like.out
• src/test/regress/expected/create_view.out
• src/test/regress/expected/hash_part.out
• src/test/regress/expected/insert.out
• src/test/regress/expected/join.out
• src/test/regress/expected/opr_sanity.out
• src/test/regress/expected/rules.out
• src/test/regress/sql/alter_table.sql
• src/test/regress/sql/create_aggregate.sql
• src/test/regress/sql/create_table.sql
• src/test/regress/sql/create_table_like.sql
• src/test/regress/sql/create_view.sql
• src/test/regress/sql/hash_part.sql
• src/test/regress/sql/insert.sql
• src/test/regress/sql/join.sql
• src/test/regress/sql/opr_sanity.sql
• src/test/regress/sql/rules.sql

Purpose and Scope

This document provides a high-level introduction to Apache Cloudberry, a distributed massively parallel processing (MPP) database system. It covers the overall architecture, core subsystems, and their interactions. For detailed information about specific subsystems, refer to the following pages:

• System Architecture details: System Architecture
• Key Design Concepts (MVCC, WAL, MPP): Key Design Concepts
• Build system specifics: Build System
• Core database engine components: Core Database Engine
• Distributed execution details: Distributed Architecture

What is Apache Cloudberry?

Apache Cloudberry is an open-source distributed relational database management system derived from PostgreSQL and Greenplum. It extends PostgreSQL's single-node architecture with MPP capabilities for parallel query execution across multiple segment servers. The system maintains PostgreSQL compatibility while adding distributed transaction management, parallel query optimization, and shared-nothing data partitioning.

Sources: src/include/catalog/catversion.h54-56 README.md architecture diagrams

PostgreSQL and Greenplum Heritage

Cloudberry builds on PostgreSQL 14 as its foundation, inheriting the query processing pipeline, storage engine, and transaction management systems. The catalog version identifier uses a "3" prefix to distinguish Greenplum/Cloudberry versions from PostgreSQL:

From Greenplum, Cloudberry inherits the distributed MPP architecture, including the Query Dispatcher/Query Executor (QD/QE) model, interconnect layer for data movement, and GUC synchronization mechanisms for distributed configuration management.

Sources: src/include/catalog/catversion.h44-60 src/backend/utils/misc/guc_gp.c1-16

High-Level Architecture

Apache Cloudberry follows a shared-nothing MPP architecture with these primary layers:

Layer	Components	Purpose
Client	psql, libpq, pg_dump	Connection and command submission
Connection	postmaster, authentication	Process forking and security
Coordinator (QD)	Parser, Planner, Dispatcher	Query analysis and coordination
Segments (QE)	Executors, Storage	Parallel data processing
Storage	Heap, Indexes, WAL	Data persistence and durability
Background	bgwriter, checkpointer, walwriter, autovacuum	Maintenance operations

Sources: Architecture Diagram 1, src/backend/postmaster/postmaster.c1-66

Core Architecture Components

Process Model and Lifecycle

The postmaster process src/backend/postmaster/postmaster.c1-66 is the main server process that:

1. Listens for client connections on TCP sockets
2. Forks a dedicated backend process per client connection via BackendStartup()
3. Launches auxiliary processes (bgwriter, checkpointer, walwriter) during initialization
4. Manages process lifecycle and crash recovery

Each backend process runs PostgresMain() src/backend/tcop/postgres.c1-18 to execute the query processing loop.

Sources: src/backend/postmaster/postmaster.c1-373 src/backend/tcop/postgres.c113-152 Architecture Diagram 1

Query Processing Pipeline

The query processing pipeline transforms SQL text through multiple stages:

1. Parsing src/backend/parser/gram.y1-47: base_yyparse() converts SQL into a parse tree using the grammar rules
2. Analysis src/backend/parser/parse_utilcmd.c1-9: Semantic validation and transformation to a query tree
3. Planning src/backend/optimizer/plan/planner.c1-16: The planner() function generates execution plans
   • Standard PostgreSQL planner in src/backend/optimizer/path/allpaths.c
   • Or ORCA optimizer (configurable via GUC optimizer)
4. Distributed Planning src/backend/cdb/cdbllize.c: Adds Motion nodes for data movement between segments
5. Execution: Plan nodes execute via the executor framework

Sources: src/backend/parser/gram.y1-110 src/backend/optimizer/plan/planner.c1-89 src/backend/optimizer/path/allpaths.c1-22 src/backend/optimizer/plan/createplan.c1-42 Architecture Diagram 2

Storage and Durability

All data modifications flow through the Write-Ahead Log (WAL) to ensure durability and enable crash recovery:

The WAL subsystem src/backend/access/transam/xlog.c1-13 is the foundation for ACID properties:

• Write-Ahead Logging: XLogInsertRecord() ensures all changes are logged before data pages are modified
• Durability: XLogWrite() and XLogFlush() persist records to disk
• Recovery: StartupXLOG() replays WAL records after a crash
• Checkpointing: CreateCheckPoint() periodically flushes dirty buffers to reduce recovery time

WAL records are written to segment files in pg_wal/ with a typical size of 16MB per segment.

Sources: src/backend/access/transam/xlog.c1-100 src/backend/storage/buffer/bufmgr.c Architecture Diagram 3

Distributed MPP Architecture

Cloudberry extends PostgreSQL with distributed query execution:

• Query Dispatcher (QD): Runs on the coordinator node, plans queries and dispatches plan slices to segments via CdbDispatchPlan() src/backend/cdb/dispatcher/cdbdisp_query.c
• Query Executors (QE): Run on segment nodes, execute their assigned plan slices on local data partitions
• Data Distribution: Tables are hash-distributed or randomly distributed across segments based on DISTRIBUTED BY clause
• GUC Synchronization: Configuration parameters are synchronized from QD to QEs before query execution src/backend/utils/misc/guc_gp.c112-116
• Motion Nodes: Special plan nodes that transfer data between segments during execution (Redistribute, Broadcast, Gather)
• Interconnect: High-speed data transport layer between segments src/backend/cdb/motion/

Sources: src/backend/cdb/dispatcher/cdbdisp_query.c src/backend/utils/misc/guc_gp.c112-116 src/backend/cdb/cdbllize.c Architecture Diagram 7

Configuration System (GUC)

The Grand Unified Configuration (GUC) system manages all server parameters:

Component	File	Purpose
Core GUC	guc.c	PostgreSQL parameters
GP Extensions	guc_gp.c	Cloudberry/Greenplum-specific parameters
Configuration File	postgresql.conf	Persistent settings
Auto Config	postgresql.auto.conf	ALTER SYSTEM settings
GUC Restore List	gp_guc_restore_list	QD to QE synchronization

Parameters can be set at multiple levels (server start, per-database, per-role, per-session) with different contexts (POSTMASTER, SIGHUP, BACKEND, USERSET).

In distributed mode, the QD maintains gp_guc_restore_list src/backend/utils/misc/guc_gp.c115-116 to track GUC changes that must be dispatched to QE segments.

Sources: src/backend/utils/misc/guc.c1-18 src/backend/utils/misc/guc_gp.c1-116 doc/src/sgml/config.sgml1-50

System Catalogs

PostgreSQL system catalogs store metadata about database objects:

• pg_class: Tables, indexes, sequences, views src/include/catalog/pg_class.h
• pg_proc: Functions and procedures src/include/catalog/pg_proc.h1-20
• pg_attribute: Column definitions
• pg_type: Data types
• pg_operator: Operators
• pg_index: Index definitions

Cloudberry adds Greenplum-specific catalogs:

• gp_segment_configuration: Segment server topology
• gp_distribution_policy: Table distribution policies
• pg_appendonly: Append-optimized table metadata

The catalog version src/include/catalog/catversion.h59 identifies schema compatibility.

Sources: src/include/catalog/pg_proc.h1-162 src/include/catalog/catversion.h44-60 doc/src/sgml/catalogs.sgml1-78

Build and Deployment

The build system supports multiple platforms:

• Unix/Linux: Autotools-based build system with ./configure and make configure.ac
• Windows: Perl-based MSVC project generator src/tools/msvc/Mkvcbuild.pm
• CI/CD: Concourse pipelines automate builds and tests concourse/
• Configuration: ./configure flags enable features like --enable-orca, --with-ssl, --enable-debug

Sources: configure.ac GNUmakefile src/tools/msvc/ Architecture Diagram 5

Key Subsystems Summary

This overview introduced the major components. For detailed documentation, see:

Subsystem	Page	Description
Query Planning	#3.6.2	Standard planner and ORCA optimizer
Transaction Management	#3.4	MVCC, 2PC, distributed transactions
Storage Engine	#3.5	Heap tables, indexes, visibility maps
WAL and Recovery	#3.3	Write-ahead logging and crash recovery
Client Libraries	#4.1	libpq API and frontend/backend protocol
Replication	#5	Physical and logical replication
Autovacuum	#6.3	Automatic maintenance
Distributed Execution	#7	QD/QE coordination and interconnect

Sources: Table of contents JSON structure