SQLC/database/sql support (no implementation changes)

[Copilot]

Implement MVP support for Go database/sql + sqlc via a stable C ABI, a cgo-backed driver, and a minimal sqlc configuration/example while keeping scope limited to the Baseline API and $N parameters.

• Implementation
  • No changes applied.
• Tests
  • No changes applied.
• Docs
  • No changes applied.

No example snippet; no implementation changes were made.

Original prompt

You are a coding agent working in the DecentDB repo. Implement MVP support for Go database/sql + sqlc as specified in SQLC_SUPPORT.md, without expanding scope to SQLAlchemy/Dapper.

Read first (required):

• AGENTS.md (repo workflow + DoD)
• PRD.md, SPEC.md, TESTING_STRATEGY.md
• 0005-sql-parameterization-style.md and 0023-isolation-level-specification.md

Goal (MVP):

1. Add a stable C ABI to the Nim engine with streaming statements (prepare/bind/step/column/finalize) and error reporting (last_error_code/message) matching the “Baseline API” in SQLC_SUPPORT.md.
2. Add a Go database/sql/driver implementation (decentdb driver name) that uses cgo to call the C ABI, supports $1..$N parameters, and passes end-to-end tests.
3. Add minimal docs and an example sqlc config demonstrating engine: postgresql so generated SQL uses $N.

Scope constraints:

• Do NOT change any persistent formats (db header/page/WAL formats). If you think you must, stop and propose an ADR.
• Do NOT implement native row batching/row-view ABI unless you first add an ADR (the doc explicitly calls this out). MVP can use per-column accessors even if it’s slower; keep the API extensible for a later optimization pass.
• Avoid new dependencies unless truly necessary; if you must add one, justify it and keep it minimal.

Implementation tasks (deliverables):
A) Nim C ABI

• Add a new Nim module (prefer a single focused module, e.g., “c_api”) exporting C-callable functions with cdecl, and opaque handle types for decentdb_db* and decentdb_stmt*.
• Implement the full baseline surface:
  • decentdb_open(path_utf8, options_utf8) -> decentdb_db*
  • decentdb_close(db) -> int
  • decentdb_last_error_code(db) -> int
  • decentdb_last_error_message(db) -> const char*
  • decentdb_prepare(db, sql_utf8, out_stmt**) -> int
  • decentdb_bind_null/int64/float64/text/blob(stmt, index_1_based, ...) -> int
  • decentdb_step(stmt) -> int (1 row, 0 done, <0 error)
  • decentdb_column_count/name/type(stmt, col_0_based) -> ...
  • decentdb_column_is_null/int64/float64/text/blob(stmt, col_0_based, ...) -> ...
  • decentdb_rows_affected(stmt) -> int64
  • decentdb_finalize(stmt) -> void
• Enforce the pointer lifetime rules described in the doc: anything returned as const char* or const uint8_t* is a borrowed view valid until the next mutation of the same handle or finalize/close. Keep it safe and deterministic.
• Make error storage predictable (per-db handle is fine for MVP); ensure errors are set on failure paths consistently.

B) Build output for native library

• Update Nimble/build scripts so the repo can produce a shared library (.so on Linux; keep hooks for macOS/Windows but Linux support is the immediate target).
• Provide a simple developer workflow to build it (document the exact command).

C) Go driver (database/sql/driver)

• Create a Go module inside the repo (pick a sane folder like bindings/go/decentdb-go/).
• Implement driver.Driver, plus context-aware interfaces: QueryContext, ExecContext, BeginTx, and PrepareContext where applicable.
• DSN format: support file:/absolute/path/to.db?cache_size=...&busy_timeout_ms=...&fsync=on|off (parse with net/url). Unknown options should error (or be clearly ignored with a comment + test).
• Parameters:
  • Accept only $N placeholders; reject ? and named params rather than rewriting.
  • Bind supported Go types: nil, int64/int, float64, bool, string, []byte, time.Time (epoch-ms UTC).
• Rows:
  • Implement forward-only Rows.Next and decode columns into driver.Value.
  • Copy TEXT/BLOB out of the native borrowed buffers immediately.
• Transactions:
  • Implement BeginTx/Commit/Rollback via SQL (BEGIN/COMMIT/ROLLBACK) or direct engine hooks if they exist; keep semantics consistent with Snapshot Isolation (don’t claim stronger).
• Error mapping:
  • Introduce a structured Go error type (like DecentDBError{Code, Message, SQL}) and map “bad connection” cases to driver.ErrBadConn.
  • Respect context cancellation best-effort (at least check ctx before/after stepping rows).

D) Tests + docs (Definition of Done)

• Add Nim tests that exercise the C ABI directly (open, prepare, bind, step, column reads, finalize, error paths).
• Add Go integration tests using testing + database/sql that:
  • open a temp db file
  • CREATE TABLE, INSERT, SELECT with $1 bindings
  • transaction commit/rollback behavior
• Add a small doc section and/or example files showing sqlc config (engine: postgresql) and a tiny queries.sql and usage snippet.

Validation commands (run locally as part of the work):

• nimble test (or the repo’s existing test runner; discover and use the standard one)
• go test source. within the Go module folder
• If there is an existing “comprehensive” test binary in the repo, run the smallest relevant subset and report results.

Output expectations:

• Keep changes minimal and focused.
• Provide a brief su...

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Copilot wasn't able to review any files in this pull request.

[sphildreth]

@copilot What am I reviewing? There are no files modified?