feat(compat): add Knex compatibility layer for MySQL and PostgreSQL

[jeremydaly]

Summary

Adds a Knex compatibility layer so the Data API Client can back Knex for both MySQL and PostgreSQL, closing the last gap among the supported query builders (Drizzle and Kysely already work). CRUD, the common query-builder surface, transactions, and upserts all work.

• Knex doesn't accept an injected pool like Drizzle/Kysely; it builds its own driver via Client._driver(). We subclass the mysql2 and pg dialects and override that single method to hand Knex a Data API-backed connection. Knex keeps full ownership of SQL generation; queries execute over the Data API.
• New data-api-client/compat/knex subpath exporting createKnexMySQLClient(config) and createKnexPgClient(config). knex is lazy-required and declared as an optional peer dependency (^3.0.0).
• Transactions work: the compat layer intercepts the literal BEGIN/COMMIT/ROLLBACK SQL Knex issues (src/compat/transaction-sql.ts) and maps it to the Data API transaction lifecycle, threading transactionId onto subsequent queries on that connection. db.transaction() commits on success and rolls back on a thrown callback.
• Query-builder coverage: 26 tests per engine exercise the common syntax from the Knex guide, including selects/distinct/pluck/first, the where family, joins, groupBy/having/aggregates, ordering/pagination, unions, subqueries, CTEs, insert/update/del, returning, increment/decrement, and onConflict().merge() upserts.

Bugs fixed along the way

These were latent in the shared compat layers and benefit non-Knex callers too:

• compat/pg binding clobber: the query({ text, values }, cb) callback form left params defaulting to [], which overrode config.values in executeQuery, so parameterized queries using node-postgres's config-object form lost their bindings (bind message supplies 0 parameters).
• compat/mysql2 callback parsing: query(config, undefined, cb) (the form Knex uses for bindings-less statements like BEGIN;) never picked up the third-argument callback, so the callback never fired and transactions hung. Fixed in all four query parsers.
• compat/pg CTE command inference: inferCommand() keyed off the first SQL word, so WITH ... SELECT was tagged QUERY instead of SELECT. node-postgres-driven callers (Knex/Kysely/Drizzle) read result shape off command, so a CTE returned the raw response object instead of rows. Now resolves the primary verb at parenthesis depth 0.

Test Plan

• Unit tests pass: npm run test:unit (157 passed)
• Knex integration, both engines: npm run test:int:orm:knex (74 passed)
  • CRUD, transactions (commit/rollback/nested-rejection), and the full query-builder coverage
• Regression: pg compat, Kysely, and Drizzle suites still pass (the shared compat/pg and compat/mysql2 fixes do not break existing callers)
• tsc build emits dist/compat/knex.{js,d.ts} and dist/compat/transaction-sql.js; ESLint clean

Integration tests require .env.local (live Aurora Serverless v2 clusters). Declared engines.node >= 20 (.nvmrc of 20) to match CI and the vitest 4 toolchain floor.

Limitations

• Nested transactions need SQL SAVEPOINTs, which the Data API has no primitive for, so a nested trx.transaction(...) throws a clear error. A single top-level transaction works.
• Streaming (.stream()) is unsupported, since the Data API has no cursor API.
• Knex's dedicated whereLike() appends COLLATE utf8_bin, which MySQL rejects on utf8mb4 columns. This is a Knex/MySQL quirk that affects real mysql2 too, not the compat layer; the portable where(col, 'like', val) form works.

Notes

• The deep import knex/lib/dialects/{mysql2,postgres} is Knex's documented-but-internal extension point, so a Knex major version could move it, which is why the peer range is ^3.0.0.
• This branch also carries a CLAUDE.md refresh, an npm audit fix for three dev-dependency advisories, and a note that .env.local must be sourced in the same shell command as the test run.