Initial commit: @perryts/mysql v0.1.0

Pure-TypeScript MySQL/MariaDB wire-protocol driver. Runs on Node.js,
Bun, and AOT-compiles to a native binary via Perry.

- M1: Packet framing + lenenc codecs
- M2: Handshake + COM_QUERY
- M3: Auth plugins (native, caching_sha2, sha256, clear, ed25519) + auth-switch
- M4: Prepared protocol (PREPARE/EXECUTE/CLOSE) + LRU cache
- M5: 23 type codecs + Decimal, MyDate/MyTime/MyDateTime
- M6: TLS, Pool, cancel via KILL QUERY, sql`` template, URL/env config
- M7: Multi-resultset, LOCAL_INFILE refusal, benchmark harness

138 passing unit + integration tests, Node TLS suite, Docker matrix
(MySQL 8 + MariaDB 11), benchmarks vs mysql2 in bench/RESULTS.md.

Author: proggeramlug

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+bench/node_modules/
+dist/
+*.log
+.DS_Store
+.env
+.env.local
+*.tsbuildinfo

CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+## v0.1 — initial release
+
+Milestones M1 → M7, all shipped:
+
+- **M1 — Framing + low-level codecs.** 3-byte length + 1-byte seq id packet
+  framing, >16 MB continuation handling, length-encoded integer + string
+  codecs, little-endian buffer cursor, NULL-bitmap helpers (with the
+  server→client +2 reserved-bit offset baked in).
+- **M2 — Handshake + text query.** `HandshakeV10` decoding,
+  `HandshakeResponse41` building, `COM_QUERY` / `COM_QUIT` / `COM_PING`,
+  structured `MyError` (errno + SQLSTATE + message), cross-runtime
+  socket adapter (Node, Bun, Perry).
+- **M3 — Auth plugins.** Dispatcher handling `AuthSwitchRequest` and
+  `AuthMoreData` mid-handshake. Built-in plugins:
+  `mysql_native_password`, `caching_sha2_password` (with RSA-OAEP-SHA1
+  public-key retrieval, gated by `allowPublicKeyRetrieval`),
+  `sha256_password`, `mysql_clear_password` (TLS-gated), MariaDB
+  `client_ed25519`. Custom plugins pluggable via `registerAuthPlugin`.
+- **M4 — Prepared protocol.** `COM_STMT_PREPARE` / `COM_STMT_EXECUTE` /
+  `COM_STMT_CLOSE` / `COM_STMT_RESET` / `COM_STMT_SEND_LONG_DATA`.
+  Per-connection prepared-statement cache keyed on SQL text.
+  Binary-resultset decoder with the +2 server→client NULL-bitmap offset.
+- **M5 — Type codec registry + 23 codecs.** Parallel-array registry
+  keyed on MYSQL_TYPE_* + column flags. Built-in codecs for TINY,
+  SHORT, LONG, LONGLONG, INT24, FLOAT, DOUBLE, NEWDECIMAL (+ legacy
+  DECIMAL), NULL, YEAR, BIT, VAR_STRING, STRING, VARCHAR, BLOB (+ TINY,
+  MEDIUM, LONG), ENUM, SET, GEOMETRY, JSON, DATE, DATETIME, TIMESTAMP,
+  TIME. `Decimal` wrapper (string-backed, lossless). `MyDate`,
+  `MyDateTime`, `MyTime` wrappers preserving microsecond precision.
+  Callers can override codecs via `registerType()`.
+- **M6 — TLS, pool, cancel, sql tag, URL/env resolution.**
+  `SSLRequest` + mid-stream TLS upgrade (`sslmode`:
+  `disable` / `require` / `verify-ca` / `verify-full`) with a single
+  Perry-vs-Node adapter. `Pool` with idle / acquire timeouts and a
+  `withConnection` / `transaction` surface. `Connection.cancel()` opens
+  a second connection and runs `KILL QUERY <connection_id>`.
+  `sql\`\`` tagged template with `?` placeholders and `raw()` for
+  identifiers. `parseConnectionString` for `mysql://` / `mariadb://`
+  DSNs with `ssl-mode`, `charset`, `allowPublicKeyRetrieval` query
+  params. `resolveConnectOptions` for libmysqlclient-style env
+  precedence (`MYSQL_HOST`, `MYSQL_TCP_PORT`, `MYSQL_USER`, `MYSQL_PWD`,
+  `MYSQL_DATABASE`, `MYSQL_SSL_MODE`).
+- **M7 — Multi-resultset, LOCAL_INFILE guard, polish.**
+  Multi-statement / multi-resultset handling gated on
+  `multipleStatements: true`; each set surfaces on
+  `QueryResult.resultSets`. `LOCAL INFILE` requests default to a clean
+  `MyError` refusal with the requested filename in the message.
+  Benchmark harness + shared workloads against `mysql2` / `mysql`.
+  Additional smoke examples (`perry-smoke-prepared`, `perry-smoke-tls`,
+  `select-one`).
+
+### Polish after M7
+
+- **Positive-path TLS integration tests.** `tests-node/tls-node-tests.ts`
+  drives full `SSLRequest` → TLS handshake → `HandshakeResponse41`
+  round-trips against an in-process mock server with a throwaway
+  self-signed cert. Runs under `node --import tsx --test` (Bun 1.3's
+  `tls.connect({socket})` stalls; negative paths still covered under
+  `bun test`).
+- **Cancel integration test.** Mock server supports `simulatedSleepMs`
+  + `KILL QUERY <id>` relay between connections; verifies
+  `conn.cancel()` returns errno 1317 / SQLSTATE 70100 on the target.
+- **Bench harness vs mysql2 and legacy mysql.** `bench/bench-mysql2.ts`
+  and `bench/bench-mysql.ts` mirror `bench-this.ts`; `bench/package.json`
+  keeps comparison drivers out of the main package.
+- **Docker real-server matrix.** `scripts/test-real.sh` brings up MySQL 8
+  + MariaDB 11 via `docker-compose.yml`, runs
+  `tests/integration/real-server.test.ts` against both (skipped by
+  default without `MYSQL_REAL=1`).
+- **Warning event hook.** `conn.on('warning', cb)` fires a summary
+  `MyWarning` whenever a query returns `warningCount > 0`.
+- **`scripts/verify.sh`** — one-shot gate: typecheck → bun test → node
+  TLS → build.
+
+### Bug fixes found via real-server testing (MySQL 8.0.45)
+
+- **HandshakeResponse41 caps mismatch over TLS.** The SSLRequest
+  advertised `CLIENT_CONNECT_ATTRS` while `HandshakeResponse41` (built
+  after the upgrade) stripped it when no attrs were supplied. MySQL
+  cross-checks the two and rejected with errno 1043 "Bad handshake".
+  Now both frames are computed from a single `initialCaps` up front,
+  guaranteeing exact equality.
+- **Prepared INSERT/UPDATE/DELETE hung.** `COM_STMT_EXECUTE` responses
+  for statements that return no resultset are a single OK packet, but
+  the driver jumped straight to the row-collection phase and tried to
+  decode the OK as a binary row. Fixed by always entering the exec
+  response through the column-count phase — its first-packet branch
+  correctly recognises the OK.
+- **`Buffer.isBuffer()` not lowered by Perry AOT codegen.** Replaced
+  with a duck-type check (`typeof v.readUInt8 === 'function' &&
+  typeof v.length === 'number'`) so the driver source compiles cleanly
+  under `perry compile`.
+
+### Perry AOT status
+
+- `perry check --check-deps examples/perry-aot-smoke.ts` passes.
+- `perry compile examples/perry-aot-smoke.ts` produces a 3.6 MB arm64
+  Mach-O binary.
+- **Full end-to-end connect + text query + prepared query + close runs
+  natively** against a real MySQL 8.0.45 server with the driver source
+  identical across all three runtimes (Node, Bun, Perry AOT). Confirmed
+  on perry 0.5.99.
+- Bringing the AOT target up surfaced eight Perry compiler issues —
+  #78, #79, #80, #81, #82 (fixed in 0.5.95); #85 (fixed in 0.5.97); #87,
+  #88 (fixed in 0.5.98); #91 (fixed in 0.5.99). All driver-side
+  workarounds were removed once the upstream fixes landed.
+- The one driver fix that stuck (and would have been correct against
+  every Node/Bun version too) was switching `raw[raw.length - 1]` to
+  `raw.readUInt8(raw.length - 1)` in `decoder.decodeHandshakeV10` —
+  Perry-stdlib's Buffer doesn't lower bracket indexing, and the
+  spurious truthiness left a stray NUL in the auth challenge that
+  silently corrupted the SCRAM scramble.

