# 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`, `Query`, `MustQuery` (+ `*Context` variants) |
| Mutations | `Insert`, `InsertReturning`, `Update`, `UpdateAffected`, `UpdateOne`, `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 string scalar transit. 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`.