Ryan Malloy f202dbce0c Initialize Phase 0 spike scaffold

Project goal: pure-Python implementation of the Informix SQLI wire
protocol. No CSDK, no JVM, no native deps. Targets icr.io/informix
/informix-developer-database (port 9088) as the dev/test instance.

Phase 0 is a documentation-only spike that gates all implementation
work. The four scaffolds:

- README.md: project status and Phase 0 deliverable index
- docs/PROTOCOL_NOTES.md: byte-level wire-format reference (TBD)
- docs/JDBC_NOTES.md: reverse-lookup index into the decompiled IBM
  JDBC driver (4.50.4.1), populated from build/jdbc-src/ once the
  decompile lands
- docs/DECISION_LOG.md: running rationale, with the Phase-1 paramstyle
  /Python-floor/autocommit decisions pre-locked so they don't churn
  later

CLAUDE.md is gitignored — operator-private context, public-PyPI repo.

2026-05-02 13:22:28 -06:00

3.7 KiB

Raw Blame History

SQLI Wire Protocol Notes

Phase 0 spike artifact. This is the byte-level reference document for the Informix SQLI wire protocol, derived from a combination of packet captures against the IBM Informix Developer Edition Docker image and clean-room study of the decompiled IBM JDBC driver (com.ibm.informix:jdbc:4.50.4.1). It is the canonical reference that all subsequent implementation phases depend on.

Current state: scaffold only. Sections fill in as the spike proceeds.

Source attribution conventions

Each documented byte sequence cites both sources of evidence:

🔵 PCAP: observed in docs/CAPTURES/<file>.pcap at offset <n>
🟡 JDBC: cross-referenced against <class>.<method>() in the decompiled tree (see JDBC_NOTES.md)

A finding is considered confirmed only when 🔵 and 🟡 corroborate. Single-source observations are flagged 🟠 unverified.

1. Connection establishment

TCP setup

Port: 9088 (SQLI native, default)
Protocol: TCP, no TLS in plain mode
Who speaks first: TBD

Initial banner / capability exchange

TBD

Message ordering

TBD

Offset	Width	Field	Notes
TBD	TBD	TBD	TBD

Username encoding

TBD

Password encoding (plain auth, no obfuscation)

TBD

Database selection

TBD (during login, or separate USE-DATABASE message?)

Server response on success

TBD

Server response on auth failure

TBD

3. Message framing

Header layout

TBD — fields: type tag, length, flags?

Length field

Width: TBD bytes
Endianness: TBD
Value semantics: payload-only or whole-message?

Endianness (overall)

TBD

Message type tags

Tag (hex)	Direction	Name	Purpose
TBD	TBD	TBD	TBD

4. Statement execution: `SELECT 1`

Request

TBD

Response

TBD

Type code observed for the literal `1`

TBD

5. Result-set framing

Column descriptor block

TBD — fields per column: name, type code, precision/scale, nullability flag, …

Row encoding

TBD — fixed-position fields? null bitmap? per-field length prefix?

End-of-result marker

TBD

6. Error responses

Error packet format

TBD — fields: SQLSTATE, native error code, message text

Encoding

TBD

7. Disconnection

Client→server logout message

TBD

Server-side close behavior

TBD

8. Type codecs

IDS type codes observed in column descriptors

Code (decimal/hex)	IDS Type	Wire format	Notes
TBD	SMALLINT	TBD
TBD	INTEGER	TBD
TBD	BIGINT	TBD
TBD	FLOAT	TBD
TBD	CHAR	TBD
TBD	VARCHAR	TBD
TBD	BOOLEAN	TBD
TBD	DATE	TBD	4-byte day count from 1899-12-31 (Informix epoch); confirm

(DATETIME, INTERVAL, DECIMAL, BLOBs etc. are out of scope for Phase 0; see DECISION_LOG.md.)

9. Open questions

List things observed in JDBC source or packet captures that we don't yet understand. Each entry is either resolved-and-removed or escalated to DECISION_LOG.md as a deferred item.

(none yet)

10. Cross-checks

JDBC ↔ PCAP corroboration matrix

Phase 0 milestone	JDBC source confirms	PCAP confirms	Status
Login byte layout	⬜	⬜	pending
`SELECT 1` round-trip	⬜	⬜	pending
Error response structure	⬜	⬜	pending
Disconnection	⬜	⬜	pending

Phase 0 exit requires all four rows = ✅✅ confirmed.

3.7 KiB Raw Blame History