libpq_cpp

Modern C++ RAII wrapper around PostgreSQL libpq.

This repository is prepared as a reusable module that can be integrated into a different project, while still being executable standalone for local integration testing.

Project Structure

• src/db/pg.hpp / src/db/pg.cpp: Core wrapper (PgConn, Result, Tx, PgError)
• examples/basic_usage.cpp: Example executable
• tests/integration_smoke.cpp: Integration smoke test (runs against real PostgreSQL)
• docker-compose.yml: Local PostgreSQL service
• .env.example: Environment template

Prerequisites

• CMake 3.20+
• C++17 compiler
  • Windows: MSVC (Visual Studio 2022) or MinGW
  • Linux/macOS: GCC/Clang
• PostgreSQL client development package (libpq)

Install Dependencies

Windows (vcpkg recommended)

vcpkg install libpq:x64-windows

Then configure CMake with the vcpkg toolchain:

cmake -S . -B build `
  -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y build-essential cmake libpq-dev

Fedora

sudo dnf install -y gcc-c++ cmake postgresql-devel

Start PostgreSQL for Integration

1. Copy .env.example to .env and adjust credentials if needed.
2. Start database:

docker compose up -d

3. Verify health:

docker compose ps

Build (Standalone)

Configure

cmake -S . -B build -DLIBPQ_CPP_BUILD_EXAMPLES=ON -DLIBPQ_CPP_BUILD_TESTS=ON

Compile

cmake --build build --config Release

Run Example

Set connection info first:

PowerShell

$env:PG_CONNINFO="host=127.0.0.1 port=5432 dbname=mydb user=myuser password=mypass"

Bash

export PG_CONNINFO="host=127.0.0.1 port=5432 dbname=mydb user=myuser password=mypass"

Run:

./build/example_basic

On multi-config generators (Visual Studio), binary can be under build/Release/.

Run Tests

ctest --test-dir build --output-on-failure

Integration test behavior:

• Creates table if needed
• Inserts one row
• Validates query output
• Rolls back transaction for deterministic state

Install Library (Optional)

cmake --install build --prefix install

Installed items:

• include/db/pg.hpp
• lib/<library files>
• CMake export targets under lib/cmake/libpq_cpp

Integrate Into Another CMake Project

Option A: Add as subdirectory

add_subdirectory(external/libpq_cpp)
target_link_libraries(your_app PRIVATE libpq_cpp::libpq_cpp)

In your source:

#include "db/pg.hpp"

Option B: Use installed package export

After cmake --install ...:

list(APPEND CMAKE_PREFIX_PATH "/path/to/libpq_cpp/install")
find_package(libpq_cpp REQUIRED CONFIG)
target_link_libraries(your_app PRIVATE libpq_cpp::libpq_cpp)

Typical Connection String

host=127.0.0.1 port=5432 dbname=mydb user=myuser password=mypass

If PG_CONNINFO is not set, example and tests use this default.

Common Build Problems

• Could NOT find PostgreSQL:
  • Install libpq dev package.
  • On Windows with vcpkg, pass CMAKE_TOOLCHAIN_FILE.
• Linker errors for PQ* symbols:
  • Ensure your target links to libpq_cpp::libpq_cpp.
  • Ensure find_package(PostgreSQL REQUIRED) succeeds.
• Runtime connection failure:
  • Check docker compose ps.
  • Check credentials in .env and PG_CONNINFO.