# antonmedv/elephpantdb architecture

> Architecture diagram of the GitHub repository antonmedv/elephpantdb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antonmedv/elephpantdb
- Repository: https://github.com/antonmedv/elephpantdb

## Overview

ElephpantDB is a single-file PHP SQL database with both a CLI API and a JSON-over-HTTP endpoint. The main workflow accepts one SQL statement and optional parameters, tokenizes and parses it, validates and executes it, then returns rows, an affected-row count, or an error. Its documented capabilities include schema and data changes, indexed equality lookups, persistence and recovery, locking, and vacuuming. Most implementation is in one file; the excerpts are partial, so uncertain internal call wiring is omitted.

Main entry points: [`elephpantdb.php`](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php) (Statement executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interfaces"]
  node_http["HTTP endpoint<br/>[elephpantdb.php]"]
  node_database_api["Database API<br/>[elephpantdb.php]"]
  node_token_auth["Token authentication<br/>[elephpantdb.php]"]
  node_result["Query result<br/>[elephpantdb.php]"]
end

subgraph group_sql["SQL engine"]
  node_tokenizer["SQL tokenizer<br/>[elephpantdb.php]"]
  node_parser["SQL parser<br/>[elephpantdb.php]"]
  node_binder["Parameter binder<br/>[elephpantdb.php]"]
  node_validator["Schema validation<br/>[elephpantdb.php]"]
  node_predicate["Predicate evaluation<br/>[elephpantdb.php]"]
  node_planner["Index planning<br/>[elephpantdb.php]"]
  node_executor["Statement executor<br/>[elephpantdb.php]"]
end

subgraph group_storage["Table storage"]
  node_schema["Table schema<br/>[elephpantdb.php]"]
  node_heap[("Append-only heap<br/>[elephpantdb.php]")]
  node_indexes[("Hash indexes<br/>[elephpantdb.php]")]
end

subgraph group_integrity["Integrity and maintenance"]
  node_table_lock["Table locking<br/>[elephpantdb.php]"]
  node_recovery["Recovery and checksums<br/>[elephpantdb.php]"]
  node_vacuum["Vacuum and rebuild<br/>[elephpantdb.php]"]
end

node_client(("SQL client"))
node_file_system[("Local filesystem")]

node_client -->|"posts SQL"| node_http
node_client -->|"executes SQL"| node_database_api
node_http -->|"checks token"| node_token_auth
node_http -->|"dispatches request"| node_database_api
node_database_api -->|"tokenizes SQL"| node_tokenizer
node_database_api -->|"parses statement"| node_parser
node_database_api -->|"binds parameters"| node_binder
node_database_api -->|"executes statement"| node_executor
node_parser -->|"validates structure"| node_validator
node_executor -->|"validates values"| node_validator
node_executor -->|"checks rows"| node_predicate
node_executor -->|"selects index"| node_planner
node_executor -->|"reads or writes"| node_schema
node_executor -->|"reads or mutates"| node_heap
node_executor -->|"looks up or updates"| node_indexes
node_executor -->|"locks table"| node_table_lock
node_executor -->|"runs vacuum"| node_vacuum
node_executor -->|"produces result"| node_result
node_heap -->|"persists records"| node_file_system
node_schema -->|"persists schema"| node_file_system
node_indexes -->|"persists indexes"| node_file_system
node_table_lock -->|"uses flock"| node_file_system
node_heap -->|"checks and repairs"| node_recovery
node_recovery -->|"truncates tail"| node_file_system
node_vacuum -->|"rewrites live rows"| node_heap
node_vacuum -->|"rebuilds indexes"| node_indexes
node_vacuum -->|"reads schema"| node_schema

click node_http "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_database_api "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_token_auth "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_tokenizer "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_parser "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_binder "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_validator "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_predicate "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_planner "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_executor "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_result "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_schema "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_heap "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_indexes "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_table_lock "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_recovery "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"
click node_vacuum "https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http,node_database_api,node_token_auth,node_result,node_client toneBlue
class node_tokenizer,node_parser,node_binder,node_validator,node_predicate,node_planner,node_executor,node_file_system toneAmber
class node_schema,node_heap,node_indexes toneMint
class node_table_lock,node_recovery,node_vacuum toneRose
```

## Components

### Interfaces

- [HTTP endpoint](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Database API](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Token authentication](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Query result](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`

### SQL engine

- [SQL tokenizer](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [SQL parser](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Parameter binder](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Schema validation](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Predicate evaluation](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Index planning](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Statement executor](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`

### Table storage

- [Table schema](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Append-only heap](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Hash indexes](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`

### Integrity and maintenance

- [Table locking](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Recovery and checksums](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`
- [Vacuum and rebuild](https://github.com/antonmedv/elephpantdb/blob/master/elephpantdb.php): `elephpantdb.php`

### Other components

- **SQL client**
- **Local filesystem**

## Connections

- SQL client → HTTP endpoint: posts SQL
- SQL client → Database API: executes SQL
- HTTP endpoint → Token authentication: checks token
- HTTP endpoint → Database API: dispatches request
- Database API → SQL tokenizer: tokenizes SQL
- Database API → SQL parser: parses statement
- Database API → Parameter binder: binds parameters
- Database API → Statement executor: executes statement
- SQL parser → Schema validation: validates structure
- Statement executor → Schema validation: validates values
- Statement executor → Predicate evaluation: checks rows
- Statement executor → Index planning: selects index
- Statement executor → Table schema: reads or writes
- Statement executor → Append-only heap: reads or mutates
- Statement executor → Hash indexes: looks up or updates
- Statement executor → Table locking: locks table
- Statement executor → Vacuum and rebuild: runs vacuum
- Statement executor → Query result: produces result
- Append-only heap → Local filesystem: persists records
- Table schema → Local filesystem: persists schema
- Hash indexes → Local filesystem: persists indexes
- Table locking → Local filesystem: uses flock
- Append-only heap → Recovery and checksums: checks and repairs
- Recovery and checksums → Local filesystem: truncates tail
- Vacuum and rebuild → Append-only heap: rewrites live rows
- Vacuum and rebuild → Hash indexes: rebuilds indexes
- Vacuum and rebuild → Table schema: reads schema