Contents

• CLAUDE.md
  • Project Overview
  • Build Commands
  • Development Commands
  • Testing
  • Code Style
  • Architecture
  • Version Compatibility
  • Versioning
  • Reference Projects
  • Useful Skills

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

pg_stat_ch is a PostgreSQL 16+ extension written in C++ that captures query execution telemetry via server hooks and exports it to ClickHouse. The architecture is: hooks (foreground) → shared-memory queue → bgworker exporter → ClickHouse events_raw

All aggregation (p50/p95/p99, top queries, errors) happens in ClickHouse via materialized views, not in the extension.

Build Commands

mise run build              # Debug build (current pg_config)
mise run build:release      # Release build
mise run build:16           # Build for PostgreSQL 16
mise run build:17           # Build for PostgreSQL 17
mise run build:18           # Build for PostgreSQL 18
mise run build:all          # Build for all PG versions
mise run install            # Install the extension
mise run clean              # Clean build artifacts

Development Commands

mise run format             # Format code with clang-format
mise run lint               # Run clang-tidy linting
mise run compdb             # Copy compile_commands.json to root (for IDE)
mise run configure          # Configure with CMake (debug)

Testing

# Via mise (uses PG 18)
mise run test:all           # Run all tests
mise run test:regress       # SQL regression tests
mise run test:tap           # TAP tests (stress, concurrent, overflow)
mise run test:isolation     # Isolation tests (race conditions)

# Via script (specify PG version)
./scripts/run-tests.sh 18 all
./scripts/run-tests.sh 17 regress

Test types: - regress - SQL regression tests in test/regression/ - tap - Perl TAP tests in t/ (stress, concurrent sessions, overflow) - isolation - Race condition tests in specs/

Note: TAP tests require PostgreSQL built with --enable-tap-tests. Mise-installed versions don’t include the Perl test modules; the script skips TAP tests gracefully when unavailable.

# we have a local build of PostgreSQL with tap tests enabled
# so we can run the tap tests against it
./scripts/run-tests.sh ../postgres/install_tap tap

Code Style

• C++17 with Google style guide (.clang-format)
• Column limit: 100, 2-space indent
• postgres.h must be included first in any source file
• Use extern "C" blocks for PostgreSQL C ABI compatibility
• Naming: CamelCase for classes/functions, lower_case for variables, kCamelCase for constants
• No STL in shared memory; use Postgres allocators and shmem APIs

Architecture

Source files: - src/pg_stat_ch.cc - Main entry point with _PG_init() and SQL functions - include/pg_stat_ch/pg_stat_ch.h - Public header with version macro and declarations - sql/pg_stat_ch--0.1.sql - SQL function definitions

Build system: - CMake with presets (default=debug, release) - cmake/FindPostgreSQLServer.cmake - Finds PostgreSQL via pg_config - cmake/CompilerWarnings.cmake - Strict warning flags - cmake/GitVersion.cmake - Version extraction from git

Key PostgreSQL hooks to implement (see pg_stat_ch.md for details): - shmem_request_hook / shmem_startup_hook - Shared memory setup - post_parse_analyze_hook - Capture queryId early - ExecutorStart/Run/Finish/End_hook - Track execution - ProcessUtility_hook - Handle DDL/utility statements - emit_log_hook - Capture errors

Version Compatibility

Use #if PG_VERSION_NUM >= XXXXX for version-specific code: - PG 18+: execute_once removed from ExecutorRun - PG 17+: Unified nesting_level, separate block timing - PG 15+: JIT instrumentation, temp_blk timing

Versioning

Two independent versions exist:

Version	Location	Purpose
Git tag (e.g., v0.1.5)	Release workflow	Build/release artifacts
default_version	pg_stat_ch.control	PostgreSQL extension schema

• Release workflow uses git describe --tags for artifact naming
• Extension version in .control must match SQL filename (e.g., 0.1 → pg_stat_ch--0.1.sql)
• Only bump default_version when SQL interface changes (new functions, types, etc.)
• Schema changes require a migration script: pg_stat_ch--OLD--NEW.sql

Reference Projects

These projects are available in the workspace as references:

• ../pg_stat_monitor - Primary reference for PostgreSQL hook patterns, shared memory management, and query statistics collection. Our hook implementations are based on patterns from this project.
• ../clickhouse-cpp - C++ client library for ClickHouse; reference for HTTP transport to ClickHouse
• ../pg_duckdb - Another PG extension in C++; reference for C++/PostgreSQL integration patterns
• ../postgres - PostgreSQL source code for understanding internal APIs

Useful Skills

• /cpp-review - Review C++ code against Google Style Guide
• /cpp-naming-check - Check naming conventions