honest-persist

The apply() Algorithm

FUNCTION apply(conn, desired_schemas):
    live_schema ← inspect(conn)           ← read actual DB state
    plan        ← diff(live_schema, desired_schemas)
    FOR EACH operation IN plan:
        execute_ddl(conn, operation)
        emit("hf.persist.migration", operation)
    RETURN plan

diff() is a pure function: it takes two schema representations and returns an ordered list of DDL operations. It never touches the database. apply() is the only function that runs DDL.

diff() produces operations in this order: 1. CREATE TABLE for tables that do not exist 2. ADD COLUMN for columns that do not exist in an existing table 3. ALTER COLUMN for columns whose type or constraints changed (where the DB supports it) 4. CREATE INDEX for declared indexes not present in live schema 5. DROP INDEX for live indexes not in the declared schema (with explicit opt-in only) 6. DROP COLUMN and DROP TABLE are never produced automatically — destructive operations require explicit declaration

Schema Declaration Rules

A schema is declared as a TableConfig dict:

{
    "table":   "users",
    "columns": [
        {"name": "id",     "type": "text",    "primary": True},
        {"name": "email",  "type": "text",    "unique": True, "nullable": False},
        {"name": "status", "type": "text",    "default": "active"},
        {"name": "created_at", "type": "timestamp", "default": "now()"},
    ],
    "indexes": [
        {"columns": ["email"], "unique": True},
        {"columns": ["status", "created_at"]},
    ],
}

Column type mapping:

SQLite and Turso store booleans as integers and timestamps as ISO 8601 strings. execute() and select() coerce transparently when the column type is declared.

The execute() Function

execute() is the only function that runs SQL. No SQL appears anywhere else in application code.

FUNCTION execute(conn, operation, table, columns, params, where, order, limit):
    sql    ← build_sql(operation, table, columns, where, order, limit)
    result ← conn.execute(sql, params)
    emit("hf.persist.query", {
        table, operation, row_count, duration_ns, sql_hash, request_id
    })
    RETURN result as typed records (plain dicts matching declared schema)

sql_hash is always emitted. Full SQL is emitted only in development mode.

Supported operations: select, select_one, insert, upsert, update, delete, raw.

raw accepts a literal SQL string. It is the escape hatch for queries that the operation set cannot express. It still emits hf.persist.query.

Query Style Support

honest-persist supports four equivalent query styles. All compile to the same parameterized SQL internally:

# Fluent
q.table("users").where(status="active").order("created_at DESC").select("id", "email")

# Django-style
User.objects.filter(status="active").order_by("-created_at").values("id", "email")

# Prisma-style
db.user.find_many(where={"status": "active"}, order_by={"created_at": "desc"})

# Pseudo-SQL
select("id", "email", from_table="users", where="status = :s",
       order="created_at DESC", params={"s": "active"})

All four produce identical parameterized SQL. Style is a per-project configuration. Mixed styles within a project are not permitted — honest-check HC-P013 flags them.

The Write Queue

For high-latency backends (Turso, remote Postgres), honest-persist maintains an optimistic write queue. Writes are acknowledged immediately and flushed asynchronously. The queue emits hf.persist.queue_stalled if writes remain unflushed for more than 6 hours.

The write queue is transparent to application code. execute("insert", ...) behaves identically whether the queue is active or not. Queue depth and stall events are observable via honest-observe projections.

Connection Pool Lifecycle

POOL_EVENTS = {
    "created":   "pool initialized",
    "exhausted": "all connections in use, caller waiting",
    "retry":     "connection attempt retried after failure",
    "closed":    "pool shut down gracefully",
    "error":     "unrecoverable pool error",
}

Every event emits hf.persist.pool to honest-observe. Pool exhaustion is never silent.

Append-Only Tables

A table declared append_only=True rejects UPDATE and DELETE at the honest-persist level:

{
    "table":       "honest_event_log",
    "append_only": True,
    "columns":     [...],
}

Any attempt to execute("update", ...) or execute("delete", ...) against an append-only table returns a server fault immediately, before any SQL reaches the database.

Conformance Requirements