From 764788446418758472226b3a4c015b68d4c27bf7 Mon Sep 17 00:00:00 2001 From: Elijah Duffy Date: Mon, 29 Jun 2026 17:50:47 -0700 Subject: [PATCH] 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 --- CHANGELOG.md | 24 ++++++++++++++++++ README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++- dbxm/doc.go | 7 ++++++ dbxp/doc.go | 7 ++++++ doc.go | 13 +++++++--- 5 files changed, 116 insertions(+), 4 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 dbxm/doc.go create mode 100644 dbxp/doc.go diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7e8ee03 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +## Unreleased (v1.0.0) + +### Breaking changes + +- Removed `UUID`, `NewUUID`, and `ParseUUID`. +- Added `StringKSUID` and `BinaryKSUID` with distinct SQL encodings and shared GraphQL transit (`ksuid_str` JSON field, replacing `uuid_str`). +- Removed `DBConfig.AutoMigrate`, `SQLOFunc`, and `JSONB.ToMap()`. +- Replaced `Column` / `ColumnList` intersection interfaces with dialect-neutral type aliases. +- `Apply*` and `Expr*` helpers now accept `Column` / `ColumnList` / `Expression` aliases instead of `mysql.*` types. + +### Added + +- Context-aware variants for all query and mutation helpers. +- `Delete`, `DeleteAffected`, `WithTx`, `ContainsCol`, and `CurrentDialect()`. +- Package documentation (`doc.go`), expanded README, and subpackage docs for `dbxm` / `dbxp`. +- Comprehensive tests for KSUID types, CRUD helpers, column utilities, and module lifecycle. + +### Changed + +- Debug logger setup returns an error instead of panicking when `DebugLog` is enabled without a dialect logger blank import. +- `DestName` skips logging when the database module is not initialized. +- Source reorganized into domain-focused files (`query.go`, `exec.go`, `apply.go`, etc.). diff --git a/README.md b/README.md index fe22862..5126404 100644 --- a/README.md +++ b/README.md @@ -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`. diff --git a/dbxm/doc.go b/dbxm/doc.go new file mode 100644 index 0000000..bd9f052 --- /dev/null +++ b/dbxm/doc.go @@ -0,0 +1,7 @@ +// Package dbxm registers the MySQL Jet query debug logger for dbx. +// +// Blank-import this package when using dbx with MySQL and [dbx.DBConfig.DebugLog] +// is enabled: +// +// import _ "gitea.auvem.com/go-toolkit/dbx/dbxm" +package dbxm diff --git a/dbxp/doc.go b/dbxp/doc.go new file mode 100644 index 0000000..825afdd --- /dev/null +++ b/dbxp/doc.go @@ -0,0 +1,7 @@ +// Package dbxp registers the Postgres Jet query debug logger for dbx. +// +// Blank-import this package when using dbx with Postgres and [dbx.DBConfig.DebugLog] +// is enabled: +// +// import _ "gitea.auvem.com/go-toolkit/dbx/dbxp" +package dbxp diff --git a/doc.go b/doc.go index 75d4cbb..54e2e2d 100644 --- a/doc.go +++ b/doc.go @@ -3,12 +3,14 @@ // # Module lifecycle // // Call [ModuleDB] once to register the database [app.Module], then use [SQLO] -// to access the connection pool. Only one database per process is supported. +// to access the connection pool. [CurrentDialect] reports the configured dialect. +// Only one database per process is supported. // // # Query and mutation helpers // // [Fetch], [FetchOne], [Insert], [Update], [Delete], and their Must* and Context // variants wrap Jet [Statement] execution with consistent error semantics. +// [WithTx] runs a function inside a SQL transaction. // // # Jet column utilities // @@ -21,7 +23,11 @@ // # Identifier types // // [StringKSUID] and [BinaryKSUID] wrap segmentio/ksuid with storage-specific -// SQL encoding. [JSONB] provides map-based JSON column scanning. +// SQL encoding. Both share identical GraphQL string transit. Choose StringKSUID +// for text columns (VARCHAR, TEXT); choose BinaryKSUID for binary columns +// (BINARY(20), BYTEA). +// +// [JSONB] provides map-based JSON column scanning for Postgres JSONB and MySQL JSON. // // # Pointer and string utilities // @@ -31,7 +37,8 @@ // # Debug logging // // Enable [DBConfig.DebugLog] and blank-import dbxm (MySQL) or dbxp (Postgres) -// to register Jet query debug output. +// to register Jet query debug output. Setup returns an error if DebugLog is +// enabled without the matching blank import. // // # Dialect notes //