🔷 CobaltDB

---

🚀 Two Modes, One Database

CobaltDB runs in two modes — use it as an embedded library inside your Go application, or deploy it as a standalone database server that any MySQL client can connect to.

┌─────────────────────────────────────────────────────────┐
│                     CobaltDB                            │
│                                                         │
│  ┌─────────────┐           ┌───────────────────────┐    │
│  │ Embedded    │           │ Standalone Server     │    │
│  │ (Go Library)│           │ (MySQL Protocol)      │    │
│  │             │           │                       │    │
│  │ db.Query()  │           │ mysql -h host -P 4200 │    │
│  │ db.Exec()   │           │ Any MySQL client/ORM  │    │
│  └─────────────┘           └───────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Comparison

Feature	CobaltDB	PostgreSQL	MySQL	SQLite
Deployment	Embedded + Server	Server only	Server only	Embedded only
Protocol	MySQL wire protocol	PostgreSQL	MySQL	C API
Language	Pure Go (Zero CGO)	C	C/C++	C
Query Language	SQL + JSON	SQL + JSON	SQL + JSON	SQL
Encryption at Rest	✅ AES-256-GCM	Plugin	Plugin	❌
WAL Encryption	✅ Built-in	❌	❌	❌
TLS	✅ TLS 1.2+	✅	✅	❌
Replication	✅ Master-Slave	✅	✅	❌
Row-Level Security	✅ Policy-based	✅	❌	❌
Audit Logging	✅ Encrypted	Plugin	Plugin	❌
Vector Search	✅ HNSW	pgvector	❌	❌
Temporal Queries	✅ AS OF	✅	❌	❌
Zero Dependencies	✅	❌	❌	✅
Cross-Compile	✅ Any OS/Arch	❌	❌	CGO needed
Single Binary	✅	❌	❌	Library

---

📦 Installation

go get github.com/cobaltdb/cobaltdb

Requirements: Go 1.25+ (toolchain go1.26.5) · Zero CGO runtime dependency

Verification and Security Checks

Run core checks locally:

make verify

Run full security/concurrency gate (requires CGO toolchain and gcc for race detector):

make verify-security

If tool commands are missing locally, install:

go install golang.org/x/vuln/cmd/govulncheck@latest
go install github.com/securego/gosec/v2/cmd/gosec@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

---

⚡ Quick Start

1. Server Mode — Connect with MySQL-Compatible Clients

# Start CobaltDB server
./cobaltdb-server -mysql-addr 127.0.0.1:3307 -admin-pass "StrongPass123!" -data ./data

# Connect with standard MySQL client
mysql -h 127.0.0.1 -P 3307 -u admin -p

mysql> CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT);
mysql> INSERT INTO users VALUES (1, 'Alice', '[email protected]');
mysql> SELECT * FROM users;
+----+-------+-------------------+
| id | name  | email             |
+----+-------+-------------------+
|  1 | Alice | [email protected] |
+----+-------+-------------------+

The MySQL wire-protocol surface is tested in-repo for handshake, COM_QUERY, result sets, and parameterized prepared statement execution. Validate each production driver or ORM against docs/MYSQL_COMPATIBILITY.md.

Server features: MySQL protocol, TLS 1.2+, authentication (Argon2id), connection pooling, rate limiting, circuit breaker, health checks, encrypted tamper-evident audit logging, and master-slave replication transport.

Production note: CobaltDB is a production-oriented single-node database candidate. Use TLS for non-loopback wire access, keep the MySQL listener private or disabled, and do not treat replication as automatic HA/failover infrastructure. Replication plaintext is now limited to syntactic loopback endpoints for local development; non-loopback replication requires authenticated TLS, with optional mutual TLS and SSLServerName certificate-name override on replicas.

2. Embedded Mode — Use as a Go Library

import "github.com/cobaltdb/cobaltdb/pkg/engine"

db, _ := engine.Open(":memory:", &engine.Options{InMemory: true})
defer db.Close()

ctx := context.Background()
db.Exec(ctx, `CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    metadata JSON
)`)

db.Exec(ctx, "INSERT INTO users VALUES (?, ?, ?, ?)",
    1, "Alice", "[email protected]", `{"role": "admin"}`)

