Architecture Overview

ParticleDB is a hybrid transactional/analytical processing (HTAP) database. A single process serves both OLTP point lookups and OLAP analytical queries over the same data, eliminating the need for separate ETL pipelines between operational and analytical systems.

System Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        Client Connections                        │
│ PostgreSQL Wire │ gRPC │ HTTP/REST + SSE │ Redis RESP            │
└────────┬─────────┴───┬──┴───────┬─────────┴──────┬───────────────┘
         │             │          │                │
┌────────▼─────────────▼──────────▼────────────────▼──────────────┐
│                        Network Layer                             │
│              Protocol handlers, TLS, auth, routing               │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                     SQL Parser & Planner                         │
│   Parse → AST → Logical Plan → Optimize → Physical Plan          │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                      Query Execution Engine                      │
│   Vectorized columnar execution · Parallel across CPU cores      │
└─────────┬──────────────────────────────────┬────────────────────┘
          │                                  │
┌─────────▼──────────┐          ┌────────────▼────────────────────┐
│ Transaction Engine │          │         Vector Index             │
│  MVCC · WAL · 2PC  │          │  HNSW · IVFFlat                  │
└─────────┬──────────┘          └─────────────────────────────────┘
          │
┌─────────▼──────────────────────────────────────────────────────┐
│                        Storage Engine                            │
│   Columnar persistent storage · Write-Ahead Log · Compression   │
└─────────────────────────────────────────────────────────────────┘

Core Components

SQL Parser and Optimizer

The SQL layer parses incoming queries into an abstract syntax tree and transforms them through a series of optimization passes before producing a physical execution plan.

Optimization	Description
Predicate pushdown	Pushes WHERE filters through projections, joins, and into scans to reduce rows early
Projection pushdown	Narrows scan projections to only the columns referenced by the query
Constant folding	Evaluates constant sub-expressions at plan time
Join reordering	Cost-based: flattens multi-way inner joins, sorts by estimated cardinality
Plan cache	Normalized SQL text maps to cached physical plans; cleared on DDL changes

Query Execution Engine

The engine executes plans using vectorized columnar operators that run in parallel across CPU cores. Aggregates resolve from precomputed metadata when possible, so queries like SELECT COUNT(*) or SELECT MAX(price) return without scanning rows.

Transaction Engine

ParticleDB provides MVCC with snapshot isolation. Three WAL synchronization modes trade durability for throughput:

Mode	Behavior	Use case
sync	Per-entry fsync	Maximum durability
groupsync	Batched fsync across transactions	Balanced (default)
nosync	WAL writes skipped entirely	Maximum throughput

Row-level locking supports FOR UPDATE / FOR SHARE with SKIP LOCKED and NOWAIT.

See the Transaction Engine deep dive for full details.

Network Layer

ParticleDB exposes multiple server protocols through a single process, so applications can connect with whichever protocol fits their stack:

Protocol	Default Port	Primary Use
PostgreSQL wire	5432	SQL access, ORM compatibility
gRPC	26257	Typed RPC, batch execution, CDC
HTTP / REST	8080	JSON SQL, status endpoints, SSE
Redis RESP	6379	Key-value and data-structure access

All protocols share the same underlying storage and transaction engine, so data written via one protocol is immediately visible through any other.

Vector Index

ParticleDB includes built-in vector similarity search without external plugins:

• HNSW (Hierarchical Navigable Small World) for high-recall approximate nearest neighbor search.
• IVFFlat (Inverted File with Flat quantization) for large-scale workloads.
• Distance metrics: L2 (Euclidean), Cosine, and Inner Product.

Vector columns are defined with standard SQL DDL and queried with the <-> operator or the vector_search() function. See Vector Search for SQL syntax.

Design Principles

1. Single binary — one binary contains the full database. No JVM, no external dependencies, no sidecar processes.
2. Columnar-first — analytical queries scan only the columns they need.
3. Protocol diversity — multiple server interfaces let you use the right tool for each workload without proxies or adapters.
4. HTAP by design — OLTP and OLAP share the same storage and transaction engine rather than replicating data between separate systems.