bun

Since the standard math/big package does not implement database/sql scan/value methods, it cannot be used directly with Bun. bunbig provides a wrapper around math/big that allows you to use big.Int and big.Float types within your Bun models and database operations (including PostgreSQL).

type TableWithBigint struct {
	ID      uint64
	Name    string
	Deposit *bunbig.Int
	Residue *bunbig.Float
}

To use Bun in your Go project, install it using go get:

go get github.com/uptrace/bun

To log SQL queries executed by Bun using slog, create a new QueryHook using bunslog.NewQueryHook and register it with your *bun.DB instance using AddQueryHook. You can pass several options to control log levels for general queries, slow queries, and error queries.

import (
	"github.com/uptrace/bun"
	"github.com/uptrace/bun/extra/bunslog"
	"log/slog"
	"time"
)

// ... setup sqldb and dialect ...

db := bun.NewDB(sqldb, dialect)

hook := bunslog.NewQueryHook(
	bunslog.WithQueryLogLevel(slog.LevelDebug),
	bunslog.WithSlowQueryLogLevel(slog.LevelWarn),
	bunslog.WithErrorQueryLogLevel(slog.LevelError),
	bunslog.WithSlowQueryThreshold(3 * time.Second),
)

db.AddQueryHook(hook)

To use pgdriver as your PostgreSQL driver for database/sql, install it using go get:

go get github.com/uptrace/bun/driver/pgdriver

To run the demonstration of PostgreSQL's LISTEN/NOTIFY capabilities using Bun, navigate to the example directory and execute the following command:

go run .

Generate new migration files. You can choose between Go-based migrations or raw SQL migrations.

• Go migrations: Use create_go followed by the migration name.
• SQL migrations: Use create_sql followed by the migration name.

Use the github.com/uptrace/bun/migrate package to version your database schema. You register migration functions (Up and Down) and use a Migrator to execute them.

import "github.com/uptrace/bun/migrate"

migrations := migrate.NewMigrations()

migrations.MustRegister(func(ctx context.Context, db *bun.DB) error {
    _, err := db.NewCreateTable().Model((*User)(nil)).Exec(ctx)
    return err
}, func(ctx context.Context, db *bun.DB) error {
    _, err := db.NewDropTable().Model((*User)(nil)).Exec(ctx)
    return err
})

migrator := migrate.NewMigrator(db, migrations)
err := migrator.Init(ctx)
err = migrator.Up(ctx)

To execute the model hooks demonstration, navigate to the example directory and run the following command:

go run .

View the current status of your migrations to see which have been applied or are pending using the status command.

go run . db status

To execute the basic example provided in the repository, use the standard Go run command from within the example directory.

go run .

To execute the demonstration of a polymorphic has-many relationship in Bun, run the following command from the example directory:

go run main.go