rows, _ := db.Query(ctx, `SELECT name, JSON_EXTRACT(metadata, '$.role') FROM users`)

Zero CGO, zero dependencies. Import and use — no external server needed.

CLI Mode

# Interactive shell
./cobaltdb-cli -path ./mydb.db

# Execute SQL directly
./cobaltdb-cli -memory "SELECT * FROM users"

# Server mode uses the MySQL protocol
mysql -h 127.0.0.1 -P 3307 -u admin -p

Docker Mode

# Start with Docker Compose (includes Prometheus + Grafana monitoring)
export COBALTDB_ADMIN_PASSWORD='change-this-before-production'
export GRAFANA_ADMIN_PASSWORD='change-this-too'
docker compose up -d

# Or run standalone
docker build -t cobaltdb .
docker run -d \
  -p 4200:4200 \
  -p 3307:3307 \
  -p 8420:8420 \
  -e COBALTDB_ADMIN_PASSWORD='change-this-before-production' \
  -e COBALTDB_ALLOW_CLEARTEXT_AUTH=true \
  -v cobaltdb_data:/data/cobaltdb \
  cobaltdb

# Connect to containerized database
mysql -h 127.0.0.1 -P 3307 -u admin -p

See DOCKER.md for detailed Docker setup instructions.

---

🌍 Multi-Language SDKs

CobaltDB speaks a tested subset of the MySQL wire protocol. Use standard MySQL drivers for validated workflows, and run the compatibility checks for each production driver or ORM.

Go (Embedded)

import (
    "database/sql"
    _ "github.com/cobaltdb/cobaltdb/sdk/go"  // register driver
)

db, _ := sql.Open("cobaltdb", "file://./data/mydb.cb?cache=1024")
db.Exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
db.Exec("INSERT INTO users VALUES (?, ?)", 1, "Alice")

Go (Network Client)

import "database/sql"
import _ "github.com/go-sql-driver/mysql"

db, _ := sql.Open("mysql", "admin@tcp(127.0.0.1:3307)/")
rows, _ := db.Query("SELECT * FROM users")

Python

import cobaltdb  # sdk/python

conn = cobaltdb.connect(host='127.0.0.1', port=3307, user='admin')
cursor = conn.execute("SELECT * FROM users")
for row in cursor.fetchall():
    print(row)

Node.js

const cobaltdb = require('./sdk/js');

const conn = await cobaltdb.connect({ host: '127.0.0.1', port: 3307 });
const [rows] = await conn.execute('SELECT * FROM users');
console.log(rows);

Java

import com.cobaltdb.sdk.CobaltDB;

Connection conn = CobaltDB.connect("127.0.0.1", 3307, "admin", "");
ResultSet rs = conn.createStatement().executeQuery("SELECT * FROM users");

MySQL CLI

mysql -h 127.0.0.1 -P 3307 -u admin -e "SELECT * FROM users"

See docs/MYSQL_COMPATIBILITY.md before relying on a specific ORM or advanced MySQL protocol feature in production.

---

🔥 Performance Benchmarks

Test Environment: AMD Ryzen 9 9950X3D · Go 1.26 · Windows 11

Core Operations (B-Tree Level)

Operation	Latency	Throughput
PUT	~641 ns	1.56M ops/sec
PUT (Sequential)	~694 ns	1.44M ops/sec
GET (Point Lookup)	~64 ns	15.7M ops/sec
UPDATE	~153 ns	6.5M ops/sec
DELETE	~197 ns	5.1M ops/sec
SCAN (1K range)	~270 µs	3.7K ops/sec

SQL Engine Performance (10K rows)

