Ryan Malloy
ea00990774
Polish item #1: byte-for-byte regression test that asserts our generated login PDU is structurally identical to JDBC's reference captured in docs/CAPTURES/01-connect-only.socat.log. The test (tests/test_pdu_match.py) immediately caught a real bug: the capability section was misread during Phase 0 byte-decoding. Earlier text claimed Cap_1=1, Cap_2=0x3c000000, Cap_3=0 — actually: Cap_1 = 0x0000013c (= (capability_class << 8) | protocol_version where protocol_version = 0x3c = PF_PROT_SQLI_0600) Cap_2 = 0 Cap_3 = 0 The misalignment was: the 0x3c byte I attributed to Cap_2's high byte was actually Cap_1's low byte. The dev-image server is permissive enough to accept arbitrary capability values, so the connection succeeded even with the wrong bytes — but the PDU wasn't structurally identical to JDBC's reference. SERVER-ACCEPTS ≠ STRUCTURALLY-CORRECT. This is exactly why the byte-for-byte diff was the right polish item; "it connects" was a false ceiling. After fix: - 6 PDU-match tests assert byte-for-byte equality at offsets 2..280 (the structural prefix: SLheader sans length, all login markers, capability ints, username, password, protocol IDs, env vars). - Bytes 280+ legitimately differ per process (PID, TID, hostname, cwd, AppName) — those are NOT asserted. - Length field (offsets 0..1) also legitimately differs because our PDU has shorter env list and AppName. - Test uses monkey-patched IfxSocket so no network is needed. Polish item #2: Makefile per global CLAUDE.md convention. Targets: install, lint, format, test, test-integration, test-all, test-pdu, ifx-up/down/logs/shell/status, capture (re-run JDBC scenarios under socat), clean. `make` (no target) prints help. Doc updates: - PROTOCOL_NOTES.md §12: corrected capability section with the actual values and an explanation of the methodology lesson - DECISION_LOG.md: new entry recording the correction with a pointer to the regression test and the takeaway Side artifacts: - docs/CAPTURES/03-py-connect-only.socat.log - docs/CAPTURES/04-py-no-database.socat.log - docs/CAPTURES/05-py-fixed-caps.socat.log Test counts: 40 unit + 6 integration = 46 total, all green, ruff clean.
informix-db
Pure-Python driver for IBM Informix IDS, speaking the SQLI wire protocol over raw sockets. No IBM Client SDK. No JVM. No native libraries.
Status
🟢 Phase 1 complete. connect() / close() work end-to-end against a real Informix server. Cursor / execute / fetch land in Phase 2.
To our knowledge this is the first pure-socket Informix driver in any language — every other Informix driver (IfxPy, the legacy informixdb, ODBC bridges, Perl DBD::Informix) wraps either IBM's CSDK or the JDBC JAR.
Quick start
import informix_db
with informix_db.connect(
host="127.0.0.1", port=9088,
user="informix", password="in4mix",
database="sysmaster", server="informix",
) as conn:
# cursor() / execute() / fetchone() arrive in Phase 2
pass
Test against the official Informix dev container
docker compose -f tests/docker-compose.yml up -d # IBM Developer Edition, pinned by digest
uv sync --extra dev
uv run pytest # 34 unit tests (no Docker needed)
uv run pytest -m integration # 6 integration tests (needs the container)
Phase 0 artifacts (still useful — they ARE the public reference)
docs/PROTOCOL_NOTES.md— byte-level wire-format reference, derived from packet captures + JDBC decompilation, validated against a real serverdocs/JDBC_NOTES.md— index into the decompiled IBM JDBC driver's wire-protocol classesdocs/DECISION_LOG.md— running rationale for protocol / auth / type decisionsdocs/CAPTURES/— socat hex-dump captures of three reference scenarios (connect, SELECT, full DML cycle)tests/reference/RefClient.java— re-runnable JDBC ground-truth client for capturing fresh traces
License
MIT.