Storm ORM Documentation

Welcome to Storm ORM - a modern C++26 ORM library using compile-time reflection to automatically map C++ structs to database tables without macros.

Supported backends: SQLite, PostgreSQL

Quick Links

• Main Project Guide (CLAUDE.md) - Quick start and common tasks
• Benchmarks - Performance results and benchmark system

Guide

Documentation for users of Storm ORM — patterns, features, and field/migration reference.

Cookbook

• Cookbook - Quick-reference patterns for common Storm ORM operations

Features

• CRUD Operations - INSERT, UPDATE, DELETE with auto-generated IDs
• SELECT Queries - Optimized row extraction and statement caching
• WHERE Clauses - Type-safe filtering with pure C++26 reflection
• JOIN Operations - Single and multi-FK JOINs with type erasure
• Batch Operations - Bulk INSERT/UPDATE/DELETE with smart thresholds
• UPSERT Operations - Single-row ON CONFLICT DO UPDATE / DO NOTHING
• Referential Integrity - Always-on FK constraints, junction FOREIGN KEYs, SQLite PRAGMA
• Indexes - Single-column indexed/unique tags and composite Index<>/UniqueIndex<>
• Connection Tuning - SQLite busy_timeout default, optional WAL, pooled concurrency

Reference

• Field Selectors - The fields::Model.field spelling, the per-model declaration recipe, and the column/relation distinction
• Field Types - Supported C++ to SQLite/PostgreSQL type mappings
• Migrations - Atlas-based schema migrations with auto-discovered models

Internals

Documentation for Storm ORM contributors — architecture, build/test workflow, and performance/compiler internals.

Architecture

• Overview - High-level architecture overview
• Design Decisions - Key architectural decisions and rationale
• C++26 Reflection - How Storm uses std::meta for ORM mapping
• SQL Generation - Compile-time SQL generation with ConstexprString
• Module System - Database-agnostic module design with zero-cost cross-module inlining
• Statement Caching - Single Connection-level statement cache achieving near-raw SQLite performance
• Compile-Time vs Runtime - WHERE expression design tradeoffs and performance analysis
• Composite & Non-Integer Primary Keys - Multi-column and UUID keys: per-issue design notes and the failure each prevents
• PostgreSQL Binary Results - Automatic binary-format optimization for SELECT extraction on PostgreSQL

Building

• Getting Started - First-time setup, build via Docker (recommended) or from source
• Common Tasks - Adding operations, common development workflows
• Adding Features - How to add new database operations
• Pre-Commit - clang-tidy modes (--diff / --full / --all), weekly sweep, parse-failure handling
• Formatting - clang-format and cmake-format targets, pre-commit integration, and .clang-format settings

Testing

• Testing - Test framework, PostgreSQL test isolation, running tests
• Code Coverage - How to generate and analyze test coverage
• Sanitizers - ASAN+UBSAN and TSAN presets, what each sanitizer catches, MSAN status
• Fuzzing - libFuzzer stress testing of the runtime SQL binding and execution layer
• MSAN libc++ Fix - In-progress fix for the MSAN + import std; + GTest false positive

Performance

• Performance - Performance guidelines, hot-path tips, and benchmarking/testing workflow
• Compile Time - Where build time goes, measured; what moves it and what was rejected
• Benchmark Dashboard - Real-time TUI for storm_bench: setup, schema, backup/restore, troubleshooting
• JOIN Analysis - JOIN performance deep dive
• DISTINCT Analysis - DISTINCT performance analysis

Compiler

• Compiler Issues - Known workarounds for clang-p2996
• Compiler Attributes - Guide for using hot, flatten, and always_inline attributes
• C++26 Coding Standards - Modern C++ best practices and patterns
• Code Quality - Lint hook thresholds and .lint-skip exemption policy

Open Issues

All open tasks are tracked as GitHub Issues.