Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Configs ¶
type Configs struct {
// DSN takes priority over individual fields when non-empty.
// Format: "postgres://user:pass@host:port/db?sslmode=disable"
DSN string `config:",omitempty"`
// Individual connection fields — used when DSN is empty.
Host string `config:",omitempty"` // default "localhost"
Port int `config:",omitempty"` // default 5432
User string `config:",omitempty"`
Password string `config:",omitempty"`
Database string `config:",omitempty"`
SSLMode string `config:",omitempty"` // default "disable"
// Connection pool settings.
MaxOpenConns int `config:",omitempty"` // default 25
MaxIdleConns int `config:",omitempty"` // default 5
ConnMaxLifetime time.Duration `config:",omitempty"` // default 1h
ConnMaxIdleTime time.Duration `config:",omitempty"` // default 30m
// QueryHooks are registered on the bun.DB instance.
// Use them to add query logging, tracing, or metrics.
// Must be set in code — function types are not loadable from file.
QueryHooks []bun.QueryHook `config:"-"`
}
Configs holds configuration for a bun DB connection (PostgreSQL via pgdriver).
Compatible with rockconfig.InitFromFile. If DSN is set it takes priority; otherwise the connection string is built from the individual Host/Port/User/Password/Database/SSLMode fields.
Example config.yaml:
dsn: "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
— or individual fields —
host: "localhost" port: 5432 user: "myuser" password: "secret" database: "mydb" ssl_mode: "disable" max_open_conns: 25 max_idle_conns: 5 conn_max_lifetime: "1h" conn_max_idle_time: "30m"
type Service ¶
type Service interface {
// Init opens the connection pool and verifies connectivity via Ping.
Init(ctx context.Context) error
// Stop closes the connection pool.
Stop() error
// DB returns the underlying *bun.DB for building queries.
// Must not be called before Init.
DB() *bun.DB
// Ping verifies the database connection is alive.
Ping(ctx context.Context) error
// RunInTx runs fn inside a database transaction.
// The transaction is committed if fn returns nil, rolled back otherwise.
// Pass nil opts to use the database default isolation level.
RunInTx(ctx context.Context, opts *sql.TxOptions, fn func(ctx context.Context, tx bun.Tx) error) error
}
Service wraps a bun.DB and provides lifecycle management.
Call order: Init → use → Stop.
Use DB() to access the full bun query builder for selects, inserts, updates, deletes, and schema migrations. Use RunInTx for transactional work.
func NewService ¶
NewService creates a Service that is ready to be initialised. No connection is opened — call Init to establish the connection pool.
Example ¶
package main
import (
"context"
"database/sql"
"log"
"github.com/arzab/gorock-catalog/rockbun"
"github.com/uptrace/bun"
)
func main() {
svc := rockbun.NewService(rockbun.Configs{
Host: "localhost", User: "app", Password: "p@ss:w/rd", Database: "app", SSLMode: "verify-full",
})
ctx := context.Background()
if err := svc.Init(ctx); err != nil { // opens the pool and pings
log.Fatal(err)
}
defer func() { _ = svc.Stop() }()
var n int
if err := svc.DB().NewSelect().ColumnExpr("1").Scan(ctx, &n); err != nil {
log.Fatal(err)
}
err := svc.RunInTx(ctx, &sql.TxOptions{}, func(ctx context.Context, tx bun.Tx) error {
_, err := tx.NewRaw("SELECT 1").Exec(ctx)
return err
})
if err != nil {
log.Fatal(err)
}
}
Output: