Building from Source¶

This guide covers building pgraft from source for development and contributing.

Prerequisites¶

Ensure you have all required dependencies:

PostgreSQL 17+: With development headers
Go 1.21+: For Raft implementation
GCC: C compiler
Make: Build system

See Installation for system-specific installation instructions.

Build Process¶

1. Clone Repository¶

git clone https://github.com/pgelephant/pgraft.git cd pgraft

2. Build¶

make clean make

The build process:

Compiles C sources (src/*.c) to object files
Builds Go library (src/pgraft_go.go) to shared library
Links everything into final pgraft.dylib (or .so on Linux)
Creates extension SQL from pgraft--1.0.sql

3. Install¶

# Find PostgreSQL paths PG_LIB=$(pg_config --libdir) PG_SHARE=$(pg_config --sharedir)  # Install files cp pgraft.dylib $PG_LIB/ cp src/pgraft_go.dylib $PG_LIB/ cp pgraft.control $PG_SHARE/extension/ cp pgraft--1.0.sql $PG_SHARE/extension/

Build Targets¶

Clean Build¶

make clean make

Install After Build¶

make install

Build with Debugging¶

make clean CFLAGS="-g -O0" make

This builds with: - -g: Debug symbols - -O0: No optimization

Verifying Build¶

Check for Errors¶

# Should have no errors make 2>&1 | grep -i error  # Should have no warnings make 2>&1 | grep -i warning

Check Binary¶

# macOS otool -L pgraft.dylib  # Linux ldd pgraft.so  # Should show dependencies on libpq, PostgreSQL, etc.

Test Extension¶

# Start PostgreSQL with extension psql -c "CREATE EXTENSION pgraft;" psql -c "SELECT pgraft_test();"

Development Workflow¶

Edit-Compile-Test Cycle¶

# 1. Edit source files vim src/pgraft_core.c  # 2. Rebuild make clean && make  # 3. Reinstall make install  # 4. Restart PostgreSQL pg_ctl restart -D /path/to/data  # 5. Test psql -c "SELECT pgraft_test();"

Incremental Builds¶

For faster development, you can rebuild only changed files:

# Rebuild only C files (if Go unchanged) make pgraft.dylib  # Rebuild only Go (if C unchanged) cd src go build -buildmode=c-shared -o pgraft_go.dylib pgraft_go.go

Code Organization¶

C Source Files (`src/`)¶

File	Purpose
`pgraft.c`	Main extension entry point, background worker
`pgraft_core.c`	Core Raft interface to Go layer
`pgraft_sql.c`	SQL function implementations
`pgraft_guc.c`	GUC (configuration) parameters
`pgraft_state.c`	State management, shared memory
`pgraft_log.c`	Log replication functions
`pgraft_kv.c`	Key-value store implementation
`pgraft_kv_sql.c`	KV SQL interface
`pgraft_util.c`	Utility functions
`pgraft_go.c`	CGO wrapper for Go library

Header Files (`include/`)¶

File	Purpose
`pgraft_core.h`	Core function declarations
`pgraft_go.h`	Go library interface
`pgraft_guc.h`	GUC declarations
`pgraft_sql.h`	SQL function declarations
`pgraft_state.h`	State structures
`pgraft_log.h`	Log function declarations
`pgraft_kv.h`	KV store declarations

Go Implementation¶

src/pgraft_go.go - Complete Raft implementation (2900+ lines)

Coding Standards¶

pgraft follows PostgreSQL C coding standards:

C89/C90 Compliance¶

/* Correct: Variables at function start */ void my_function(void) {  int result;  char *message;   result = 0;  message = "Hello";  /* ... function code ... */ }  /* Wrong: Variables declared in middle */ void bad_function(void) {  int result = 0;  /* some code */  char *message = "Hello"; /* NOT at start */ }

Comments¶

/* Correct: C-style comments */ /* This is a proper comment */  // Wrong: C++ style comments // This is not allowed

Indentation¶

Tabs only (not spaces)
Tab width: 4 spaces
Opening brace on same line:

/* Correct */ if (condition) {  /* code */ }  /* Wrong */ if (condition) {  /* code */ }

Testing¶

Unit Tests¶

cd examples ./run.sh --destroy ./run.sh --init ./run.sh --status

Manual Testing¶

-- Test basic functionality SELECT pgraft_test(); SELECT pgraft_init(); SELECT pgraft_is_leader();  -- Test cluster operations SELECT pgraft_add_node(2, '127.0.0.1', 7002); SELECT * FROM pgraft_get_cluster_status();

Debugging¶

Enable Debug Output¶

SELECT pgraft_set_debug(true);

Check Logs¶

tail -f $PGDATA/log/postgresql-*.log | grep pgraft

Use GDB¶

# Start PostgreSQL with gdb gdb --args postgres -D /path/to/data  # Set breakpoints (gdb) break pgraft_init (gdb) run  # When breakpoint hit (gdb) backtrace (gdb) print variable_name

Common Debug Points¶

/* Add logging in C code */ elog(LOG, "pgraft: Debug point reached, value=%d", value);  /* Add error logging */ elog(ERROR, "pgraft: Error occurred: %s", error_message);

Contributing¶

See Contributing for guidelines on: - Code style - Pull request process - Testing requirements - Documentation

Performance Profiling¶

CPU Profiling¶

# Use perf on Linux perf record -g postgres perf report  # Use Instruments on macOS instruments -t "Time Profiler" postgres

Memory Profiling¶

# Valgrind valgrind --leak-check=full postgres -D /path/to/data  # macOS Instruments instruments -t "Leaks" postgres

Troubleshooting Build Issues¶

PostgreSQL Headers Not Found¶

# Set PG_CONFIG explicitly export PG_CONFIG=/usr/local/pgsql/bin/pg_config make clean && make

Go Build Fails¶

# Ensure Go modules are downloaded cd src go mod download go mod tidy

Link Errors¶

# Check library paths export DYLD_LIBRARY_PATH=/usr/local/pgsql/lib # macOS export LD_LIBRARY_PATH=/usr/local/pgsql/lib # Linux

Build System Details¶

The Makefile uses PostgreSQL's PGXS build system:

PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) include $(PGXS)

This automatically handles: - Finding PostgreSQL headers - Setting correct compiler flags - Linking with PostgreSQL libraries - Installing to correct directories