Skip to content

The only tool you need to know what is happening and how to fix it.

updated: lit version + claude.md for lit

narrow-adventure2c58eb6b4e20
diff --git a/CLAUDE.md b/CLAUDE.md
index 36a9542c..520151cb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,20 +39,21 @@ Traceway is an error tracking and monitoring platform consisting of:
- **CLI**: Go 1.26, Cobra 1.10, separate Go module (`github.com/tracewayapp/traceway/cli`); flake.nix dev shell, justfile entrypoints
- **Client SDK**: Go 1.25, Gin middleware support
-### go-lightning Library (PostgreSQL ORM)
-- **Import**: `github.com/tracewayapp/go-lightning/lit`
-- **Purpose**: Lightweight generic CRUD operations for PostgreSQL
+### lit Library (SQL mapper)
+- **Import**: `github.com/tracewayapp/lit/v2` (currently v2.0.5)
+- **Purpose**: Lightweight generic CRUD operations on top of `database/sql`. Supports PostgreSQL, MySQL, SQLite, and DuckDB drivers (`lit.PostgreSQL`, `lit.MySQL`, `lit.SQLite`, `lit.DuckDB`). Traceway registers models against `db.Driver` (SQLite or PostgreSQL depending on build tags); the DuckDB telemetry backend deliberately keeps `lit.SQLite` for reads since DuckDB accepts `?` placeholders.
+- **Docs for AI use**: the lit repo ships a skill at `skills/lit/SKILL.md` plus `llms.txt` with the full API contract and pitfall checklist.
#### Model Registration (required before use)
-All models are registered centrally in `models/models.go` via `models.Init()`:
+All models are registered centrally in `models/models.go` via `models.Init(driver lit.Driver)`, called at boot with `db.Driver`:
```go
-func Init() {
- lit.RegisterModel[User](lit.PostgreSQL)
- lit.RegisterModel[Project](lit.PostgreSQL)
+func Init(driver lit.Driver) {
+ lit.RegisterModel[User](driver)
+ lit.RegisterModel[Project](driver)
// ...all models registered here
}
```
-Repository-local result models (e.g., aggregate structs only used in one repo) can use file-level `init()` instead.
+Repository-local result models (e.g., aggregate structs only used in one repo) can use file-level `init()` instead. Irregular table names use `lit.RegisterModelWithNaming` with a struct embedding `lit.DefaultDbNamingStrategy` (see `escalationPolicyNaming` in `models.go`).
#### Naming Conventions
- Fields: CamelCase → snake_case (`FirstName` → `first_name`)
@@ -61,7 +62,7 @@ Repository-local result models (e.g., aggregate structs only used in one repo) c
- Override via struct tag: `lit:"custom_name"`
#### Core CRUD Operations
-All lit functions take `*sql.Tx` as the first argument for transactional consistency:
+All lit functions take a `lit.Executor` as the first argument. Both `*sql.Tx` and `*sql.DB` qualify: main-DB repositories pass the `*sql.Tx` from the transaction middleware, telemetry repositories pass `db.TelemetryDB` directly.
| Function | Description |
|----------|-------------|
@@ -72,7 +73,10 @@ All lit functions take `*sql.Tx` as the first argument for transactional consist
| `lit.SelectSingle[T](tx, query, args...)` | Retrieve one record (returns `*T`) |
| `lit.Update[T](tx, &entity, "id = $1", id)` | Update (auto-prepends WHERE) |
| `lit.UpdateNative(tx, "UPDATE table SET col = $1 WHERE ...", args...)` | Raw SQL update for partial/single-field changes |
-| `lit.Delete(tx, "DELETE FROM table WHERE id = $1", id)` | Delete records |
+| `lit.Delete(tx, "DELETE FROM table WHERE id = $1", id)` | Delete records (any exec statement) |
+| `lit.SelectNamed[T]` / `lit.SelectSingleNamed[T]` / `lit.UpdateNamed[T]` | `:name` placeholder variants taking a `lit.P{...}` map; render per-driver, used for dialect-neutral queries |
+| `lit.DeleteNamed(driver, tx, query, lit.P{...})` | Named delete/exec. Gotcha: takes the driver as the FIRST argument |
+| `lit.ParseNamedQuery(driver, query, lit.P{...})` | Renders `:name` to positional; escape hatch for `QueryContext`/`RowsAffected` via `database/sql` |
#### Transaction Helper (`pgdb.ExecuteTransaction`)
All PostgreSQL operations should use `ExecuteTransaction` for automatic commit/rollback:
diff --git a/backend/app/controllers/dashboard_template_seed_test.go b/backend/app/controllers/dashboard_template_seed_test.go
index 63fcaf47..48a5cd0e 100644
--- a/backend/app/controllers/dashboard_template_seed_test.go
+++ b/backend/app/controllers/dashboard_template_seed_test.go
@@ -1,4 +1,4 @@
-//go:build !telemetry_ch && !transactional_pg
+//go:build !telemetry_ch && !transactional_pg && !telemetry_duckdb
package controllers
diff --git a/backend/app/migrations/duckdb_telemetry/0004_add_output_key_to_check_results.up.sql b/backend/app/migrations/duckdb_telemetry/0004_add_output_key_to_check_results.up.sql
index 2b291eec..8298f389 100644
--- a/backend/app/migrations/duckdb_telemetry/0004_add_output_key_to_check_results.up.sql
+++ b/backend/app/migrations/duckdb_telemetry/0004_add_output_key_to_check_results.up.sql
@@ -1 +1 @@
-ALTER TABLE check_results ADD COLUMN output_key VARCHAR NOT NULL DEFAULT '';
+ALTER TABLE check_results ADD COLUMN output_key VARCHAR DEFAULT '';
diff --git a/backend/go.mod b/backend/go.mod
index 742711fb..f76361ba 100644
--- a/backend/go.mod
+++ b/backend/go.mod
@@ -18,7 +18,7 @@ require (
github.com/lib/pq v1.10.9
github.com/markbates/goth v1.82.0
github.com/modelcontextprotocol/go-sdk v1.6.1
- github.com/tracewayapp/lit/v2 v2.0.2
+ github.com/tracewayapp/lit/v2 v2.0.5
github.com/tracewayapp/traceway/cli v1.9.15
go.opentelemetry.io/collector/component v1.60.0
go.opentelemetry.io/collector/component/componenttest v0.154.0
diff --git a/backend/go.sum b/backend/go.sum
index 110e73b2..966cf634 100644
--- a/backend/go.sum
+++ b/backend/go.sum
@@ -336,8 +336,8 @@ github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRU
github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI=
github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4=
github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg=
-github.com/tracewayapp/lit/v2 v2.0.2 h1:ZE8UlRWUOX3OZvY2UfbYSDcDUpBoTNLXl70Qujs0mqs=
-github.com/tracewayapp/lit/v2 v2.0.2/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
+github.com/tracewayapp/lit/v2 v2.0.5 h1:BMPopt9xMZqMgIEwDFIRRV+rrDczajGAlV5Md2AsxPM=
+github.com/tracewayapp/lit/v2 v2.0.5/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
github.com/ugorji/go/codec v1.3.0 h1:Qd2W2sQawAfG8XSvzwhBeoGq71zXOC/Q1E9y/wUcsUA=
diff --git a/cli/test/contract/go.mod b/cli/test/contract/go.mod
index 7ff7ceac..b1e388db 100644
--- a/cli/test/contract/go.mod
+++ b/cli/test/contract/go.mod
@@ -100,7 +100,7 @@ require (
github.com/shopspring/decimal v1.4.0 // indirect
github.com/tklauser/go-sysconf v0.4.0 // indirect
github.com/tklauser/numcpus v0.12.0 // indirect
- github.com/tracewayapp/lit/v2 v2.0.2 // indirect
+ github.com/tracewayapp/lit/v2 v2.0.5 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.0 // indirect
github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
diff --git a/cli/test/contract/go.sum b/cli/test/contract/go.sum
index e23b131e..fb75cd5d 100644
--- a/cli/test/contract/go.sum
+++ b/cli/test/contract/go.sum
@@ -282,8 +282,8 @@ github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRU
github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI=
github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4=
github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg=
-github.com/tracewayapp/lit/v2 v2.0.2 h1:ZE8UlRWUOX3OZvY2UfbYSDcDUpBoTNLXl70Qujs0mqs=
-github.com/tracewayapp/lit/v2 v2.0.2/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
+github.com/tracewayapp/lit/v2 v2.0.5 h1:BMPopt9xMZqMgIEwDFIRRV+rrDczajGAlV5Md2AsxPM=
+github.com/tracewayapp/lit/v2 v2.0.5/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
github.com/ugorji/go/codec v1.3.0 h1:Qd2W2sQawAfG8XSvzwhBeoGq71zXOC/Q1E9y/wUcsUA=
diff --git a/examples/devtesting-embedded/go.mod b/examples/devtesting-embedded/go.mod
index b9edb172..e6787cff 100644
--- a/examples/devtesting-embedded/go.mod
+++ b/examples/devtesting-embedded/go.mod
@@ -109,7 +109,7 @@ require (
github.com/shopspring/decimal v1.4.0 // indirect
github.com/tklauser/go-sysconf v0.4.0 // indirect
github.com/tklauser/numcpus v0.12.0 // indirect
- github.com/tracewayapp/lit/v2 v2.0.2 // indirect
+ github.com/tracewayapp/lit/v2 v2.0.5 // indirect
github.com/tracewayapp/traceway/cli v1.9.15 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.1 // indirect
diff --git a/examples/devtesting-embedded/go.sum b/examples/devtesting-embedded/go.sum
index bc79250b..7d1d8243 100644
--- a/examples/devtesting-embedded/go.sum
+++ b/examples/devtesting-embedded/go.sum
@@ -288,8 +288,8 @@ github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRU
github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI=
github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4=
github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg=
-github.com/tracewayapp/lit/v2 v2.0.2 h1:ZE8UlRWUOX3OZvY2UfbYSDcDUpBoTNLXl70Qujs0mqs=
-github.com/tracewayapp/lit/v2 v2.0.2/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
+github.com/tracewayapp/lit/v2 v2.0.5 h1:BMPopt9xMZqMgIEwDFIRRV+rrDczajGAlV5Md2AsxPM=
+github.com/tracewayapp/lit/v2 v2.0.5/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
diff --git a/examples/embedded-backend-go-client/go.mod b/examples/embedded-backend-go-client/go.mod
index 6bc1b908..fa0db767 100644
--- a/examples/embedded-backend-go-client/go.mod
+++ b/examples/embedded-backend-go-client/go.mod
@@ -78,7 +78,7 @@ require (
github.com/segmentio/asm v1.2.1 // indirect
github.com/segmentio/encoding v0.4.0 // indirect
github.com/shopspring/decimal v1.4.0 // indirect
- github.com/tracewayapp/lit/v2 v2.0.2 // indirect
+ github.com/tracewayapp/lit/v2 v2.0.5 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.0 // indirect
go.opentelemetry.io/otel v1.39.0 // indirect
diff --git a/examples/embedded-backend-go-client/go.sum b/examples/embedded-backend-go-client/go.sum
index a8e4d24a..c3521489 100644
--- a/examples/embedded-backend-go-client/go.sum
+++ b/examples/embedded-backend-go-client/go.sum
@@ -237,8 +237,8 @@ github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk=
-github.com/tracewayapp/lit/v2 v2.0.2 h1:ZE8UlRWUOX3OZvY2UfbYSDcDUpBoTNLXl70Qujs0mqs=
-github.com/tracewayapp/lit/v2 v2.0.2/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
+github.com/tracewayapp/lit/v2 v2.0.5 h1:BMPopt9xMZqMgIEwDFIRRV+rrDczajGAlV5Md2AsxPM=
+github.com/tracewayapp/lit/v2 v2.0.5/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
github.com/tracewayapp/traceway/backend v1.5.2 h1:MK2KceJCPfDmCqRQti9YRWax531MaTpdQBNCfFm7Xb4=
github.com/tracewayapp/traceway/backend v1.5.2/go.mod h1:BgPfL0a44LtR7MKTu+2uMc/e6imUi9vNhRj8HQMwwsk=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
diff --git a/examples/embedded-backend-otel/go.mod b/examples/embedded-backend-otel/go.mod
index fb25d6ca..96169be6 100644
--- a/examples/embedded-backend-otel/go.mod
+++ b/examples/embedded-backend-otel/go.mod
@@ -85,7 +85,7 @@ require (
github.com/segmentio/asm v1.2.1 // indirect
github.com/segmentio/encoding v0.4.0 // indirect
github.com/shopspring/decimal v1.4.0 // indirect
- github.com/tracewayapp/lit/v2 v2.0.2 // indirect
+ github.com/tracewayapp/lit/v2 v2.0.5 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.1 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
diff --git a/examples/embedded-backend-otel/go.sum b/examples/embedded-backend-otel/go.sum
index 2e4d4390..97cccf06 100644
--- a/examples/embedded-backend-otel/go.sum
+++ b/examples/embedded-backend-otel/go.sum
@@ -245,12 +245,8 @@ github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk=
-github.com/tracewayapp/lit/v2 v2.0.2 h1:ZE8UlRWUOX3OZvY2UfbYSDcDUpBoTNLXl70Qujs0mqs=
-github.com/tracewayapp/lit/v2 v2.0.2/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
-github.com/tracewayapp/traceway/backend v1.5.0 h1:eTwUnLW54GAIz87/Up8tKZo9KAAtWju8NbRBBi7H4z4=
-github.com/tracewayapp/traceway/backend v1.5.0/go.mod h1:BgPfL0a44LtR7MKTu+2uMc/e6imUi9vNhRj8HQMwwsk=
-github.com/tracewayapp/traceway/backend v1.5.1 h1:xUGk/0qbEPYFZM45VnXKFjnvAl57ebSeOr71bOf7W1k=
-github.com/tracewayapp/traceway/backend v1.5.1/go.mod h1:BgPfL0a44LtR7MKTu+2uMc/e6imUi9vNhRj8HQMwwsk=
+github.com/tracewayapp/lit/v2 v2.0.5 h1:BMPopt9xMZqMgIEwDFIRRV+rrDczajGAlV5Md2AsxPM=
+github.com/tracewayapp/lit/v2 v2.0.5/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
github.com/tracewayapp/traceway/backend v1.5.2 h1:MK2KceJCPfDmCqRQti9YRWax531MaTpdQBNCfFm7Xb4=
github.com/tracewayapp/traceway/backend v1.5.2/go.mod h1:BgPfL0a44LtR7MKTu+2uMc/e6imUi9vNhRj8HQMwwsk=
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=