add db

add db gives a module a second, independent database connection, alongside its default one. Reach for it when a module needs its own pool: a separate analytics database, a reporting replica, or any connection that shouldn't share a transaction with the module's default one.

go tool gpsystem add db <module> <name> [--connector pgx|bun]

Every module already has one default connection (cfg.DB / pool), chosen for the whole project at new project --db. add db adds another, independent one to a single module: its own DB_<NAME>_* config, its own pgx pool (optionally wrapped with dbx/bunx), its own closer, and <Name>DB / <Name>Transactor fields on the module's Dependencies.

go tool gpsystem add db news analytics --connector bun

The connector is a property of the connection, not the project: a module can have a pgx-native default connection and a bun-backed analytics connection side by side, or vice versa. This is a hard boundary, not a style choice; see Transactions: a pgx-native dbx/pg executor and a dbx/bunx one cannot share a single transaction, so a connection's connector cannot change per call.

What it generates

DBAnalytics dbx.Config `envPrefix:"DB_ANALYTICS_"`

analyticsPool := pg.MustNewPool(ctx, cfg.DBAnalytics)
analyticsBun := bunx.Open(analyticsPool)   // only for --connector bun

type Dependencies struct {
    DB                  *pg.DB
    Transactor          dbx.Transactor
    AnalyticsDB         *bun.DB
    AnalyticsTransactor dbx.Transactor
    // gpsystem:dependencies
}

A closer is registered next to the pool's (analytics-pgxpool, and analytics-bun when the connector is bun, since the bun closer is registered after the pool's, so graceful shutdown's LIFO order closes the bun handle before its underlying pool). When cmd/worker/main.go already exists, the same pool/deps/closer wiring is added there too, so listeners and jobs see the connection through the same Dependencies struct.

.env.example gets a DB_ANALYTICS_* block pointing at the same local Postgres as the default connection. Repoint it to a different instance for local development. DB_ANALYTICS_USER, DB_ANALYTICS_PASSWORD and DB_ANALYTICS_NAME are required: the process fails at startup, not on the first query, if they are unset; see the configuration reference.

Binding the module repository to it

By itself, add db only makes the connection available on Dependencies; it does not touch the module's repository. Bind the module's shared repository/ skeleton to it with add surface --db (or add domain --db to bind an existing module's repository the same way):

go tool gpsystem add surface news reports --db analytics
# -> internal/modules/news/repository/analytics/doc.go

Without --db the module keeps the flat repository/ directory bound to the default connection; nothing changes for projects that never call add db.

Troubleshooting: missing anchors

add db preflights cmd/<module>/main.go for the gpsystem:pools and gpsystem:closers anchors before writing anything. If either anchor comment is missing, the command stops and prints the exact two comment lines to paste in by hand (see a freshly generated project for placement); run it again once they're in place.