dbx/README.md

dbx

Database extensions — a small toolkit of reusable database helpers built on Jet and go-toolkit/app.

Install

go get gitea.auvem.com/go-toolkit/dbx

Quick start

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 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.