System Overview

Database System is an advanced C++20 database abstraction layer providing unified access to multiple database backends. It eliminates vendor lock-in through a type-safe, backend-agnostic interface with zero-configuration setup and RAII-based resource management.

As a Tier 3 system in the kcenon ecosystem, it builds on common_system for error handling (Result<T>), thread_system for async execution, and monitoring_system for performance observability.

Key Features

Category	Feature	Description
Backends	PostgreSQL	Full-featured relational backend via libpqxx
Backends	SQLite	Lightweight embedded database backend
Backends	MongoDB	Document-oriented NoSQL backend (experimental)
Backends	Redis	Key-value store backend (experimental)
ORM	Entity Macros	ENTITY_TABLE, ENTITY_FIELD, ENTITY_METADATA with C++20 concepts
Query	Immutable Builder	Thread-safe, functional-style query construction
Query	SQL Dialect	Backend-aware SQL generation with condition and join builders
Integration	Unified System	Zero-config entry point with builder pattern
Integration	Connection Pool	Health-checked connection pooling
Async	Async Operations	Asynchronous database operations via Asio
Security	Secure Connection	TLS/SSL encrypted connections with audit logging
Monitoring	Performance Monitor	Real-time query metrics and pool statistics

Architecture Diagram

The system is organized in layers. The core backend interface defines the contract, concrete backends implement it, and higher-level modules (query, ORM, integrated) compose functionality on top.

Quick Start

A minimal example connecting to SQLite and executing a query:

#include "database/database_manager.h"
#include "database/core/database_context.h"
 
using namespace database;
 
int main() {
    // Create context for SQLite
    auto context = std::make_shared<database_context>();
    context->set_backend_type(backend_type::sqlite);
    context->set_connection_string("file:mydb.sqlite3");
 
    // Connect via database_manager
    database_manager manager(context);
    auto connect_result = manager.connect();
    if (!connect_result.is_ok()) {
        std::cerr << "Connection failed: "
                  << connect_result.error().message() << "\n";
        return 1;
    }
 
    // Execute a query
    auto result = manager.execute(
        "CREATE TABLE IF NOT EXISTS users ("
        "  id INTEGER PRIMARY KEY AUTOINCREMENT,"
        "  name TEXT NOT NULL,"
        "  email TEXT UNIQUE"
        ")");
 
    if (result.is_ok()) {
        std::cout << "Table created successfully\n";
    }
 
    manager.disconnect();
    return 0;
}

Installation

CMake FetchContent (Recommended)

include(FetchContent)
FetchContent_Declare(
    database_system
    GIT_REPOSITORY https://github.com/kcenon/database_system.git
    GIT_TAG        v0.1.0
)
FetchContent_MakeAvailable(database_system)
 
target_link_libraries(your_target PRIVATE database)

vcpkg

vcpkg install kcenon-database-system

find_package(database_system CONFIG REQUIRED)

target_link_libraries(your_target PRIVATE kcenon::database)

Manual Build

git clone https://github.com/kcenon/database_system.git
cd database_system
./scripts/dependency.sh
cmake -B build -DCMAKE_BUILD_TYPE=Release -DUSE_POSTGRESQL=ON
cmake --build build

Module Overview

Module	Directory	Key Headers	Description
Core	`core/`	database_backend.h, backend_base.h, backend_registry.h	Backend interface, CRTP base, factory registry
PostgreSQL	`backends/postgresql/`	postgresql_backend.h	Full-featured PostgreSQL backend via libpqxx
SQLite	`backends/sqlite/`	sqlite_backend.h	Lightweight embedded SQLite backend
MongoDB	`backends/mongodb/`	mongodb_backend.h	Document-oriented NoSQL backend (experimental)
Redis	`backends/redis/`	redis_backend.h	Key-value store backend (experimental)
Query	`query/`	immutable_query_builder.h	Thread-safe, immutable query construction
Query Builder	`query_builder/`	condition_builder.h, join_builder.h, sql_dialect.h	SQL generation with conditions, joins, and dialect awareness
ORM	`orm/`	entity.h	ENTITY_TABLE, ENTITY_FIELD macros with C++20 concepts
Integrated	`integrated/`	unified_database_system.h	Zero-config unified entry point with builder pattern
Async	`async/`	async_operations.h	Asynchronous database operations via Asio
Monitoring	`monitoring/`	performance_monitor.h, pool_metrics.h	Real-time query and pool performance metrics
Security	`security/`	secure_connection.h	TLS/SSL encrypted connections and audit logging
Protocol	`protocol/`	database_protocol.h	Database protocol and serialization

Learning Resources

New to database_system? Start with the tutorials below, then dig into the FAQ and troubleshooting guide as questions come up.

Resource	Description
Quick Start Tutorial	Connection setup, basic CRUD, result handling, transactions
ORM Entity Mapping Tutorial	ENTITY_FIELD / ENTITY_METADATA, constraints, relationships, query builder integration
Multi-Backend Tutorial	SQLite vs PostgreSQL vs MySQL vs MongoDB, connection modes, migration patterns
Frequently Asked Questions	Backend selection, pooling, isolation levels, multi-tenancy, async, and more
Troubleshooting Guide	Connection failures, deadlocks, ORM mistakes, slow queries, migration drift

Examples

Example	Source	Description
Basic Connection	basic_connection.cpp	Database connection and simple query execution
Query Builder	query_builder_usage.cpp	Fluent query construction with the immutable builder
Transactions	transaction_management.cpp	Transaction begin, commit, and rollback patterns
ORM Entities	orm_entity_demo.cpp	Entity mapping with ENTITY_TABLE and ENTITY_FIELD macros
Error Handling	error_handling.cpp	Result<T> error handling and recovery strategies
Connection Pool	connection_pool_demo.cpp	Connection pooling with health checks

Related Systems

Database System is a Tier 3 system in the kcenon ecosystem, sitting between the monitoring layer and the application layer:

System	Tier	Relationship	Repository
common_system	0	Foundation: Result<T>, IExecutor, ILogger	https://github.com/kcenon/common_system
thread_system	1	Async execution and thread pooling	https://github.com/kcenon/thread_system
container_system	1	Data serialization format	https://github.com/kcenon/container_system
monitoring_system	2	Performance observability	https://github.com/kcenon/monitoring_system
database_system	3	This project	https://github.com/kcenon/database_system
network_system	4	Network communication layer	https://github.com/kcenon/network_system
pacs_system	5	Full ecosystem consumer	https://github.com/kcenon/pacs_system

Table of Contents