Operation	Latency	Detail
INSERT	~2.0 µs	Single row with SQL parsing
Point Lookup	~2.1 µs	WHERE id = ? (indexed)
Full Scan (1K)	~598 µs	Custom fast decoder, no reflection
Full Scan (10K)	~8.8 ms	130K allocs (42% less than json.Unmarshal)
SUM/AVG	~5.0 ms	Byte-level fast path, no JSON decode
COUNT(*)	~4.4 ms	Fast path, skip row decode
LIMIT 100 OFFSET 1K	~3.7 ms	Early termination
WHERE (10K)	~10.3 ms	Custom decoder + expression eval
Index vs No Index	458 µs vs 8.7 ms	19x faster with index
Inner JOIN (1K)	~724 µs	Hash join
3-Way JOIN (1K×3)	~2.0 ms	Hash join
Recursive CTE	~3.6 µs	1000 nodes
Simple CTE	~584 µs	View-based resolution
Concurrent Read (×20)	~669 ns	Parallel goroutines
Transaction	~347 µs	Single statement
Rollback	~167 µs	100 statements
Window (RowNumber)	~10.0 ms	OVER (ORDER BY) on 10K rows
DELETE (bulk)	~998 µs	WHERE age < 50 on 1K rows
UPDATE (bulk)	~9.2 ms	WHERE age < 50 on 10K rows

Parser & Storage Performance

Component	Operation	Latency	Throughput
SQL Parser	Parse SELECT	~826 ns	1.2M ops/sec
SQL Parser	Parse INSERT	~1.0 µs	960K ops/sec
SQL Parser	Parse Complex Query	~4.7 µs	214K ops/sec
Lexer	Tokenize	~499 ns	2.0M ops/sec
Buffer Pool	Get Page	~27 ns	36.5M ops/sec
Buffer Pool	Memory Read	~34 ns	29.4M ops/sec
WAL	Append	~192 µs	5.2K ops/sec

💡 In-memory benchmarks. Disk persistence adds ~20-40% overhead depending on storage.

---

🔐 Security Features

CobaltDB provides enterprise-grade security features:

Encryption at Rest

import "github.com/cobaltdb/cobaltdb/pkg/storage"

// Generate encryption key
key, _ := storage.GenerateSecureKey()

// Open encrypted database
db, _ := engine.Open("encrypted.db", &engine.Options{
    EncryptionKey: key,
})

• AES-256-GCM authenticated encryption
• Argon2id for secure key derivation
• Transparent encryption/decryption

TLS Support

import "github.com/cobaltdb/cobaltdb/pkg/server"

config := &server.Config{
    Address: ":4200",
    TLS: &server.TLSConfig{
        Enabled:              true,
        GenerateSelfSigned:   true,  // Auto-generate certs
        // Or provide your own:
        // CertFile: "server.crt",
        // KeyFile:  "server.key",
    },
}

srv, _ := server.New(db, config)
srv.Listen(":4200", config.TLS)

• TLS 1.2/1.3 support
• Self-signed certificate generation
• Client certificate authentication

Audit Logging

import "github.com/cobaltdb/cobaltdb/pkg/audit"

auditConfig := &audit.Config{
    Enabled:  true,
    LogFile:  "audit.log",
    LogFormat: "json",  // or "text"
}

db, _ := engine.Open("audited.db", &engine.Options{
    AuditConfig: auditConfig,
})

• JSON and text format support
• Query, DDL, and authentication events
• Automatic log rotation (100MB default)
• Hash-chained entries with offline verification via audit.VerifyLogFile

Row-Level Security (RLS)

import "github.com/cobaltdb/cobaltdb/pkg/security"

// Enable RLS
db, _ := engine.Open("secure.db", &engine.Options{
    EnableRLS: true,
})

// Create policies via SQL
// CREATE POLICY tenant_isolation ON users
//   USING (tenant_id = current_tenant());

---

🏭 Production Features

CobaltDB includes enterprise-grade production features for resilience, observability, and high availability:

Circuit Breaker

import "github.com/cobaltdb/cobaltdb/pkg/engine"

config := &engine.CircuitBreakerConfig{
    MaxFailures:         5,
    MinSuccesses:        3,
    ResetTimeout:        30 * time.Second,
    MaxConcurrency:      100,
    HalfOpenMaxRequests: 1,
}

cb := engine.NewCircuitBreaker(config)

if err := cb.Allow(); err != nil {
    return err // Circuit open
}
defer cb.Release()

err := doOperation()
if err != nil {
    cb.ReportFailure()
} else {
    cb.ReportSuccess()
}

• Three states: Closed, Open, Half-Open
• Automatic recovery with configurable timeout
• Concurrency control and rate limiting in half-open state

Retry Logic

