Database support

Mere ships pure-Mere PostgreSQL, MySQL, and Redis clients. All three wire protocols, their auth flows (SCRAM-SHA-256 for PG, mysql_native_password and caching_sha2_password for MySQL, AUTH for Redis), and everything on top are implemented in Mere itself; the host only exposes low-level TCP and crypto primitives. No npm packages involved.

The rest of this page walks the stack top-down, then catalogs the 32 examples/db_*.mere demos.

At a glance

Contents

• Layered architecture — 5-layer diagram
• Quick start — docker + build + run
• Public API reference — grouped tables per concern
• Demo catalog — 32 demos grouped by engine + concern
• Limitations and future work

Layered architecture

┌────────────────────────────────────────────────────────────────────┐
│  Mere application code                                             │
│  (e.g. examples/http_todo_pg.mere)                                 │
├────────────────────────────────────────────────────────────────────┤
│  contrib/db/pg.mere            contrib/db/mysql.mere               │
│  ─────────────────             ─────────────────────               │
│  Wire protocol (v3)            Wire protocol (v10)                 │
│  SCRAM-SHA-256                 mysql_native_password (SHA-1)       │
│  Simple + extended query       caching_sha2_password (SHA-256 +    │
│  Prepared statements            RSA-OAEP-SHA1)                     │
│  Transactions + savepoints     Simple query (COM_QUERY)            │
│  COPY FROM/TO STDOUT           Prepared statements (COM_STMT_*)    │
│  LISTEN / NOTIFY + async queue Text + binary row decode            │
│  URL parser (RFC 3986)         URL parser (mysql://)               │
│                                                                    │
│  contrib/db/pg_pool.mere       contrib/db/mysql_pool.mere          │
│  ─────────────────────         ────────────────────────            │
│  Keep-alive pool               Keep-alive pool                     │
│  Idle event pump                                                   │
│                                                                    │
│  contrib/db/redis.mere                                             │
│  ─────────────────────                                             │
│  Full RESP2 + RESP3 (Null / Double / Bool / Map / Set / BigNum /   │
│                       Verbatim / Push / Attribute)                 │
│  redis_command + typed extractors + AUTH + HELLO 3                 │
│  PUB/SUB (SUBSCRIBE / PSUBSCRIBE / redis_wait_message)             │
│  Pipelining (N commands / N replies in one round trip)             │
│  TLS (redis_connect_ssl / _verify — direct handshake, no in-band)  │
│                                                                    │
│  contrib/db/redis_sentinel.mere                                    │
│  ─────────────────────────                                         │
│  Sentinel master resolution + list-masters                         │
│                                                                    │
│  contrib/db/redis_cluster.mere                                     │
│  ────────────────────────                                          │
│  CRC16-XMODEM slot hash + hash-tag extraction                      │
│  CLUSTER SLOTS bootstrap, MOVED redirection, per-node fd cache     │
├────────────────────────────────────────────────────────────────────┤
│  Crypto helpers                                                    │
│  sha256, hmac_sha256, pbkdf2_sha256, base64_encode/decode,         │
│  random_hex / random_b64, hex_xor                                  │
├────────────────────────────────────────────────────────────────────┤
│  Byte-buffer primitives                                            │
│  mem_alloc, mem_{set,get}_{u8,u16be,u32be}, mem_copy_str,          │
│  mem_to_str, str_ptr                                               │
├────────────────────────────────────────────────────────────────────┤
│  Sync TCP + TLS transport                                          │
│  tcp_connect / tcp_write / tcp_read / tcp_close / tcp_set_timeout  │
│  tcp_starttls  — in-place TLS upgrade of an established socket     │
│  worker_thread + SharedArrayBuffer + Atomics.wait                  │
│  (scripts/tcp_worker.js)                                           │
└────────────────────────────────────────────────────────────────────┘

Everything below contrib/db/pg.mere lives in `scripts/pg_env.js` and is shared between the CLI runner (run_wasm.js) and the HTTP harness (run_http_server.js). Wasm's synchronous model composes naturally with the request/response DB protocols; the worker-thread transport bridges Node's async sockets so a Wasm-level tcp_read blocks the way the caller expects.

Values crossing the extern boundary are hex-encoded whenever they'd otherwise contain NUL bytes — Mere's str is C-string, so raw digests and binary frames can't ride as strings. Frame construction uses mem_alloc + mem_set_u*be so the resulting buffer is opaque to the str layer.

Quick start

# 1. Boot a Postgres. Trust-mode works for everything except db_scram,
#    which needs POSTGRES_HOST_AUTH_METHOD=scram-sha-256.
docker run -d --name mere-pg -p 15432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust \
  -e POSTGRES_USER=postgres -e POSTGRES_DB=postgres postgres:16

# 2. Build the driver + a demo.
./_build/default/bin/mere.exe -w examples/db_hello.mere > /tmp/db.wat
wat2wasm --enable-tail-call /tmp/db.wat -o /tmp/db.wasm

# 3. Run it.
node scripts/run_wasm.js /tmp/db.wasm

Expected output for db_hello:

connected
1 | hello
42 | world

Public API reference

Import contrib/db/pg.mere for everything except the pool helpers, which live in contrib/db/pg_pool.mere.

Connect

Auth methods: trust (any password accepted, pass "") and SCRAM-SHA-256. Cleartext-password and MD5 aren't wired — the driver prints a diagnostic and returns -1 if the server asks for them.

Query

_params variants use the extended-query protocol (Parse/Bind/Execute/Sync). Parameters are sent out of band — SQL injection is impossible. Text format for both parameters and results; callers add ::int / ::uuid etc. casts where PG can't infer.

Prepared statements

Parse once, execute many:

Transactions

Callbacks return 'a option — Some commits, None rolls back:

pg_tx_iso's opts is spliced verbatim after BEGIN — pass constants like "ISOLATION LEVEL SERIALIZABLE READ ONLY", never HTTP input.

Bulk transfer (COPY)

10-100× faster than a loop of INSERTs once batch sizes reach a few hundred rows.

Text format only — backslash / tab / newline / CR are escaped per PG's COPY rules and None maps to \N.

Pub/sub (LISTEN / NOTIFY)

Every drain function inside pg.mere (query result, COPY, handshake) captures async NotificationResponse messages into a module-level FIFO queue instead of dropping them, so notifications that arrived during a pg_query surface on the next pg_drain_notifications without another wire read.

Connection pool

Single-fd keep-alive — sufficient for the single-threaded runtime.

Row access

pg_query returns (str option list) list. Helpers turn cells into typed values:

Metadata

• pg_type_name : int -> str maps type OIDs to their canonical names

(int4, text, uuid, jsonb, …). Unknown OIDs surface as "oid=" so callers can pattern-match on the tag.

Demo catalog

All demos live under `examples/db_*.mere`. Build recipe (db_hello shown; substitute the file name):

./_build/default/bin/mere.exe -w examples/db_hello.mere > /tmp/db.wat
wat2wasm --enable-tail-call /tmp/db.wat -o /tmp/db.wasm
node scripts/run_wasm.js /tmp/db.wasm

Every demo is self-contained (its file header lists the exact docker command needed) and cleans up on process exit.

PostgreSQL (16 demos)

Auth & connect

Query surface

Transactions

Bulk transfer (COPY)

Async pub/sub

End-to-end integration

MySQL (4 demos)

Redis (7 demos)

Core

RESP3 & async

Cluster / high availability

Transport / TLS (5 demos — one per engine plus verification variants)

Limitations and future work

• Auth: SCRAM-SHA-256 is the only strong method wired. Cleartext

password and MD5 aren't; SCRAM-SHA-256-PLUS (channel binding) isn't either.

• TLS: both drivers negotiate TLS 1.2/1.3 through Node's tls

module. pg_connect_ssl sends PG's 8-byte SSLRequest and waits for the single-byte 'S' reply before upgrading; mysql_connect_ssl sends the 32-byte "SSL Request Packet" with the CLIENT_SSL bit at MySQL seq=1, then hands the full HandshakeResponse41 over the encrypted channel at seq=2. The _verify variants (pg_connect_ssl_verify / mysql_connect_ssl_verify / redis_connect_ssl_verify) take an optional CA PEM (empty = Node's built-in trust store), require a valid chain, AND run tls.checkServerIdentity against the caller-supplied hostname — so a cert without a matching CN or Subject Alternative Name entry short-circuits the connect with -1 even if the chain itself is valid. Hostname / SAN checks apply to both DNS and IP literal targets (Node's default checker handles IP: SAN entries). URL parsers auto-select: sslmode=verify-full / sslmode=verify-ca → verified, sslmode=require / ssl=true → accept-anything, otherwise plain.

• Binary column format: everything is text. Encoding / decoding

of PG binary format would let us skip a pg_type_name-based decode step for hot paths.

• Column NULL asymmetry: pg_query results distinguish NULL from

"" via str option; some helpers (pg_col_int_or) collapse them to a default for ergonomics.

• Async event loop: NotificationResponse handling is queue-based

— the pool has a pump primitive but no background loop. A real event loop would need cooperation from the Node harness.

• MySQL client: connect + auth + COM_QUERY + prepared statements

(COM_STMT_PREPARE / _EXECUTE / _CLOSE) with binary-protocol row decoding + mysql:// URL parsing + single-fd mysql_pool + transactions (mysql_tx / mysql_tx_iso) with savepoints. Both auth plugins are wired — mysql_native_password (SHA-1) and caching_sha2_password (SHA-256 fast-path + RSA-OAEP-SHA1 public-key exchange when the server's auth cache is cold). TLS is wired (mysql_connect_ssl / ?ssl=true). LISTEN-style pub/sub is not — MySQL has no server-side pub/sub (NOTIFY is a PG feature).

• Redis client: redis_command speaks RESP2 out of the box; call

redis_hello3 to upgrade to RESP3. The full RESP3 wire spec is parsed — RRNull, RRDouble, RRBool, RRMap, RRSet, RRBigNum, RRVerbatim, RRPush, and RRAttr are all recognized on the wire and surfaced through typed extractors (redis_as_bool / redis_as_map / redis_as_bignum / redis_as_verbatim / redis_as_push) plus a redis_unwrap_attr metadata peeler. Binary-safe command args ride through redis_command_b with a redis_arg variant — RATxt s for ASCII, RABin (ptr, len) for arbitrary byte buffers built via mem_alloc / bytes_from_hex_alloc. Reads still surface as RRBulk (Some str) where str is NUL-terminated at the Mere layer; the raw byte buffer is intact at that pointer, so callers who need binary reads peek via mem_get_u8. Also wired: PUB/SUB (redis_subscribe / redis_psubscribe / redis_wait_message / redis_publish), pipelining (redis_pipeline), TLS (redis_connect_ssl / redis_connect_ssl_verify).

• SQLite: not implemented. Would need either a fresh Mere

implementation of the file format or a bundled Wasm build (sql.js / wa-sqlite).