Áttekintés

A dbx egy önálló Go modul (github.com/gp-system/dbx): adatbázis-agnosztikus kontrakt, nem driver. Mindössze két dolgot definiál: a Config-ot, ami egy PostgreSQL-kapcsolatot ír le, és a Transactor interfészt, amitől a service-ek függenek, hogy egy tranzakcióban több repositoryt fogjanak össze. A gyökér package-nek saját adatbázis-driver függősége nincs: a tényleges implementáció egy alcsomagban él, és azzal választod ki, hogy melyiket importálod:

• dbx/pg: a pgx-natív stack (az alapértelmezés): pool-építés, a DBTX query executor és egy pgx.Tx-re épülő Transactor.
• dbx/bunx: opcionális adapter azoknak a projekteknek, amik a bun query buildert preferálják, bun.Tx-re épülve.

Egy binárisba mindig csak az egyik linkelődik be. A service- és repository-réteged a dbx.Transactor-tól és a dbx.Config-tól függ, sosem a konkrét implementációtól. Ezért egy service kódja betűre azonos, akár pgx, akár bun fut alatta. A dbx a kittel és anélkül is ugyanúgy működik; a gpsystem kit new project/new module generátorai csupán kiválasztják neked az egyik alcsomagot, és bekötik a generált main.go-ba.

Telepítés

go get github.com/gp-system/dbx@v0.1.0 # a kit is ezt a taget használja
go get github.com/gp-system/dbx@latest

Go 1.25+. A gyökér dbx package csak az errs-től függ; ami driver-specifikus, az a saját importja mögött él, tehát hogy mit húzol be ténylegesen, az alcsomagtól függ:

Egy projekt, ami csak a dbx/pg-t importálja, sosem linkeli be a bunt a binárisába, és fordítva.

Config

A dbx.Config egyetlen PostgreSQL-kapcsolat leírása. Az alkalmazás konfig-structjába prefixszel komponálod be:

type Config struct {
    DB dbx.Config `envPrefix:"DB_"`
}

Ezzel a következő env-változókra képződik le (a generált projektek .env.example-je pontosan ezeket sorolja fel):

A DSN() metódus postgres:// kapcsolati URL-lé rendereli a konfigot. Ezt fogyasztja a pg.NewPool és a generált cmd/migrate bináris is. A betöltést az envconf végzi, .env-támogatással.

Nevesített kapcsolatok

Egy modul default kapcsolata, a DB_* alatt komponált cfg.DB, fedi a gyakori esetet: egy projekt, egy adatbázis, egy connector. Egy második, független kapcsolat ugyanígy komponálódik, saját prefix alatt, envconf.LoadPrefixed-szel betöltve:

type Config struct {
    DB          dbx.Config `envPrefix:"DB_"`
    DBAnalytics dbx.Config `envPrefix:"DB_ANALYTICS_"`
}

ami a DB_ANALYTICS_HOST, DB_ANALYTICS_USER és így tovább változókat olvassa, teljesen függetlenül az első kapcsolat pooljától, tranzakciójától és hibakezelésétől. Generált projektben ezt a mintát az add db generátor drótozza be helyetted: saját dbx.Config-ot DB_<NÉV>_* alatt, saját pgx poolt, és <Név>DB / <Név>Transactor mezőket a modul Dependencies-én.

A connector (pgx vagy bun) kapcsolatonként dől el, nem projektenként: egy modul kombinálhat pgx-natív defaultot bun-alapú nevesített kapcsolattal, vagy fordítva. Ez egyenesen a lenti Transactor-határból következik: a WithinTransaction egyik kapcsolaton sem terjed át a másikra, így nincs kapcsolatok közötti tranzakció, amit konzisztensen kellene tartani, és nincs ok minden kapcsolatot ugyanarra a stackre kényszeríteni. Az add surface --db egy modul közös repository-vázát köti egy nevesített kapcsolathoz; a cmd/migrate mindig csak a default kapcsolatot célozza.

Transactor

type Transactor interface {
    WithinTransaction(ctx context.Context, fn func(ctx context.Context) error) error
}

Ez az egyetlen interfész, amin keresztül az alkalmazáskód tranzakciót kezel. A tranzakciót a context hordozza, így az fn-en belül minden adatbázis-hívás, a dbx/pg DB-jén vagy a dbx/bunx resolverein keresztül, automatikusan csatlakozik hozzá, anélkül hogy a repositoryk tudnának róla. nil-re commit, hibára vagy panicre rollback; beágyazott hívás a külső tranzakcióhoz csatlakozik. A teljes szemantikát és a mintát a Tranzakciók oldal tárgyalja.

A tranzakció a contextben utazik, nem egy globális connection-menedzserben.

Melyiket válaszd: pgx vagy bun?

A választás projektenkénti és a generáláskor dől el (--db pgx|bun, default pgx), ha a kit generátorait használod; a manifest rögzíti, és minden későbbi generátor ehhez igazodik: lásd new project. Önállóan, kit nélkül a választás egyszerűen az, melyik alcsomagot importálod.

Ökölszabály: ha szeretsz SQL-t írni, maradj a pgx-nél: kevesebb réteg, kevesebb meglepetés. Ha egy query buildert szeretnél struct-alapú modellekkel, a bun ismerős lesz, de nem egy ActiveRecord/Eloquent-stílusú ORM, és ezt érdemes előre tudni.

Szándékosan nincs ORM-absztrakció

A kit elve itt is a centralizál, nem absztrahál: a dbx nem definiál közös query-interfészt a két stack fölé. A dbx/pg pgx.Rows-t ad vissza, a dbx/bunx bun.IDB-t. A pgx és a bun upstream dokumentációja, példái és Stack Overflow-válaszai változtatás nélkül érvényesek a projektedre. A közös nevező tudatosan minimális: a kapcsolat leírása (Config) és a tranzakció-határ (Transactor), mert ez a kettő az, amitől a service-rétegnek függenie kell.

Ebből következik a séma-kezelés is: nincs schema builder, a migrációk sima, beágyazott SQL-fájlok.

A szekció oldalai

• pgx: a default stack: pool, DBTX, DB, repositoryk
• bun: az opcionális query builder adapter
• Tranzakciók: a Transactor minta mélységében, a PlaceOrder példával
• Seederek: idempotens alapadat a dbx/seed-del és a dbx/seed/bunx-szal
• Migrációk: számozott SQL-fájlok, beágyazva, saját cmd/migrate binárissal