Engine Database Concept
This document details the database persistence architecture of the Niksphere Engine, explaining how relational data storage and storage drivers operate under the hood.
1. Dual-Driver Storage Architecture
The Niksphere Engine incorporates a flexible dual-driver storage abstraction supporting two distinct relational backends:
PostgreSQL (Enterprise & Cloud Production)
- Architecture: Client-server relational database.
- Use Case: Production environments, multi-tenant cloud deployments, high-concurrency enterprise workloads.
- Features: Connection pooling, SSL/TLS transport security, online backups, horizontal read scaling.
Embedded SQLite (Zero-Config & Edge)
- Architecture: In-process, serverless CGO-free file database engine.
- Use Case: Local developer workstations, edge devices, single-tenant installations, testing environments.
- Features: Zero external installation, single-file storage (
niksphere.dbby default), zero network latency.
File Location
By default (db_name: niksphere, no db_url set), the Engine resolves the SQLite file against the OS-standard State directory described in the Standard Directories Concept — e.g. %LOCALAPPDATA%\Niksphere\Engine\niksphere.db on Windows — rather than the process' working directory. This keeps the database in a stable, backed-up location regardless of where the Engine binary or service is started from.
This default only applies when db_name is a bare file name with no directory component. Setting db_name to a relative or absolute path (e.g. ./data/niksphere or /var/lib/niksphere/niksphere), or providing an explicit db_url, overrides this and is used exactly as given.
2. Storage Backend Decision Matrix
| Criteria | PostgreSQL | Embedded SQLite |
|---|---|---|
| Target Environment | Self-Hosted Enterprise / Niksphere Cloud (Fully Managed) | Local Dev / Edge / Testing |
| Concurrent Write Performance | High (Row-level locking) | Moderate (WAL mode / file locking) |
| External Setup Needed | Yes (DB Server / Container) | No (Built-in file engine) |
| Backup Mechanism | pg_dump / Point-in-time recovery | Single file copy (.db) |
| Network Overhead | Low (TCP/IP socket) | Zero (In-process memory/disk) |
Related Documentation
- Engine Deployment Concept — Architectural overview of Self-Hosted (Docker / Standalone Binary) and Cloud (Fully Managed) deployment models.
- Layer System Concept — Core explanation of the "Everything is an App" layer principle and Base36 UIDs.
- Engine Configuration Reference — Reference for
NIKSPHERE_ENGINE_DB_DRIVERand connection parameters. - Engine Installation & Setup Guide — Quickstart guide for setting up Engine and databases.