config := &engine.RetryConfig{
    MaxAttempts:  3,
    InitialDelay: 100 * time.Millisecond,
    MaxDelay:     30 * time.Second,
    Multiplier:   2.0,
    Jitter:       0.1, // 10% randomization
}

err := engine.Retry(ctx, config, func() error {
    return db.Query("SELECT * FROM users")
})

// Or with result
result, err := engine.RetryWithResult(ctx, config, func() (string, error) {
    return fetchData()
})

• Exponential backoff with jitter
• Context cancellation support
• 4 predefined policies: Fast, Standard, Aggressive, Background

Rate Limiter

import "github.com/cobaltdb/cobaltdb/pkg/server"

config := &server.RateLimiterConfig{
    RPS:             1000,
    Burst:           100,
    PerClient:       true,
    CleanupInterval: 5 * time.Minute,
    MaxClients:      10000,
}

rl := server.NewRateLimiter(config)
defer rl.Stop()

if !rl.Allow("client-id") {
    return errors.New("rate limit exceeded")
}

• Token bucket algorithm
• Global and per-client rate limiting
• Adaptive rate limiting based on system load

SQL Injection Protection

config := &server.SQLProtectionConfig{
    Enabled:             true,
    BlockOnDetection:    true,
    MaxQueryLength:      10000,
    MaxORConditions:     10,
    MaxUNIONCount:       5,
    SuspiciousThreshold: 3,
}

sp := server.NewSQLProtector(config)

result := sp.CheckSQL(sql)
if !result.Allowed {
    return errors.New("SQL injection detected")
}

• 15 SQL injection pattern detection
• UNION-based, time-based blind, conditional blind, OOB exfil detection
• Whitelist support for trusted queries

Distributed Tracing

// Generate request ID
ctx = server.ContextWithRequestID(ctx, server.NewRequestContext().ID)

// Extract from context
requestID := server.RequestIDFromContext(ctx)

• Request ID tracking across components
• Span-based tracing
• Context propagation

Health Checks & Monitoring

# Liveness probe (Kubernetes)
curl http://localhost:8420/health

# Readiness probe (Kubernetes)
curl http://localhost:8420/ready

# Detailed health status
curl http://localhost:8420/healthz

# Circuit breaker statistics
curl http://localhost:8420/circuit-breakers

# Rate limiter statistics
curl http://localhost:8420/rate-limits

# System statistics
curl http://localhost:8420/stats

Production Server

config := &server.ProductionConfig{
    Lifecycle: &server.LifecycleConfig{
        ShutdownTimeout: 30 * time.Second,
        DrainTimeout:    10 * time.Second,
    },
    EnableCircuitBreaker: true,
    CircuitBreaker:       engine.DefaultCircuitBreakerConfig(),
    EnableRetry:          true,
    Retry:                engine.DefaultRetryConfig(),
    EnableRateLimiter:    true,
    EnableSQLProtection:  true,
    EnableHealthServer:   true,
    HealthAddr:           "127.0.0.1:8420",
}

ps := server.NewProductionServer(db, config)
if err := ps.Start(); err != nil {
    log.Fatal(err)
}

ps.Wait() // Wait for shutdown signal

• Graceful shutdown with configurable timeouts
• Signal handling for SIGTERM/SIGINT
• Component lifecycle management

---

📁 Project Structure

