docs: add V1 README, CHANGELOG, and package docs

Expand README with setup and API guidance, add CHANGELOG breaking section, and refresh package documentation for the V1 API surface. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-29 17:50:47 -07:00
parent 63187ee905
commit 7647884464
5 changed files with 116 additions and 4 deletions
@@ -1,3 +1,70 @@
 # dbx

-dbx (**D**ata**b**ase **E**extensions) is a small toolkit of common and reusable database helpers built around the [Jet](https://github.com/go-jet/jet) SQL builder. Provides an [app.Module](https://gitea.auvem.com/go-toolkit/app).
+**D**ata**b**ase e**x**tensions — a small toolkit of reusable database helpers built on [Jet](https://github.com/go-jet/jet) and [go-toolkit/app](https://gitea.auvem.com/go-toolkit/app).
+
+## Install
+
+```bash
+go get gitea.auvem.com/go-toolkit/dbx
+```
+
+## Quick start
+
+```go
+import (
+    "gitea.auvem.com/go-toolkit/app"
+    "gitea.auvem.com/go-toolkit/dbx"
+    _ "gitea.auvem.com/go-toolkit/dbx/dbxm" // MySQL debug logging only
+)
+
+func main() {
+    cfg := &dbx.DBConfig{
+        User:     "user",
+        Password: "pass",
+        URI:      "localhost:3306",
+        Name:     "mydb",
+        MaxConn:  10,
+    }
+
+    modules := []*app.Module{
+        dbx.ModuleDB(dbx.DialectMySQL, cfg, false),
+    }
+
+    app.Run(modules...)
+    db := dbx.SQLO()
+    _ = db
+}
+```
+
+For Postgres, use `dbx.DialectPostgres` and blank-import `dbxp` instead of `dbxm` when `DebugLog` is enabled.
+
+## Helper catalog
+
+| Area | Functions |
+|------|-----------|
+| Query | `Fetch`, `MustFetch`, `FetchOne`, `MustFetchOne` (+ `*Context` variants) |
+| Mutations | `Insert`, `InsertReturning`, `Update`, `UpdateAffected`, `UpdateReturning`, `Delete`, `DeleteAffected` (+ `*Context` variants) |
+| Transactions | `WithTx` |
+| Columns | `NormalCols`, `ContainsCol`, `ExprValues`, `ExprStringers` |
+| Partial update | `ApplyPtr`, `ApplyComplexPtr`, `ApplyInterfacePtr`, `ApplyVal` |
+| Pointers | `Ptr`, `Val`, `NowPtr`, `TrimPtr`, `TrimPtrToNil`, `IsZero` |
+| Types | `StringKSUID`, `BinaryKSUID`, `JSONB` |
+
+## KSUID type selection
+
+| Type | SQL column | Storage |
+|------|------------|---------|
+| `StringKSUID` | `VARCHAR(27)`, `TEXT` | Base62 string |
+| `BinaryKSUID` | `BINARY(20)`, `BYTEA` | Raw 20 bytes |
+
+Both types use identical GraphQL JSON transit (`ksuid_str` field). Pick the type that matches your column encoding — Scan rejects ambiguous payloads.
+
+## Dialect notes
+
+- **MySQL inserts:** use `Insert` for `LastInsertId` workflows.
+- **Postgres inserts:** use `InsertReturning` with a Jet `RETURNING` clause.
+- **Debug logging:** requires blank-import of `dbxm` or `dbxp` matching your dialect. Without it, module setup returns an error when `DebugLog` is true.
+
+## Documentation
+
+Package docs are available on pkg.go.dev and via `go doc gitea.auvem.com/go-toolkit/dbx`.