C++ PostgreSQL 클라이언트 완벽 가이드 | libpq·libpqxx
이 글의 핵심
C++에서 PostgreSQL 연동: libpq·libpqxx 설치·연결, CRUD·트랜잭션·Prepared Statement 실전 코드. "주문·결제 데이터를 안전하게 저장해야 하는데, 어떻게 하죠?" "사용자 입력을 그대로 쿼리에 넣으면 SQL injection 위험이 있어요.
들어가며: C++에서 PostgreSQL을 왜 쓰나요?
핵심 질문
"주문·결제 데이터를 안전하게 저장해야 하는데, 어떻게 하죠?"
"사용자 입력을 그대로 쿼리에 넣으면 SQL injection 위험이 있어요."
"DB 연결이 끊어지면 재연결·재시도 로직을 어떻게 구현하나요?"PostgreSQL은 ACID를 보장하는 관계형 DB로, C++ 서버에서 주문·결제·재고, 복잡한 JOIN·트랜잭션, Prepared Statement를 통해 안전하고 효율적인 데이터 처리를 가능하게 합니다. 이 글은 libpq(C 기반, PostgreSQL 공식)와 libpqxx(Modern C++ 래퍼)를 사용해 PostgreSQL을 C++에서 연동하는 완전한 가이드입니다.
이 글을 읽으면:
- libpq·libpqxx 설치 및 기본 연결을 할 수 있습니다.
- CRUD, 트랜잭션, Prepared Statement 등 실전 패턴을 구현할 수 있습니다.
- Connection refused, SQL injection, 메모리 누수 등 흔한 에러를 해결할 수 있습니다.
- 성능 최적화와 프로덕션 배포 패턴을 적용할 수 있습니다.
요구 환경: C++17 이상, PostgreSQL 11 이상 권장
실무 적용 경험: 이 글은 대규모 C++ 프로젝트에서 실제로 겪은 문제와 해결 과정을 바탕으로 작성되었습니다. 책이나 문서에서 다루지 않는 실전 함정과 디버깅 팁을 포함합니다.
문제 시나리오
시나리오 1: 주문·결제 시 데이터 일관성
"주문 생성 후 결제 실패 시, 주문 상태를 어떻게 롤백하죠?"
"재고 차감과 주문 생성이 동시에 실패하면 안 돼요."상황: 주문 생성과 결제 처리, 재고 차감이 여러 테이블에 걸쳐 있습니다. 중간에 실패하면 부분 커밋으로 데이터 불일치가 발생합니다.
해결 포인트: PostgreSQL 트랜잭션(BEGIN/COMMIT/ROLLBACK)으로 원자적 처리. libpqxx의 pqxx::work로 RAII 기반 자동 롤백 처리.
시나리오 2: SQL Injection 방지
"사용자 입력을 그대로 쿼리에 넣으면 위험하다고 들었어요."
"문자열 이스케이프를 어떻게 하죠?"상황: "SELECT * FROM users WHERE name = '" + userInput + "'" 같은 문자열 연결은 SQL injection에 취약합니다.
해결 포인트: Prepared Statement로 파라미터 바인딩. $1, $2 플레이스홀더에 값을 바인딩하면 이스케이프가 자동 처리됩니다.
시나리오 3: 연결 풀 부족
"동시 요청이 많아지면 'too many connections' 에러가 나요."
"매 요청마다 새 연결을 만들면 느려요."상황: 웹 서버가 요청마다 새 DB 연결을 생성하면, PostgreSQL max_connections 한도에 도달하고 연결 오버헤드로 지연이 발생합니다.
해결 포인트: 연결 풀로 연결 재사용. libpqxx 또는 PgBouncer와 함께 사용.
시나리오 4: 대용량 결과 처리
"10만 건 조회 시 메모리가 폭발해요."상황: SELECT * FROM logs로 대량 조회 시 전체 결과를 메모리에 로드하면 OOM이 발생합니다.
해결 포인트: 커서(Cursor) 또는 스트리밍으로 청크 단위 처리. libpqxx의 stream_from 사용.
시나리오 5: 연결 끊김·재연결
"DB 서버 재시작 후 앱이 계속 에러를 내요."상황: 장시간 유지 연결이 DB 재시작이나 네트워크로 끊기면, 이후 쿼리가 실패합니다.
해결 포인트: Health Check 및 재연결 로직. PQstatus() 체크 후 PQreset() 또는 새 연결 생성.
시나리오별 권장 패턴
| 시나리오 | 해결책 | C++ 라이브러리 |
|---|---|---|
| 트랜잭션 | BEGIN/COMMIT/ROLLBACK | libpqxx::work |
| SQL injection | Prepared Statement | libpqxx::prepare |
| 연결 풀 | Connection Pool | libpqxx, PgBouncer |
| 대용량 조회 | Cursor/스트리밍 | libpqxx::stream_from |
| 재연결 | PQstatus + PQreset | libpq |
목차
- 환경 설정 및 설치
- libpq 기본 연결 및 CRUD
- libpqxx Modern C++ 클라이언트
- 완전한 PostgreSQL C++ 예제
- 자주 발생하는 에러와 해결법
- 성능 최적화 팁
- 프로덕션 패턴
- 구현 체크리스트
1. 환경 설정 및 설치
PostgreSQL 서버 실행
# Docker로 PostgreSQL 실행 (권장)
docker run -d -p 5432:5432 \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=mydb \
postgres:16-alpine
# 또는 로컬 설치 후
pg_ctl -D /usr/local/var/postgres startlibpq 설치
libpq는 PostgreSQL 공식 C 클라이언트 라이브러리입니다.
# Ubuntu/Debian
sudo apt-get install libpq-dev
# macOS (Homebrew)
brew install libpq
# vcpkg
vcpkg install libpqlibpqxx 설치
libpqxx는 libpq 위에 구축된 공식 C++ 래퍼입니다.
# vcpkg (권장)
vcpkg install libpqxx
# Ubuntu/Debian
sudo apt-get install libpqxx-dev
# macOS (Homebrew)
brew install libpqxx
# 또는 소스 빌드
git clone https://github.com/jtv/libpqxx.git
cd libpqxx
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make && sudo make installCMake 연동 예시
# CMakeLists.txt - libpq 사용
cmake_minimum_required(VERSION 3.16)
project(postgres_demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
find_package(PostgreSQL REQUIRED)
add_executable(pq_demo main.cpp)
target_link_libraries(pq_demo PRIVATE PostgreSQL::PostgreSQL)# CMakeLists.txt - libpqxx 사용
cmake_minimum_required(VERSION 3.16)
project(postgres_demo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
find_package(libpqxx REQUIRED)
add_executable(pqxx_demo main.cpp)
target_link_libraries(pqxx_demo PRIVATE libpqxx::pqxx)2. libpq 기본 연결 및 CRUD
아키텍처 다이어그램
flowchart TB
subgraph App[C++ 애플리케이션]
Main[main]
Client[PgClient]
end
subgraph Libpq[libpq]
Conn[PGconn]
Result[PGresult]
Exec[PQexec]
end
subgraph PG[PostgreSQL 서버]
DB[(데이터베이스)]
end
Main --> Client
Client --> Conn
Client --> Exec
Exec --> Result
Conn -->|TCP 5432| DB
연결 문자열 (Connection String)
postgresql://user:password@host:port/dbnameuser: DB 사용자password: 비밀번호host: 호스트 (127.0.0.1 또는 로컬)port: 포트 (기본 5432)dbname: 데이터베이스 이름
기본 연결 (RAII)
// libpq_basic.cpp
// 컴파일: g++ -std=c++17 -o pq_basic libpq_basic.cpp -lpq
#include <libpq-fe.h>
#include <iostream>
#include <memory>
#include <stdexcept>
#include <string>
struct PgConnection {
PGconn* conn = nullptr;
PgConnection(const char* conninfo) {
conn = PQconnectdb(conninfo);
if (conn == nullptr) {
throw std::runtime_error("PostgreSQL 연결 할당 실패");
}
if (PQstatus(conn) != CONNECTION_OK) {
std::string err = PQerrorMessage(conn);
PQfinish(conn);
throw std::runtime_error("PostgreSQL 연결 실패: " + err);
}
}
~PgConnection() {
if (conn) PQfinish(conn);
}
PgConnection(const PgConnection&) = delete;
PgConnection& operator=(const PgConnection&) = delete;
};
int main() {
try {
PgConnection conn("host=127.0.0.1 port=5432 dbname=mydb user=postgres password=postgres");
// 테이블 생성
PGresult* res = PQexec(conn.conn, "CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name VARCHAR(100), email VARCHAR(100))");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
std::cerr << "CREATE TABLE 에러: " << PQerrorMessage(conn.conn) << "\n";
PQclear(res);
return 1;
}
PQclear(res);
// INSERT
res = PQexecParams(conn.conn,
"INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id",
2, nullptr, (const char*[]){"홍길동", "[email protected]"},
nullptr, nullptr, 0);
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
std::cerr << "INSERT 에러: " << PQerrorMessage(conn.conn) << "\n";
PQclear(res);
return 1;
}
std::cout << "INSERT 성공, id: " << PQgetvalue(res, 0, 0) << "\n";
PQclear(res);
// SELECT
res = PQexec(conn.conn, "SELECT id, name, email FROM users");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
std::cerr << "SELECT 에러: " << PQerrorMessage(conn.conn) << "\n";
PQclear(res);
return 1;
}
int rows = PQntuples(res);
for (int i = 0; i < rows; ++i) {
std::cout << PQgetvalue(res, i, 0) << " | "
<< PQgetvalue(res, i, 1) << " | "
<< PQgetvalue(res, i, 2) << "\n";
}
PQclear(res);
} catch (const std::exception& e) {
std::cerr << "에러: " << e.what() << "\n";
return 1;
}
return 0;
}PQexecParams로 파라미터 바인딩 (SQL Injection 방지)
// PQexecParams: $1, $2 플레이스홀더에 값을 바인딩
// - SQL injection 방지
// - 타입 안전성
// - 쿼리 플랜 재사용
const char* paramValues[] = {userName.c_str(), userEmail.c_str()};
const int paramLengths[] = {static_cast<int>(userName.size()), static_cast<int>(userEmail.size())};
const int paramFormats[] = {0, 0}; // 0 = 텍스트
PGresult* res = PQexecParams(conn,
"INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id",
2, nullptr, paramValues, paramLengths, paramFormats, 0);PGresult RAII 래퍼
// pg_result_guard.hpp
#pragma once
#include <libpq-fe.h>
#include <utility>
struct PgResultGuard {
PGresult* res = nullptr;
explicit PgResultGuard(PGresult* r) : res(r) {}
~PgResultGuard() { if (res) PQclear(res); }
PgResultGuard(const PgResultGuard&) = delete;
PgResultGuard& operator=(const PgResultGuard&) = delete;
PgResultGuard(PgResultGuard&& other) noexcept : res(std::exchange(other.res, nullptr)) {}
PGresult* get() const { return res; }
PGresult* operator->() const { return res; }
};3. libpqxx Modern C++ 클라이언트
연결 및 기본 사용
// libpqxx_basic.cpp
// vcpkg install libpqxx 후 컴파일
#include <pqxx/pqxx>
#include <iostream>
#include <string>
int main() {
try {
pqxx::connection conn("host=127.0.0.1 port=5432 dbname=mydb user=postgres password=postgres");
// 테이블 생성
pqxx::work w(conn);
w.exec("CREATE TABLE IF NOT EXISTS products (id SERIAL PRIMARY KEY, name VARCHAR(100), price INTEGER)");
w.commit();
// INSERT
pqxx::work w2(conn);
w2.exec_params("INSERT INTO products (name, price) VALUES ($1, $2) RETURNING id",
"상품A", 9900);
w2.commit();
// SELECT
pqxx::read_transaction r(conn);
pqxx::result res = r.exec("SELECT id, name, price FROM products");
for (auto row : res) {
std::cout << row[0].as<int>() << " | "
<< row[1].as<std::string>() << " | "
<< row[2].as<int>() << "\n";
}
} catch (const pqxx::sql_error& e) {
std::cerr << "SQL 에러: " << e.what() << "\n쿼리: " << e.query() << "\n";
return 1;
} catch (const std::exception& e) {
std::cerr << "에러: " << e.what() << "\n";
return 1;
}
return 0;
}트랜잭션 (RAII 자동 롤백)
// pqxx::work: 트랜잭션. commit() 호출 시 커밋, 예외 시 자동 롤백
pqxx::work w(conn);
try {
w.exec_params("INSERT INTO orders (user_id, amount) VALUES ($1, $2)", 1, 10000);
w.exec_params("UPDATE inventory SET stock = stock - 1 WHERE product_id = $1", 1);
w.commit(); // 성공 시 커밋
} catch (...) {
// w 소멸 시 자동 ROLLBACK
throw;
}Prepared Statement
// Prepared Statement: 쿼리 플랜 재사용, SQL injection 방지
conn.prepare("get_user", "SELECT id, name FROM users WHERE id = $1");
conn.prepare("insert_order", "INSERT INTO orders (user_id, amount) VALUES ($1, $2) RETURNING id");
pqxx::work w(conn);
pqxx::result r = w.prepared("get_user")(user_id).exec();
pqxx::result r2 = w.prepared("insert_order")(user_id)(amount).exec();libpq vs libpqxx 비교
| 항목 | libpq | libpqxx |
|---|---|---|
| 언어 | C | C++11/14/17 |
| 의존성 | 없음 (libpq만) | libpq |
| 트랜잭션 | 수동 BEGIN/COMMIT | pqxx::work RAII |
| 결과 처리 | PQgetvalue, 수동 | row.as |
| Prepared | PQprepare | conn.prepare() |
| 예외 | 없음 (return code) | 예외 기반 |
4. 완전한 PostgreSQL C++ 예제
예제 1: CRUD 래퍼 클래스 (libpqxx)
// user_repository.hpp
#pragma once
#include <pqxx/pqxx>
#include <optional>
#include <string>
#include <vector>
struct User {
int id;
std::string name;
std::string email;
};
class UserRepository {
public:
explicit UserRepository(pqxx::connection& conn) : conn_(conn) {}
std::optional<User> findById(int id) {
pqxx::read_transaction r(conn_);
conn_.prepare("find_user", "SELECT id, name, email FROM users WHERE id = $1");
auto res = r.prepared("find_user")(id).exec();
if (res.empty()) return std::nullopt;
auto row = res[0];
return User{
row[0].as<int>(),
row[1].as<std::string>(),
row[2].as<std::string>()
};
}
int insert(const std::string& name, const std::string& email) {
pqxx::work w(conn_);
conn_.prepare("insert_user", "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING id");
auto res = w.prepared("insert_user")(name)(email).exec();
int id = res[0][0].as<int>();
w.commit();
return id;
}
bool update(int id, const std::string& name, const std::string& email) {
pqxx::work w(conn_);
conn_.prepare("update_user", "UPDATE users SET name = $1, email = $2 WHERE id = $3");
auto res = w.prepared("update_user")(name)(email)(id).exec();
bool ok = res.affected_rows() > 0;
w.commit();
return ok;
}
bool remove(int id) {
pqxx::work w(conn_);
conn_.prepare("delete_user", "DELETE FROM users WHERE id = $1");
auto res = w.prepared("delete_user")(id).exec();
bool ok = res.affected_rows() > 0;
w.commit();
return ok;
}
private:
pqxx::connection& conn_;
};예제 2: 주문·결제 트랜잭션 (원자적 처리)
// order_service.cpp
#include <pqxx/pqxx>
#include <stdexcept>
#include <string>
struct OrderResult {
int order_id;
bool success;
std::string error_message;
};
OrderResult createOrderWithPayment(pqxx::connection& conn,
int user_id,
int product_id,
int quantity,
int amount) {
pqxx::work w(conn);
try {
conn.prepare("insert_order", "INSERT INTO orders (user_id, product_id, quantity, amount) VALUES ($1, $2, $3, $4) RETURNING id");
conn.prepare("update_inventory", "UPDATE inventory SET stock = stock - $1 WHERE product_id = $2 AND stock >= $1");
conn.prepare("insert_payment", "INSERT INTO payments (order_id, amount) VALUES ($1, $2)");
auto order_res = w.prepared("insert_order")(user_id)(product_id)(quantity)(amount).exec();
int order_id = order_res[0][0].as<int>();
auto inv_res = w.prepared("update_inventory")(quantity)(product_id).exec();
if (inv_res.affected_rows() == 0) {
throw std::runtime_error("재고 부족");
}
w.prepared("insert_payment")(order_id)(amount).exec();
w.commit();
return {order_id, true, ""};
} catch (const std::exception& e) {
// w 소멸 시 자동 ROLLBACK
return {0, false, e.what()};
}
}예제 3: 대용량 데이터 스트리밍 (stream_from)
// bulk_insert.cpp
// libpqxx stream_from: 청크 단위로 대량 INSERT
#include <pqxx/pqxx>
#include <vector>
#include <string>
void bulkInsertProducts(pqxx::connection& conn,
const std::vector<std::pair<std::string, int>>& products) {
pqxx::work w(conn);
w.exec("CREATE TABLE IF NOT EXISTS products (id SERIAL PRIMARY KEY, name VARCHAR(100), price INTEGER)");
w.commit();
pqxx::stream_from stream(w, "products", std::vector<std::string>{"name", "price"});
for (const auto& [name, price] : products) {
stream << name << price;
}
stream.complete();
w.commit();
}
// stream_to: SELECT 결과를 스트리밍으로 읽기
void streamLargeResult(pqxx::connection& conn) {
pqxx::read_transaction r(conn);
for (auto [id, name, price] : r.stream<int, std::string, int>(
"SELECT id, name, price FROM products")) {
// 10만 건이어도 한 번에 메모리에 로드하지 않음
std::cout << id << " " << name << " " << price << "\n";
}
}예제 4: 연결 풀 (간단한 구현)
// connection_pool.hpp
#pragma once
#include <pqxx/pqxx>
#include <condition_variable>
#include <mutex>
#include <queue>
#include <string>
class ConnectionPool {
public:
ConnectionPool(const std::string& conninfo, size_t pool_size = 10)
: conninfo_(conninfo) {
for (size_t i = 0; i < pool_size; ++i) {
pool_.push(std::make_unique<pqxx::connection>(conninfo_));
}
}
std::unique_ptr<pqxx::connection> acquire() {
std::unique_lock lock(mutex_);
cv_.wait(lock, [this] { return !pool_.empty(); });
auto conn = std::move(pool_.front());
pool_.pop();
return conn;
}
void release(std::unique_ptr<pqxx::connection> conn) {
if (!conn) return;
std::lock_guard lock(mutex_);
pool_.push(std::move(conn));
cv_.notify_one();
}
private:
std::string conninfo_;
std::queue<std::unique_ptr<pqxx::connection>> pool_;
std::mutex mutex_;
std::condition_variable cv_;
};예제 5: 재연결 로직 (libpq)
// reconnect.cpp
#include <libpq-fe.h>
#include <chrono>
#include <iostream>
#include <thread>
PGconn* ensureConnection(PGconn* conn, const char* conninfo) {
if (conn && PQstatus(conn) == CONNECTION_OK) {
return conn;
}
if (conn) {
PQfinish(conn);
}
conn = PQconnectdb(conninfo);
if (PQstatus(conn) != CONNECTION_OK) {
std::cerr << "재연결 실패: " << PQerrorMessage(conn) << "\n";
PQfinish(conn);
return nullptr;
}
return conn;
}
// 또는 PQreset: 기존 연결 리소스 재사용
bool resetConnection(PGconn* conn) {
if (PQstatus(conn) != CONNECTION_OK) {
PQreset(conn);
return PQstatus(conn) == CONNECTION_OK;
}
return true;
}5. 자주 발생하는 에러와 해결법
에러 1: Connection refused / Connection timed out
증상: PQconnectdb 실패, PQerrorMessage에 “Connection refused” 또는 “Connection timed out”
원인:
- PostgreSQL 서버가 실행 중이 아님
- 잘못된 호스트/포트
- 방화벽 차단
pg_hba.conf에서 클라이언트 IP 미허용
해결법:
// ❌ 잘못된 설정
PgConnection conn("host=wronghost port=5432 dbname=mydb"); // 잘못된 호스트
// ✅ 연결 문자열 검증
const char* conninfo = "host=127.0.0.1 port=5432 dbname=mydb user=postgres password=postgres connect_timeout=5";
PGconn* conn = PQconnectdb(conninfo);
if (PQstatus(conn) != CONNECTION_OK) {
std::cerr << "연결 실패: " << PQerrorMessage(conn) << "\n";
PQfinish(conn);
}# PostgreSQL 서버 확인
pg_isready -h 127.0.0.1 -p 5432
# exit 0이면 정상에러 2: PQclear 누락으로 메모리 누수
증상: 장시간 실행 시 메모리 사용량이 계속 증가
원인: PQexec/PQexecParams가 반환하는 PGresult*를 PQclear로 해제하지 않음
// ❌ 메모리 누수
PGresult* res = PQexec(conn, "SELECT * FROM users");
// ... 사용 ...
// PQclear(res) 누락!해결법:
// ✅ RAII 래퍼 사용
PgResultGuard guard(PQexec(conn, "SELECT * FROM users"));
PGresult* res = guard.get();
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
return;
}
// guard 소멸 시 자동 PQclear에러 3: SQL Injection
증상: 악의적 사용자 입력으로 인해 데이터 유출 또는 삭제
원인: 사용자 입력을 문자열 연결로 쿼리에 직접 삽입
// ❌ SQL injection 취약
std::string query = "SELECT * FROM users WHERE name = '" + userInput + "'";
PQexec(conn, query.c_str());
// userInput = "'; DROP TABLE users; --" 이면 테이블 삭제됨해결법:
// ✅ PQexecParams 또는 Prepared Statement 사용
const char* paramValues[] = {userInput.c_str()};
PQexecParams(conn, "SELECT * FROM users WHERE name = $1", 1, nullptr, paramValues, nullptr, nullptr, 0);
// libpqxx
conn.prepare("get_user", "SELECT * FROM users WHERE name = $1");
r.prepared("get_user")(userInput).exec();에러 4: too many connections
증상: (error) FATAL: sorry, too many clients already
원인: PostgreSQL max_connections 한도 초과 (기본 100)
해결법:
- 연결 풀 사용: 연결 재사용
- PgBouncer 도입: 연결 풀링 프록시
max_connections증가 (PostgreSQL 설정)
// ✅ 연결 풀 사용
ConnectionPool pool("host=127.0.0.1 dbname=mydb user=postgres password=postgres", 10);
auto conn = pool.acquire();
// ... 사용 ...
pool.release(std::move(conn));에러 5: 트랜잭션 중 연결 끊김
증상: PQexec 실패, “connection lost” 또는 “server closed the connection”
원인: 트랜잭션 진행 중 DB 재시작이나 네트워크 끊김
해결법:
// ✅ 재시도 전 PQreset 또는 새 연결
PGresult* res = PQexec(conn, "SELECT ...");
if (res == nullptr || PQresultStatus(res) == PGRES_FATAL_ERROR) {
if (PQstatus(conn) != CONNECTION_OK) {
PQreset(conn);
if (PQstatus(conn) != CONNECTION_OK) {
// 새 연결 생성 또는 에러 반환
}
}
// 재시도
}에러 6: NULL 값 처리
증상: PQgetvalue가 NULL 반환 시 std::stoi 등에서 크래시
원인: DB 컬럼이 NULL일 수 있는데 NULL 체크 없이 사용
// ❌ NULL 미처리
int id = std::stoi(PQgetvalue(res, 0, 0)); // NULL이면 "NULL" 문자열이 아님, PQgetisnull 확인 필요
// ✅ NULL 체크
if (PQgetisnull(res, 0, 0)) {
// NULL 처리
} else {
int id = std::stoi(PQgetvalue(res, 0, 0));
}// libpqxx: row[0].is_null() 체크
if (row[0].is_null()) {
// NULL 처리
} else {
int id = row[0].as<int>();
}에러 7: 동일 연결을 멀티스레드에서 공유
증상: 간헐적 크래시, 잘못된 결과
원인: libpq PGconn은 스레드 안전하지 않음
// ❌ 위험
PGconn* conn = PQconnectdb(conninfo);
std::thread t1([&]() { PQexec(conn, "SELECT 1"); });
std::thread t2([&]() { PQexec(conn, "SELECT 2"); });해결법:
// ✅ 스레드당 연결 또는 연결 풀
void worker() {
thread_local pqxx::connection conn(conninfo);
pqxx::work w(conn);
w.exec("SELECT ...");
}6. 성능 최적화 팁
팁 1: Prepared Statement 사용
동일 쿼리를 반복 실행할 때 Prepared Statement로 쿼리 플랜 재사용. 파싱·플랜 최적화 비용을 줄입니다.
// ❌ 매번 파싱
for (int i = 0; i < 1000; ++i) {
w.exec_params("SELECT * FROM users WHERE id = $1", i);
}
// ✅ Prepared Statement
conn.prepare("get_user", "SELECT * FROM users WHERE id = $1");
for (int i = 0; i < 1000; ++i) {
w.prepared("get_user")(i).exec();
}팁 2: COPY로 대량 INSERT
단일 INSERT 대신 COPY로 대량 배치 삽입 시 10~100배 빠름.
// libpqxx stream_to
pqxx::work w(conn);
pqxx::stream_to stream(w, "products", std::vector<std::string>{"name", "price"});
for (const auto& [name, price] : products) {
stream << name << price;
}
stream.complete();
w.commit();팁 3: 연결 풀 사용
매 요청마다 새 연결을 만들면 TCP 핸드셰이크·인증 비용이 큽니다. 연결 풀로 재사용하세요.
// libpqxx: ConnectionPool 사용 또는 PgBouncer팁 4: 대용량 결과는 스트리밍
10만 건 이상 조회 시 pqxx::stream 또는 stream_from 사용
// ❌ 전체 메모리 로드
pqxx::result res = r.exec("SELECT * FROM large_table");
// 10만 건 * 1KB = 100MB 이상
// ✅ 스트리밍
for (auto [id, name] : r.stream<int, std::string>("SELECT id, name FROM large_table")) {
process(id, name);
}팁 5: 인덱스 활용
-- 자주 조회하는 컬럼에 인덱스
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_orders_user_id ON orders(user_id);팁 6: 배치 커밋
대량 INSERT 시 INSERT ... VALUES (...), (...), (...) 여러 행을 한 번에 처리
// 1000건을 100건씩 묶어서 INSERT
std::string values;
for (size_t i = 0; i < batch.size(); i += 100) {
values.clear();
for (size_t j = i; j < std::min(i + 100, batch.size()); ++j) {
if (j > i) values += ",";
values += "('" + escape(batch[j].name) + "'," + std::to_string(batch[j].price) + ")";
}
w.exec("INSERT INTO products (name, price) VALUES " + values);
}
w.commit();7. 프로덕션 패턴
패턴 1: Health Check 및 재연결
bool isConnectionHealthy(pqxx::connection& conn) {
try {
pqxx::nontransaction n(conn);
n.exec("SELECT 1");
return true;
} catch (...) {
return false;
}
}
void ensureConnection(pqxx::connection& conn, const std::string& conninfo) {
if (!isConnectionHealthy(conn)) {
conn.close();
conn = pqxx::connection(conninfo);
}
}패턴 2: 설정 외부화
struct PgConfig {
std::string host = "127.0.0.1";
int port = 5432;
std::string dbname = "mydb";
std::string user = "postgres";
std::string password;
};
PgConfig loadFromEnv() {
PgConfig c;
if (const char* h = std::getenv("PGHOST")) c.host = h;
if (const char* p = std::getenv("PGPORT")) c.port = std::stoi(p);
if (const char* d = std::getenv("PGDATABASE")) c.dbname = d;
if (const char* u = std::getenv("PGUSER")) c.user = u;
if (const char* pw = std::getenv("PGPASSWORD")) c.password = pw;
return c;
}
std::string toConnectionString(const PgConfig& c) {
return "host=" + c.host + " port=" + std::to_string(c.port) +
" dbname=" + c.dbname + " user=" + c.user +
" password=" + c.password;
}패턴 3: 재시도 로직 (지수 백오프)
template <typename Func>
auto retryWithBackoff(Func&& f, int max_retries = 3) {
for (int i = 0; i < max_retries; ++i) {
try {
return f();
} catch (const pqxx::sql_error& e) {
if (i == max_retries - 1) throw;
std::this_thread::sleep_for(std::chrono::milliseconds(100 * (1 << i)));
}
}
throw std::runtime_error("재시도 실패");
}
// 사용
retryWithBackoff([&]() {
pqxx::work w(conn);
w.exec("INSERT INTO ...");
w.commit();
});패턴 4: 로깅 및 모니터링
class LoggingConnection {
public:
pqxx::result exec(const std::string& query) {
auto start = std::chrono::steady_clock::now();
auto res = conn_.exec(query);
auto elapsed = std::chrono::steady_clock::now() - start;
log("Query: " + query + " elapsed: " + std::to_string(elapsed.count()) + "ms");
return res;
}
private:
pqxx::connection conn_;
};패턴 5: 트랜잭션 격리 수준
// READ COMMITTED (기본) | REPEATABLE READ | SERIALIZABLE
pqxx::work w(conn);
w.exec("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
w.commit();8. 구현 체크리스트
환경 설정
- PostgreSQL 서버 실행 확인 (
pg_isready) - libpq 또는 libpqxx 설치
- CMake/vcpkg 연동
연결 및 기본 사용
-
PQconnectdb또는pqxx::connection으로 연결 - RAII로
PGconn/PGresult관리 -
PQclear누락 없이 호출 (libpq)
에러 처리
-
PQstatus(conn) != CONNECTION_OK체크 -
PQresultStatus(res)체크 -
pqxx::sql_error예외 처리
보안
- Prepared Statement 또는
PQexecParams사용 (SQL injection 방지) - 비밀번호 환경 변수 사용
성능
- 연결 풀 또는 스레드당 연결
- Prepared Statement로 반복 쿼리 최적화
- 대용량 조회 시 스트리밍
프로덕션
- Health Check 주기적 수행, 재연결·재시도 정책
정리
| 항목 | libpq | libpqxx |
|---|---|---|
| 용도 | C 호환, 경량, 임베디드 | Modern C++, 풍부한 API |
| 연결 | PGconn 직접 관리 | pqxx::connection |
| 트랜잭션 | 수동 BEGIN/COMMIT | pqxx::work RAII |
| 에러 | return code | 예외 기반 |
| 권장 | 레거시, 최소 의존성 | 신규 프로젝트 |
핵심 원칙:
- RAII로 연결·결과 관리
- Prepared Statement로 SQL injection 방지
- 멀티스레드에서는 연결 풀 또는 스레드당 연결
- 트랜잭션은
pqxx::work로 자동 롤백 보장
다음 글 Redis C++(#52-2)에서는 캐싱, 세션, 분산락을 다룹니다.
참고 자료
- PostgreSQL 공식 문서
- libpq 문서
- libpqxx 공식 사이트
- libpqxx GitHub
- 데이터베이스 엔진(#50-4) — DB 설계 기초
관련 글
- C++ 데이터베이스 연동 완벽 가이드 | SQLite·PostgreSQL·연결 풀·트랜잭션 [#31-3]
- C++ MongoDB 완벽 가이드 | mongocxx·CRUD·연결·문제 해결·성능 최적화 [#52-3]
- C++ 쿼리 최적화 완벽 가이드 | 인덱스 선택·실행 계획·통계·비용 모델·프로덕션 패턴 [#49-3]