cobaltdb/
├── 📂 cmd/                     # Command-line tools
│   ├── cobaltdb-server/        # Production server
│   ├── cobaltdb-cli/           # Interactive CLI
│   ├── cobaltdb-migrate/       # Migration tool
│   ├── cobaltdb-bench/         # Benchmark tool
│   └── demo*/                  # Demo applications
│
├── 📂 pkg/                     # Core packages
│   ├── engine/                 # Database engine (CB, retry)
│   ├── catalog/                # SQL execution layer
│   │   ├── catalog_core.go     # Core types & helpers
│   │   ├── catalog_insert.go   # INSERT operations
│   │   ├── catalog_update.go   # UPDATE operations
│   │   ├── catalog_delete.go   # DELETE operations
│   │   ├── catalog_select.go   # SELECT & JOIN
│   │   ├── catalog_aggregate.go # GROUP BY & aggregates
│   │   ├── catalog_window.go   # Window functions
│   │   ├── catalog_cte.go      # CTE operations
│   │   ├── catalog_ddl.go      # DDL operations
│   │   ├── catalog_txn.go      # Transactions
│   │   ├── catalog_eval.go     # Expression evaluation
│   │   ├── catalog_index.go    # Index operations
│   │   ├── catalog_rls.go      # Row-Level Security
│   │   └── ...
│   ├── query/                  # SQL parser & optimizer
│   ├── btree/                  # B+Tree storage engine
│   ├── storage/                # Storage layer (WAL, buffer pool)
│   ├── server/                 # Network server (TLS, auth)
│   ├── security/               # RLS & security
│   ├── audit/                  # Audit logging
│   ├── auth/                   # Authentication
│   ├── protocol/               # MySQL protocol
│   ├── metrics/                # Metrics collection
│   └── txn/                    # Transaction manager
│
├── 📂 test/                    # Integration tests (5,000+)
├── 📂 docs/                    # Documentation
├── 📂 scripts/                 # Utility scripts
│
├── 📂 sdk/                     # Multi-language SDKs
│   ├── go/                     # Go SDK (database/sql driver)
│   ├── python/                 # Python SDK (mysql-connector wrapper)
│   ├── js/                     # Node.js SDK (mysql2 wrapper)
│   └── java/                   # Java SDK (JDBC wrapper)
│
└── 📂 website/                 # Project website

Module Organization

Package	Purpose	Lines of Code
pkg/catalog	SQL execution (18 files)	~8,500
pkg/query	SQL parser & optimizer	~6,000
pkg/btree	B+Tree storage	~1,500
pkg/storage	Storage layer	~2,500
pkg/server	Network & production	~3,500
pkg/engine	Resilience (CB, retry)	~800

---

✨ Feature Highlights

🗄️ SQL Support

-- DDL: Schema Definition
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    price REAL CHECK (price > 0),
    category TEXT,
    tags JSON,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_category ON products(category);
CREATE VIEW expensive_products AS 
    SELECT * FROM products WHERE price > 100;

-- DML: Data Manipulation
INSERT INTO products (name, price, category, tags) 
VALUES ('MacBook Pro', 1999.99, 'Electronics', '["laptop", "apple"]');

-- Complex SELECT with JOINs, Aggregates, Window Functions
SELECT 
    p.category,
    COUNT(*) as total,
    AVG(p.price) as avg_price,
    MAX(p.price) as max_price,
    ROW_NUMBER() OVER (PARTITION BY p.category ORDER BY p.price DESC) as rank
FROM products p
LEFT JOIN orders o ON p.id = o.product_id
WHERE p.price BETWEEN 100 AND 500
GROUP BY p.category
HAVING COUNT(*) > 5
ORDER BY avg_price DESC
LIMIT 10;

📊 Advanced Features

Window Functions

SELECT 
    name,
    salary,
    AVG(salary) OVER (PARTITION BY dept) as dept_avg,
    RANK() OVER (ORDER BY salary DESC) as salary_rank,
    LAG(salary) OVER (ORDER BY salary) as prev_salary
FROM employees;

JSON Operations

-- Extract nested values
SELECT JSON_EXTRACT(metadata, '$.user.address.city') FROM users;

-- Modify JSON
UPDATE users SET metadata = JSON_SET(metadata, '$.last_login', '2026-03-02');

-- Array operations
SELECT * FROM products WHERE JSON_ARRAY_LENGTH(tags) > 2;

Transactions (ACID)

BEGIN;
    UPDATE accounts SET balance = balance - 100 WHERE id = 1;
    UPDATE accounts SET balance = balance + 100 WHERE id = 2;
    -- Atomic transfer
COMMIT;
-- Or ROLLBACK on error

Triggers & Procedures

-- Audit logging trigger
CREATE TRIGGER audit_log 
AFTER INSERT ON users
BEGIN
    INSERT INTO audit (table_name, action, record_id, created_at)
    VALUES ('users', 'INSERT', NEW.id, CURRENT_TIMESTAMP);
END;

