manifest / developer / esoteric-database-in-real-html-tables

HTML Database Drop-in

An experimental database engine that stores data in real HTML tables. Educational/entertainment project with sharded storage.

by mudrava · github.com/mudrava/esoteric-database-in-real-html-tables · website

★ 0stars

0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/mudrava/esoteric-database-in-real-html-tables/archive/refs/heads/main.zip

Readme

Esoteric Database in Real HTML Tables

A WordPress database drop-in that replaces MySQL with a flat-file storage engine — where every table is a folder of real HTML files.

⚠️ This is an esoteric/experimental project. Do not use in production.

What it does

Instead of storing data in MySQL, db.php intercepts all WordPress database calls and saves rows as HTML <table> elements inside .html files on disk. You can open any of these files in a browser and browse your database as a styled, navigable web page — complete with a retro green-on-black terminal aesthetic.

wp-content/
└── db.php          ← drop this file here to activate

html_db/
├── _index.html     ← database browser (all tables)
├── _style.css      ← retro terminal CSS
├── _global.seq     ← global TX counter
└── wp_posts/
    ├── _index.html     ← table of contents (all chunks)
    ├── _meta.json      ← metadata (pk column, row count, …)
    ├── chunk_0001.html ← rows 1–500 as an HTML table
    ├── chunk_0002.html ← rows 501–1000
    ├── wal.html        ← append-only write-ahead log
    └── .seq            ← auto-increment counter

Architecture (v3 — Sharded Storage)

Concept	Detail
Storage unit	Each table is a directory; data is split into chunk files (≤ 500 rows each by default)
Write path	All mutations (INSERT, UPDATE, DELETE) are appended to `wal.html` — O(1), crash-safe
Read path	SELECTs merge chunk data with WAL entries; WAL entry wins by highest TX id
Shard routing	PK-equality queries touch one chunk; full-scan queries read all chunks
Compaction	Background vacuum merges WAL entries into chunks (triggered after 200 WAL entries by default)
Ordering	Global monotonic TX counter for MVCC ordering across concurrent requests
Crash safety	All writes use temp-file + `rename()` (POSIX atomic)
Locking	`flock(LOCK_EX)` on appends, `LOCK_SH` on reads, dedicated `.compact.lock` during vacuum
Security	`.htaccess` deny-all + `index.html` placeholder in every storage directory
UI	Retro terminal CSS (green-on-black, monospace, glow), linked prev/next navigation between chunks

Installation

Copy db.php into your WordPress wp-content/ directory:
```
wp-content/db.php
```
WordPress automatically picks up any file named db.php in that location as a database drop-in.
Make sure the web server has write permission to the wp-content/ directory (so html_db/ can be created).
That's it. WordPress will now read and write through the HTML database engine instead of MySQL.

Configuration

Parameter	Default	Description
Base path	`wp-content/html_db`	Root directory for all HTML storage files (hardcoded)
Chunk size	`500`	Maximum rows per chunk file
Compact threshold	`200`	WAL entries before background compaction is triggered

The base path is derived automatically from WP_CONTENT_DIR and cannot currently be changed without editing db.php directly.

Browsing the database

Every chunk file is a valid HTML page you can open in any browser. Navigate to html_db/_index.html for the full database browser:

Database index — lists all tables with row counts and chunk counts
Table index — lists all chunks for a single table
Chunk pages — show actual row data as an HTML <table> with prev/next navigation
WAL page — shows the raw append-only mutation journal

All pages share a retro terminal stylesheet (_style.css): green text on a black background with monospace font and CRT glow effects.

How queries are mapped

SQL operation	HTML storage action
`INSERT`	Append `<tr>` to `wal.html` with op=`insert`
`UPDATE`	Append `<tr>` to `wal.html` with op=`update` (changed columns only)
`DELETE`	Append `<tr>` to `wal.html` with op=`delete` (tombstone)
`SELECT`	Parse matching chunk files + replay WAL on top
`CREATE TABLE`	Create table directory + `_meta.json`
Auto-increment	Atomic read-increment-write on per-table `.seq` file

Limitations

No SQL parser — only a subset of WordPress's wpdb query patterns are handled.
No joins — cross-table queries are not supported.
No transactions — each operation is independently atomic; there is no multi-statement rollback.
Performance — full-table scans read all chunk files from disk; this is much slower than MySQL for large tables.
Not for production — this is an esoteric experiment, not a production-ready database.

Requirements

PHP 8.1+ (uses readonly classes and named arguments)
WordPress 6.x
A POSIX-compatible filesystem (for rename() atomicity and flock())

License

This project is provided as-is for educational and experimental purposes.

Read the full README on GitHub →