CLAUDE.md

@@ -0,0 +1,115 @@
+# @perryts/mysql
+
+Pure-TypeScript MySQL / MariaDB wire-protocol driver. Sibling of **Tusk**
+(the GUI that consumes it) and of **@perryts/postgres** (the other
+Perry-showcase driver). Published independently as `@perryts/mysql` and
+usable by any Perry or Node.js program that wants to talk to MySQL 8,
+MariaDB 11, or compatible servers.
+
+## Positioning
+
+- **Showcase of Perry's systems-programming capability.** No native crate
+  in this package; all capabilities come from perry-stdlib
+  (`net.Socket`, `tls.connect`, `socket.upgradeToTLS`, `crypto.*`, `Buffer`).
+- **Runs unchanged on Node.js / Bun.** The only API surface that differs
+  between Perry and Node is TLS upgrade; a one-function adapter handles it.
+  Everything else (Buffer, crypto, net.Socket events, little-endian reads)
+  is Node-compatible by construction.
+- **Shaped for a GUI**, not an ORM. Returns raw rows plus full column
+  metadata (type code, flags, collation, lengths, table/org-table,
+  name/org-name). Exposes warnings, structured ErrPacket fields, server
+  connection id, server version.
+
+## Architecture
+
+```
+TypeScript driver
+    │
+    ├── src/protocol/   3-byte+seq framing, lenenc codecs, writer/reader/decoder (M1, M2)
+    ├── src/auth/       mysql_native_password, caching_sha2_password,
+    │                   sha256_password, mysql_clear_password, client_ed25519 (M3)
+    ├── src/transport/  TCP socket adapter + TLS upgrade                         (M2)
+    ├── src/types/      type-code → codec registry                               (M5)
+    ├── src/error.ts    structured MyError (errno, sqlState, message)            (M2)
+    ├── src/warnings.ts MyWarning (SHOW WARNINGS surface)                        (M7)
+    ├── src/cancel.ts   second-connection + KILL QUERY                           (M6)
+    ├── src/connection.ts  Connection: lifecycle, text + prepared queries        (M2, M4)
+    └── src/index.ts    public barrel exports
+```
+
+## Milestones (mirror the plan at /Users/amlug/.claude/plans/akin-to-postgres-we-immutable-knuth.md)
+
+- **M1** — Packet framing, lenenc codecs, buffer-cursor, null-bitmap. Unit tests green.
+- **M2** — TCP + HandshakeV10 + HandshakeResponse41 + COM_QUERY (`SELECT 1`).
+- **M3** — Auth plugins + auth-switch dispatcher (native, caching_sha2, sha256, clear, ed25519).
+- **M4** — Extended (prepared) protocol: COM_STMT_PREPARE/EXECUTE/CLOSE + binary rows + LRU cache.
+- **M5** — 20 type codecs (binary + text) + rich wrappers (Decimal, MyDate/MyTime/MyDateTime).
+- **M6** — TLS via SSLRequest + sslmode + pool + cancel via KILL QUERY + sql`` template + URL/env.
+- **M7** — Multi-resultset, LOCAL_INFILE guard, SHOW WARNINGS auto-fetch, docker matrix green.
+
+## Node.js compatibility contract
+
+Code under `src/` must only use APIs available both in Perry's stdlib and
+Node.js core:
+
+- `Buffer` (same API on both), `Buffer.concat`, little-endian read/write.
+- `net.createConnection(host, port)` with `.on('connect'|'data'|'error'|'close')`.
+- `crypto.createHash / createHmac / publicEncrypt / sign / randomBytes / ...`.
+
+The one divergence is TLS upgrade:
+
+- Perry: `socket.upgradeToTLS(servername, verify)` returns a Promise.
+- Node: `tls.connect({ socket, servername, rejectUnauthorized })` returns a new TLSSocket.
+
+`src/transport/upgrade-tls.ts` is a ~15-line adapter that feature-detects
+and picks the right path. No other code in the driver needs to know about
+the difference.
+
+## Perry AOT constraints (apply to all source files)
+
+Per the hone CLAUDE.md conventions:
+
+- No `?.` optional chaining — use explicit `if (x === undefined)` / `if (x === null)`.
+- No `??` nullish coalescing — use explicit branching.
+- No `obj[variable]` dynamic key access — use `if/else if` or switch.
+- No `/regex/.test()` — use `indexOf` or char-code checks.
+- No `{ key }` ES6 shorthand — write `{ key: key }`.
+- No `for...of` on arrays — use `for (let i = 0; i < arr.length; i++)`.
+- No `setTimeout` self-recursion — use `setInterval`.
+- No closures capturing instance methods as `this.method` — store state in
+  module-level `Map<id, State>` and use named module-level handlers.
+- No `Buffer[i]` bracket indexing — Perry's codegen doesn't lower it, the
+  read returns undefined and scans walk off the end. Use `buf.readUInt8(i)`.
+
+## MySQL-specific gotchas
+
+- **Little-endian everything.** MySQL is LE; `@perryts/postgres` is BE. Don't
+  share `BufferCursor` between the two drivers.
+- **3-byte length + 1-byte seq id** per packet, max 16 MB payload. A payload
+  of exactly 16 MB triggers a trailing zero-length continuation packet.
+  `seq = (seq + 1) & 0xFF` must wrap every 256 packets.
+- **0xFE is ambiguous.** (a) EOF packet (≤9-byte payload, old-style), (b)
+  AuthSwitchRequest (during auth state), (c) LOCAL_INFILE request (during
+  resultset state, payload is a filename). Disambiguate by (state, payload
+  length).
+- **Binary-row NULL bitmap has a +2 offset.** Only for server→client rows;
+  param bitmaps for `COM_STMT_EXECUTE` do not. Two separate helpers.
+- **Server speaks first.** HandshakeV10 arrives before the client writes
+  anything. State machine is inverted from Postgres.
+- **Auth plugins can switch mid-handshake.** The server may reply with an
+  `AuthSwitchRequest (0xFE)` asking for a different plugin's response.
+  Dispatcher lives in `auth/dispatcher.ts`.
+- **`caching_sha2_password` full-auth over plain TCP** needs RSA pubkey
+  retrieval. Gate behind `allowPublicKeyRetrieval: boolean` (default false,
+  matches JDBC).
+- **Empty-password `mysql_native_password`.** The auth response field is
+  zero bytes long (NOT 20 zero bytes). Common bug.
+- **`?` placeholders**, not `$N`. `sql.ts` doesn't need renumbering.
+
+## Testing
+
+```bash
+bun test                    # all tests
+bun test tests/unit         # pure unit tests (no DB)
+bun test tests/integration  # mock-server + docker-compose matrix
+```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skelpo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,76 @@
+# @perryts/mysql
+
+Pure-TypeScript MySQL / MariaDB wire-protocol driver. Runs on Node.js and
+Bun, and ahead-of-time compiles to a native binary via
+[Perry](https://github.com/perryts/perry) (LLVM). Zero native dependencies.
+
+Sibling package of
+[@perryts/postgres](https://github.com/perryts/postgres).
+
+## Status
+
+v0.1 — **all milestones shipped**:
+
+- [x] M1: Packet framing (3-byte length + seq id, >16 MB chains) + lenenc codecs
+- [x] M2: HandshakeV10 + HandshakeResponse41 + `COM_QUERY`
+- [x] M3: Auth plugins (`mysql_native_password`, `caching_sha2_password`,
+        `sha256_password`, `mysql_clear_password`, MariaDB `client_ed25519`)
+        + mid-handshake auth-switch
+- [x] M4: Prepared protocol: `COM_STMT_PREPARE` / `EXECUTE` / `CLOSE` +
+        per-connection prepared cache + binary-resultset decoder
+- [x] M5: Rich type codecs — `Decimal`, `MyDate` / `MyTime` / `MyDateTime`,
+        23 built-ins + `registerType()` extension point
+- [x] M6: TLS (`SSLRequest` + `sslmode`), `Pool`, `Connection.cancel()`
+        via `KILL QUERY`, `sql\`\`` template, `parseConnectionString`,
+        `resolveConnectOptions`
+- [x] M7: Multi-resultset (`resultSets` on `QueryResult`), LOCAL_INFILE
+        refusal by default, benchmark harness, smoke examples
+
+## Quickstart
+
+```ts
+import { connect } from '@perryts/mysql';
+
+const conn = await connect({
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: 'secret',
+    database: 'test',
+});
+
+const result = await conn.query('SELECT ? + ? AS sum', [40, 2]);
+console.log(result.rows); // [ { sum: 42 } ]
+
+await conn.close();
+```
+
+## Testing
+
+```sh
+bun run verify       # typecheck + bun test + node TLS tests + build
+bun test             # 135 unit + integration tests against mock server
+bun run test:tls:node  # TLS mid-stream upgrade under Node (Bun stalls on tls.connect({socket}))
+bun run test:real    # docker MySQL 8 + MariaDB 11 integration matrix
+```
+
+## Benchmarks
+
+```sh
+(cd bench && bun install)  # pulls mysql2 / mysql into bench/node_modules only
+MYSQL_HOST=127.0.0.1 MYSQL_TCP_PORT=33306 MYSQL_USER=... \
+  bash bench/run-all.sh    # runs @perryts/mysql, mysql2, mysql legacy side by side
+```
+
+## Design notes
+
+- No `pg`-style OIDs: MySQL identifies types via a single `MYSQL_TYPE_*`
+  byte + a 2-byte flag field. Codecs key on those.
+- Binary protocol for parameterised queries, text protocol for parameter-less.
+- Rows returned as `{ fields, rows, rowsArray, rowsRaw, command, rowCount }`
+  (raw bytes for GUI consumers + decoded objects for ergonomics).
+- Zero dependencies at runtime. `mysql2` / `mysql` are dev-only (bench only).
+
+## License
+
+MIT.

bench/README.md

@@ -0,0 +1,29 @@
+# Benchmarks
+
+Compares `@perryts/mysql` against `mysql2` and the legacy `mysql` driver.
+
+## Setup
+
+```sh
+docker compose -f ../tests/integration/docker-compose.yml up -d
+# Create the benchmark tables (see workloads.ts for schema expectations):
+mysql -h 127.0.0.1 -P 33306 -uroot -prootpw perry_test < seed.sql
+```
+
+## Run
+
+```sh
+MYSQL_HOST=127.0.0.1 MYSQL_TCP_PORT=33306 \
+MYSQL_USER=root MYSQL_PASSWORD=rootpw MYSQL_DATABASE=perry_test \
+bun bench/bench-this.ts
+```
+
+Per-workload stats are printed as `min / median / mean / p95 / max` in ms.
+
+## Workloads
+
+- **tiny** — `SELECT 1`, text protocol. Measures fixed overhead.
+- **param-1row** — `SELECT ?`, prepared protocol, one row. Measures
+  Parse / Execute / Sync fixed cost.
+- **medium-1k-x-20** — 1 000 rows × 20 columns. Measures per-row decode.
+- **large-10k-x-20** — 10 000 rows × 20 columns. Measures bulk throughput.