-- Stored procedure
CREATE PROCEDURE transfer_funds(from_id INT, to_id INT, amount REAL)
BEGIN
    UPDATE accounts SET balance = balance - amount WHERE id = from_id;
    UPDATE accounts SET balance = balance + amount WHERE id = to_id;
END;

CALL transfer_funds(1, 2, 100.00);

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      CLIENT LAYER                           │
│    Go SDK  ·  CLI  ·  TCP/Wire Protocol  ·  REST API        │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                    SQL QUERY ENGINE                         │
│  Parser → Planner → Optimizer → Executor (Iterator Model)   │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              TRANSACTION MANAGER (MVCC)                     │
│         Snapshot Isolation · Conflict Detection             │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                   STORAGE ENGINE                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │   B+Tree     │  │ Index Mgr    │  │  Buffer Pool     │  │
│  │  (Row Store) │  │ (Secondary)  │  │  (LRU Cache)     │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Page Manager · WAL (Write-Ahead Log) · Free Page List │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                      I/O LAYER                              │
│              Disk Backend  ·  Memory Backend                │
└─────────────────────────────────────────────────────────────┘

Key Components

Component	Technology	Purpose
Storage	B+Tree	Efficient range queries, ordered iteration
Buffer Pool	LRU	Page caching, reduces disk I/O
WAL	Write-Ahead Log	Durability, crash recovery
Transactions	MVCC	Lock-free reads, snapshot isolation
JSON	Native Parser	Document storage without external deps

---

📋 SQL Reference

Data Types

Type	Description	Example
INTEGER	64-bit signed integer	42, -17
REAL	64-bit floating point	3.14159, -0.001
TEXT	Variable-length string	'hello', "world"
BOOLEAN	True/False	TRUE, FALSE
JSON	Native JSON document	'{"key": "value"}'
VECTOR(n)	n-dimensional vector	VECTOR(128) for embeddings
DATE	Date only	'2026-03-02'
TIMESTAMP	Date + Time	'2026-03-02 14:30:00'

SQL Functions

String: LENGTH, UPPER, LOWER, TRIM, SUBSTR, CONCAT, REPLACE, INSTR
Numeric: ABS, ROUND, FLOOR, CEIL
Aggregate: COUNT, SUM, AVG, MIN, MAX
JSON: JSON_EXTRACT, JSON_SET, JSON_REMOVE, JSON_VALID, JSON_ARRAY_LENGTH, JSON_MERGE
Window: ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, FIRST_VALUE, LAST_VALUE
Date/Time: DATE, TIME, DATETIME, STRFTIME
Utility: COALESCE, IFNULL, NULLIF, CAST

Supported Statements

-- DDL
CREATE TABLE ... [PRIMARY KEY] [NOT NULL] [UNIQUE] [CHECK] [FOREIGN KEY]
CREATE INDEX ... ON ...
CREATE VIEW ... AS SELECT ...
CREATE TRIGGER ... BEFORE|AFTER INSERT|UPDATE|DELETE
CREATE PROCEDURE ...
DROP TABLE|INDEX|VIEW|TRIGGER|PROCEDURE ... [IF EXISTS]

-- DML
INSERT INTO ... VALUES (...)
INSERT INTO ... SELECT ...
UPDATE ... SET ... WHERE ...
DELETE FROM ... WHERE ...
SELECT ... FROM ... [JOIN ... ON ...] [WHERE ...] [GROUP BY ...] [HAVING ...] [ORDER BY ...] [LIMIT ...] [OFFSET ...]

-- DCL
BEGIN | COMMIT | ROLLBACK
CALL procedure_name(...)

---

🔧 Development

# Clone the repository
git clone https://github.com/cobaltdb/cobaltdb.git
cd cobaltdb

# Run tests
go test ./... -v

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

# Run benchmarks
go test -bench=. -benchtime=2s ./test/...

# Build CLI
go build -o cobaltdb-cli ./cmd/cobaltdb-cli

# Build Server
go build -o cobaltdb-server ./cmd/cobaltdb-server

# Run demo
go run cmd/demo/main.go

Test Coverage

