HarvSQL Documentation

HarvSQL SQL service

HarvSQL is a compact MySQL-compatible SQL server ELF for HarvOS. It reuses the HNET packet path, stores a deterministic line-based catalog on the data image and is intended to provide the database side for PHP/WordPress experiments.

Build

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build_harvsql.ps1

The build creates build/apps/harvsql.elf, copies it to release/program_usb/harvsql.elf, installs the app config under config/harvsql, ensures release/data_usb/data/harvsql/db and rebuilds the USB images unless -NoUsbImages is passed.

Network reuse

HarvSQL uses the same HarvOS network building blocks as HarvTTP: HNET MMIO registers, DMA bounce-window copies, a bounded TX queue, DHCP, ARP, IPv4 packet construction, a minimal TCP peer table and interrupt-assisted polling. HarvSQL adds MySQL session and protocol callbacks above that layer.

Storage model

All persistent state lives under the data image path:

\data\harvsql\db

The runtime creates catalog.hsq when missing. The catalog is line-based ASCII and rewritten as a whole after mutating statements: 

HARVSQL1
DB|name
T|db|table|column_count|column:type
R|db|table|value|value

Seed and migration scripts

Before the MySQL listener is enabled, HarvSQL scans the program image for sorted SQL scripts: 

\config\harvsql\seed
\config\harvsql\migrations

Seed scripts run once and write \data\harvsql\seeded.conf. Migration scripts are recorded in \data\harvsql\migrations.conf after successful execution.

Authentication config

Credentials are read from \config\harvsql\runtime.yaml. Both map and list forms are supported: 

databases:
  demo:
    username: demo
    password: demo

When credentials exist, MySQL handshake authentication is checked with mysql_native_password. Without credentials, HarvSQL keeps its local/test mode and accepts any username/password.

MySQL compatibility

ProtocolSQL statements
Protocol v10 handshake, COM_QUERY, COM_INIT_DB, COM_PING, COM_QUIT, OK/ERR/EOF and text result-set packets. CREATE DATABASE, USE, CREATE TABLE, INSERT INTO ... VALUES, SELECT, SHOW DATABASES, SHOW TABLES, DESCRIBE, DROP DATABASE, DROP TABLE.

Limits

  • No indexes, joins, WHERE, UPDATE, DELETE, transactions, binary protocol, TLS or prepared statements.
  • Configured passwords are stored as plaintext in the program-image YAML.
  • Fixed limits: 8 databases, 12 tables, 8 columns per table, 16 rows per table and 40 bytes per cell.
  • SQL identifiers are ASCII [A-Za-z0-9_].
  • Bootstrap scripts are capped at 4096 bytes each; individual statements are capped at 512 bytes.
  • The current HNET device is single-owner MMIO; simultaneous independent HarvTTP and HarvSQL NIC ownership still needs a supervisor/netd multiplexer.