Umbra

(/ˈʌm.brə/)

Self-contained, shadowy, and slightly suspicious database 🦇

This project takes certain... liberties with database paradigms. Born from the existential void of a southern hemisphere summer (December 2024–January 2025, when ennui struck like the heatwave), Umbra cosplays as PostgreSQL with its query planner (proper cost-based optimisation using expression trees, darling—we’re civilised), while harbouring SQLite’s scandalous little secrets under the bonnet (ahem RowId, you disreputable little implementation detail).

The bat is non-negotiable.

Let's be clear: this isn't a replacement for anything, unless you're replacing sanity with chaos, which case—welcome. The focus here is the learning process, read as "the screams of debugging hand-rolled date parsing at 3AM."

cargo run -- file.db 8000

file.db: The path to your Umbra database file (will be created if it doesn't exist). 8000: The TCP port the server will listen on.

cargo run --package usql -- 8000

Connects to the Umbra server running on port 8000.

usql is your shadowy shell into the Umbra world. It understands SQL and the void.

The beating heart of databases—and poor life decisions.

Umbra supports both signed and unsigned integer types, as well as their attention-seeking cousins: the serial pseudo-types. These SERIAL types aren’t real—they're syntactic sugar that auto-magically generate sequences behind the scenes (just like PostgreSQL, but with fewer emotional boundaries).

CREATE TABLE cursed_items (
    item_id SERIAL PRIMARY KEY,
    name VARCHAR(255),
    darkness_level SMALLINT UNSIGNED,
    soul_count BIGINT UNSIGNED
);

When integers just won’t cut it and you need approximate truths, floating-point types step in—like unreliable narrators in a numerical novel. For precision, we offer NUMERIC.

CREATE TABLE entropy_watch (
    event_id SERIAL PRIMARY KEY,
    time TIMESTAMP,
    shadow_density REAL,
    void_pressure NUMERIC(10, 4) 
);

SELECT time FROM entropy_watch WHERE shadow_density > 69; -- here we implicitly cast 69 to a float, so you can query without hustle

When numbers aren't unique enough and strings are too sincere, you reach for the UUID. Specifically: version 4, because determinism is for spreadsheets.

CREATE TABLE shadow_agents (
    agent_id UUID PRIMARY KEY,
    codename VARCHAR(255),
    clearance_level SMALLINT
);

Because shadows deserve structure, too. Umbra's JSONB implementation provides flexible syntax for JavaScript-like object literals, stores them in a compact binary format, and supports dot notation and path expression for nested access.

• Keys can skip quotes: {name: 'Umbra', active: true}
• Line comments // and block comments /* ... */ are ignored while parsing
• Missing paths quietly become NULL instead of raising errors

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    metadata JSONB
);

INSERT INTO users (metadata) VALUES
({profile: {lang: 'en', hobbies: ['lurking', 'flying']}, active: true});

SELECT metadata.profile.lang FROM users;       -- dot access
SELECT metadata.hobbies[*] FROM users;         -- array expansion
SELECT metadata.hobbies[-1] FROM users;        -- last element via negative index
SELECT metadata.non_existent_field FROM users; -- NULL

• VARCHAR
• BOOLEAN
• DECIMAL
• TEXT (the loquacious one)
• Temporal types (because time flies when... I ran out of jokes)
  • DATE
  • TIME
  • TIMESTAMP (precision: "ish")
  • INTERVAL

• PRIMARY KEY
  • Auto-incrementing (via SERIAL, no manual gear-shifting required)
• UNIQUE (because duplicates are tacky)
• NULLABLE (explicit nullability, because I believe in clarity)
• FOREIGN KEY (relationships are hard)
• CHECK

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255),              -- non-null by default
    email VARCHAR(255) NULLABLE,    -- explicitly nullable
);

• CREATE TABLE (where hope begins)
• DROP TABLE (where hope ends)
• ALTER TABLE

• WHERE (basic filtering, no existential crises)
• ORDER BY (implemented after herding literal bats)
• BETWEEN (for when life exists within bounds)
• LIMIT/OFFSET (self-restraint is here)
• Column aliases (SELECT tomb AS grave - identity is fluid)
• Table aliases (FROM crypts AS c - naming things is hard)
• JOIN (relationships require couples therapy)
• GROUP BY (aggregation is a social construct)
• HAVING

• BEGIN
• COMMIT
• ROLLBACK

• Unique indexes (exclusivity is key)
• Non-unique indexes (for the masses)
• Partial indexes (discrimination coming soon)

• EXPLAIN (peeking behind the curtain)

Now available: numerical seances. Umbra can perform ritualistic summoning of truths across rows using standard SQL aggregate functions. Useful for divining patterns, spotting anomalies, or just counting how many regrets you’ve inserted into a table.

For when you need to quantify the abyss. Basic arithmetic operations (+, -, *, /) work as expected, but these functions handle the unnatural calculations.

Words are powerful. Here they’re dangerous.

-- give me just the first letter of each name
SELECT name, SUBSTRING(name FROM 1 FOR 1) FROM customers;

-- or everything after the third character
SELECT SUBSTRING(name FROM 4) FROM customers;

-- or only the first 3 characters, starting from the beginning
SELECT SUBSTRING(name FOR 3) FROM customers;

Tools for introspection and survival.

Umbra is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

This project includes portions of code derived from third-party projects licensed under the MIT License. Attributions and licence texts for those components are provided in the THIRD_PARTY_NOTICES file.

• Documentation: Here be dragons (and possibly bats)
• Protocol: If you're implementing a client, or are just curious how the shadowy bits work under the hood, check the binary wire format here.
• Philosophy: "Compiling is victory. Running is a miracle."