Package	Coverage	Package	Coverage
pkg/logger	100.0% ✅	pkg/pool	97.5% ✅
pkg/advisor	96.8% ✅	pkg/auth	96.8% ✅
pkg/wire	94.7% ✅	pkg/metrics	94.3% ✅
pkg/fdw	93.9% ✅	pkg/optimizer	93.8% ✅
pkg/security	93.2% ✅	pkg/query	91.7% ✅
pkg/parallel	91.2% ✅	pkg/cache	90.9% ✅
pkg/audit	90.7% ✅	pkg/server	90.6% ✅
pkg/storage	88.4% ⚠️	pkg/replication	88.3% ⚠️
pkg/backup	88.2% ⚠️	pkg/txn	87.8% ⚠️
pkg/catalog	84.8% ⚠️	pkg/wasm	84.4% ⚠️
pkg/protocol	82.7% ⚠️	pkg/engine	80.8% ⚠️
pkg/btree	78.2% ⚠️

7,100+ test functions across 600+ test files, all passing. Current pkg/... coverage is 86.3%; several production-critical packages remain below the 90% package target.

---

📚 Documentation

Document	Description
DOCUMENTATION.md	Comprehensive reference (2,125 lines) — architecture, every package, security, production, SDKs, deployment, SQL reference
CHANGELOG.md	Version history, all changes
COVERAGE_GUIDE.md	Test coverage analysis and targets
FEATURES.md	Feature status - what works 100% vs partially
docs/PRODUCTION.md	Production features guide (Circuit Breaker, Retry, Rate Limiting)
docs/ARCHITECTURE_FULL.md	System design & components
docs/API.md	Go SDK documentation
docs/SQL.md	Complete SQL syntax
docs/BENCHMARKS.md	Performance benchmarks
docs/GETTING_STARTED.md	Getting started guide

---

🛣️ Roadmap

✅ Completed Features (v0.1.51)

• SQL Support - SELECT, INSERT, UPDATE, DELETE with JOINs, GROUP BY, ORDER BY, LIMIT
• Window Functions - ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, FIRST_VALUE, LAST_VALUE
• JSON Support - Native JSON type with JSON_EXTRACT, JSON_SET, JSON_REMOVE, JSON_ARRAY_LENGTH
• Indexes - CREATE INDEX, DROP INDEX with B+Tree implementation
• Views - CREATE VIEW, DROP VIEW support
• Triggers - CREATE TRIGGER with BEFORE/AFTER, INSERT/UPDATE/DELETE events
• Stored Procedures - CREATE PROCEDURE, CALL support
• Transactions - BEGIN, COMMIT, ROLLBACK with ACID compliance
• User Management - Authentication with permissions and sessions
• Constraints - PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK, NOT NULL
• MySQL Protocol - Wire-compatible MySQL protocol support

✅ Completed Features (v0.2.0)

• Full-Text Search - MATCH ... AGAINST syntax with inverted indexes
• Materialized Views - CREATE MATERIALIZED VIEW, REFRESH, and DROP support
• Common Table Expressions - WITH clause support for recursive and non-recursive CTEs
• VACUUM - Database compaction and storage reclamation
• ANALYZE - Table statistics collection for query optimization

✅ Production Hardening (v0.2.11)

• Panic Recovery - Server survives any query panic
• Resource Leak Fixes - All iterators properly closed
• Race Condition Fixes - Statement cache thread-safety
• Transaction Fixes - Connection leak plugged
• Data Corruption Fix - Free list loading corrected

✅ Enterprise Production Features (v0.2.20)

• Circuit Breaker - Three-state breaker with automatic recovery
• Retry Logic - Exponential backoff with 4 policies
• Rate Limiter - Token bucket with adaptive limiting
• SQL Injection Protection - 10+ pattern detection
• Distributed Tracing - Request ID tracking
• Graceful Shutdown - Signal handling with drain timeout
• Health Checks - Kubernetes-compatible probes

✅ v0.2.22 - WASM & Advanced Features (2026-03-17)

• WASM Compilation - Compile SQL queries to WebAssembly bytecode
• Query Plan Cache - LRU cache for parsed query plans with statistics
• Vector Support - VECTOR data type with HNSW index for similarity search
• Temporal Queries - AS OF SYSTEM TIME for time-travel queries

✅ v0.3.0 - Security Hardening & Stability (2026-03-20)

