Welcome to the SveltyCMS Database Engine documentation. Our architecture is built on the principle of Strict Agnosticism, allowing you to swap between NoSQL and Relational engines without changing a single line of application logic.

📚 Documentation Structure

1. Database-Agnostic Architecture

• Core Infrastructure — db.ts lifecycle, self-healing proxy, plugin-registry topological boot, LocalCMS SDK
• Database Methods Interface — IDBAdapter namespaces: auth, crud, content, media, system, batch, collection
• Database Resilience — Error handling, retry logic, circuit breaker, connection health monitoring
• Performance Architecture — findPage / count modes / count cache (equal on all engines), allocation-floor, schema-aware conversion, ring-buffer pools

2. Engine Implementations

• SQLite Implementation ✅ Platinum — Default for local/edge. Sub-ms CRUD, WAL mode, zero network overhead.
• PostgreSQL Implementation ✅ Production — Enterprise scaling, native JSONB, GIN indexing, PgBouncer support.
• MariaDB Implementation ✅ Production — High-concurrency pooling via mysql2, shared findPage / count estimate path.
• MongoDB Implementation ✅ Production — NoSQL engine, safeQuery security, wire compression.

🏗️ Architecture Overview

Shared list & count contract (all adapters)

Details and measured gains: Performance Architecture · method signatures: Database Methods.

🛡️ Shared Security Principles (All Adapters)

• 4-Layer Defense-in-Depth: Middleware → Dispatcher → Handler → Page Action

• Tenant Isolation: Every query scoped by tenantId at adapter level — architecturally impossible to bypass

• Credential Hashing: Website tokens and API keys are stored as SHA-256 digests only; plaintext is returned once on creation. See system.websiteTokens.

• Tenant-Scoped Bearer Lookup: Auth passes locals.tenantId into credential lookups (aligned with auth.getApiKey) to narrow multi-tenant queries.

• MongoDB Soft-Delete Safety: safeQuery() applies isDeleted: { $ne: true } so legacy documents without the field remain visible to active queries.

• SSRF Prevention: Cloud storage adapters validate endpoints before connection

• NoSQL Injection Protection: sanitizeMongoQuery blocks $where, $function, $expr

• CSPRNG-Only Tokens: globalThis.crypto.getRandomValues(), no Math.random() fallback

• Fail-Closed API: Unmapped namespaces return 403 by default

🔄 Shared Resilience Patterns (All Adapters)

• Circuit Breaker: 5 consecutive failures → 60s open → probe recovery
• Self-Healing Reconnection: Auto-recovery on connection loss + HMR reload
• Exponential Backoff with Jitter: 1s→2s→4s→8s→16s, ±500ms
• Connection Pool Diagnostics: GET /api/database/pool-diagnostics + dashboard widget — see Database Resilience
• Migration Safety: CREATE TABLE IF NOT EXISTS — idempotent

⚡ 2027 Allocation-Floor Optimizations

SQL family: ~5-8 fewer allocations per filtered query. MongoDB: ~2-3 fewer (result pool + fused mapQuery). All 4: benefit from shared BaseAdapter optimizations.

📈 Performance Benchmarks (SQLite, Latest)

Full cross-database benchmarks: Performance Benchmarks.

Adapter Selection Guide

MongoDB for unstructured/high-volume. MariaDB for MySQL-compatible setups (planned). SQLite, PostgreSQL, and MongoDB are production-ready.

Last Updated: 2026-06-22 (website-token credential hardening, safeQuery soft-delete fix, parallel SQL list+count) Maintained by: SveltyCMS Team