Configuration

View as Markdown

Nucleus runs as a single binary with sensible defaults. Configure via command-line flags, environment variables, or a configuration file.

Quick Start

# Default: listens on 0.0.0.0:5432 (PostgreSQL wire protocol)
nucleus

# Custom port
nucleus --port 5433

# With data directory
nucleus --data-dir /var/lib/nucleus

Connection

Connect using any PostgreSQL client:

# psql
psql -h localhost -p 5432

# Connection string
postgresql://localhost:5432/nucleus

All standard PostgreSQL drivers work — psycopg2, pgx, node-postgres, diesel, sqlx, etc.

Data Directory

Nucleus stores all data in a single directory:

data/
├── meta.json          # Table schemas, views, sequences, roles
├── sequences.json     # Sequence current values
├── pages/             # B-tree page files
├── wal/               # Write-ahead log
├── fts.wal            # Full-text search WAL
├── doc.wal            # Document store WAL
├── graph.wal          # Graph WAL
├── blob/              # Blob chunk storage
├── ts/                # Time-series data
└── kv/                # Key-value WAL

Wire Protocol

Nucleus implements the PostgreSQL wire protocol (v3), supporting:

  • Simple query — Text-based queries
  • Extended query — Prepared statements with parameters
  • COPY — Bulk data import/export
  • SSL/TLS — Encrypted connections
  • Authentication — Password, MD5, SCRAM-SHA-256

Storage Engines

Nucleus supports multiple storage backends:

| Engine | Description | Best For | |--------|-------------|----------| | Disk (default) | B-tree pages on disk with buffer pool | Production | | Buffered | In-memory with periodic flush | Development | | LSM | Log-structured merge tree | Write-heavy workloads | | Columnar | Column-oriented storage | Analytics |

MVCC

Multi-Version Concurrency Control provides snapshot isolation:

  • Readers never block writers
  • Writers never block readers
  • Each transaction sees a consistent snapshot
  • Automatic conflict detection on write-write conflicts

Backup & Recovery

Most data models use write-ahead logging (WAL) for crash recovery — 8 of the 14 are WAL-durable today, with the rest in progress:

  1. Operations are written to the WAL before applying
  2. On startup, any incomplete operations are replayed
  3. Periodic checkpointing compacts the WAL

Performance Tuning

Buffer Pool

The buffer pool caches frequently accessed B-tree pages in memory. Larger pools reduce disk I/O for read-heavy workloads.

SIMD Acceleration

Nucleus automatically uses SIMD instructions (SSE4.2, AVX2, NEON) when available for:

  • Vector distance calculations
  • Time-series aggregations
  • Columnar scan operations

Specialty Index Rebuild

On startup, specialty indexes (HNSW, IVFFlat, GIN, R-tree) are rebuilt from table data. This ensures consistency after any crash but adds startup time proportional to indexed data.

Monitoring

-- Check server version
SELECT VERSION();

-- Database statistics
SELECT GRAPH_NODE_COUNT();
SELECT GRAPH_EDGE_COUNT();
SELECT FTS_DOC_COUNT();
SELECT BLOB_COUNT();
SELECT TS_COUNT('series_name');
SELECT COLUMNAR_COUNT('table_name');
SELECT DOC_COUNT();

License

Nucleus is licensed under the Business Source License 1.1. Its Additional Use Grant permits production use unless Nucleus is offered to third parties on a hosted or embedded basis as a database service or database engine. Uses outside that grant require a commercial license. Each version converts to MIT on its applicable change date; the current license lists January 1, 2046 or the fourth anniversary of that version's first public distribution, whichever comes first.

The language frameworks are separately MIT-licensed. See each component's license file for its terms.