• WAL Encryption - AEAD encryption for write-ahead log with header authentication
• Audit Log Encryption - AES-256-GCM encrypted, hash-chained, and offline-verifiable audit log entries
• RLS Hardening - Fixed bypass in UPDATE...FROM and DELETE...USING
• Auth Hardening - Password policy, brute force rate limiting, random default password
• SQL Injection Protection - 15 detection patterns (conditional blind, OOB exfil, etc.)
• Concurrency Fixes - Panic recovery, double-close protection, lifecycle tracking
• 7,100+ Test Functions - all pkg packages passing; 86.3% current pkg/... coverage

✅ v0.3.1 - Production Readiness Milestone (2026-03-31)

• Deadlock Detection - Wait-for graph with automatic cycle detection and resolution
• Transaction Timeout - Configurable per-transaction and lock wait timeouts
• Transaction Metrics - Real-time monitoring of active, committed, aborted transactions
• Chaos Engineering - Comprehensive stress tests for production readiness
• Lock Management - Fine-grained lock tracking with automatic release
• Production hardening baseline
• Graceful Shutdown - Signal handling with drain timeout
• Health Checks - Kubernetes-compatible probes

✅ v0.4.0-0.6.0 - Performance & Security (2026-05)

• 85x JOIN Performance - Hash join implementation, 103ms → 1.3ms
• 8 Security Fixes - Password logging, crypto/rand, SQL injection, TLS hardening
• MVCC Multi-Writer - Concurrent transaction support with adaptive commit locking
• Catalog Optimizations - Reduced lock contention, batch operations, faster scans
• WAL Improvements - 64KB→1MB buffer, 5ms group commit, reduced allocations
• BTree Optimizations - LRU improvements, parallel flush, incremental checkpoint
• Go 1.24+ Compatibility - t.Context() updates, sync.Pool optimizations
• 7,100+ Test Functions - pkg/... coverage currently measures 86.3% overall

✅ Unreleased - SQL Compatibility & Wire-Protocol Hardening (2026-06)

• Broad SQL surface - window frames & PERCENT_RANK/CUME_DIST, window functions in expressions/derived tables, STDDEV/VARIANCE, ON CONFLICT upserts, CREATE TABLE AS SELECT, TRUNCATE, composite UNIQUE, qualified star (table.*), EXTRACT/POSITION, bitwise & <=> operators
• JOIN column-resolution fixes - unqualified joined columns, CTE-to-CTE, derived-to-derived, and window-over-derived no longer drop columns
• Numeric precision - integer literals & negation preserve full int64 (>2^53)
• Function library - math/trig/date/string/JSON/session functions expanded
• ORM/driver compatibility - START TRANSACTION (db.Begin()), @@variables, VERSION()/DATABASE(), SHOW INDEX, prepared statements & transactions verified end-to-end over a real go-sql-driver connection
• Wire-protocol hardening - correct error packets & sequence numbers, zero-column results no longer crash clients
• Security - Go toolchain 1.26.4 patches three stdlib CVEs; govulncheck, gosec, and staticcheck all clean

📋 Planned Features

• Distributed mode - Sharding, consensus, and automatic failover
• Cloud-native operations - Kubernetes operator and managed backups
• Production certification - Crash-recovery evidence, stricter release gates, and package-level coverage targets

---

💪 Why CobaltDB?

1. 🚀 Pure Go - Zero CGO, single binary, cross-compile to any OS/architecture
2. 📱 Embedded + Server - Use as Go library OR deploy as standalone MySQL-compatible server
3. 🔒 Security First - AES-256-GCM encryption (data + WAL + audit), TLS 1.2+, RLS, Argon2id auth
4. 🔄 ACID + MVCC - Snapshot isolation, lock-free reads, WAL durability
5. 🗂️ SQL + JSON + Vector - Relational queries, JSONPath, HNSW similarity search
6. ⚡ Blazing Fast - 15M+ point lookups/sec, 1.5M+ inserts/sec
7. 🏭 Production-Oriented Core - 7,100+ test functions, 86.3% package coverage, circuit breaker, rate limiter, and health checks

---

📄 License

MIT License - see LICENSE file.

---