end
7647884464
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>
71 lines
2.2 KiB
Markdown
71 lines
2.2 KiB
Markdown
# dbx
|
|
|
|
**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`.
|