testdbs

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: LGPL-3.0 Imports: 21 Imported by: 0

README

testdbs

Go Reference CI

testdbs starts SQLite, MySQL, and Postgres for your Go tests and runs each test against every one of them, through GORM. A plain go test uses an embedded SQLite; add -alldbs to run the full set in Docker containers.

Features

  • Run the same test against SQLite, MySQL 9.7, and Postgres 18
  • Keep go test fast and Docker-free; turn on the full set with one flag
  • Give each test its own database, so tests don't share tables
  • Open your own connection to MySQL or Postgres, with your own DSN or gorm.Config
  • Test against another Postgres image, such as pgvector

Add to your project

go get github.com/go-bumbu/testdbs@latest

The MySQL, Postgres, and CGo SQLite targets need Docker, and only run with -alldbs.

Start the DBs once per package
func TestMain(m *testing.M) {
	// start the DBs before the tests run
	testdbs.InitDBS()
	code := m.Run()
	// stop the containers and delete the SQLite files
	if err := testdbs.Clean(); err != nil {
		os.Exit(1)
	}
	os.Exit(code)
}
Run a test on every DB
func TestMyFunction(t *testing.T) {
	// run the same test once per DB
	for _, dbt := range testdbs.DBs() {
		t.Run(dbt.DbType(), func(t *testing.T) {
			// a *gorm.DB connected to the default database
			db := dbt.Conn()
		})
	}
}

To isolate a test, use dbt.ConnDbName(t.Name()) instead of dbt.Conn(): it creates a database with that name on first use and reuses its connection after.

Open your own connection

To test code that builds its own DSN or gorm.Config, Postgres and MySQL expose their connection parameters. SQLite does not.

func TestOpen(t *testing.T) {
	for _, dbt := range testdbs.DBs() {
		// only Postgres and MySQL expose connection parameters
		p, ok := dbt.(testdbs.ConnParamsProvider)
		if !ok {
			continue
		}
		t.Run(dbt.DbType(), func(t *testing.T) {
			// Host, Port, User, Password, DbName, and SslMode of an isolated database
			params := p.ConnParamsDbName(t.Name()) // or p.ConnParams() for the default one
			// open your own connection here, and close it when done
		})
	}
}

ConnParamsDbName(name) points at the same database as ConnDbName(name). SslMode is disable for Postgres and empty for MySQL.

Use another Postgres image

InitCustomDbs(fast, slow) replaces the default list: fast DBs always run, slow ones only with -alldbs. NewPostgres(image) runs any image that starts like the official postgres one.

func TestMain(m *testing.M) {
	// Postgres with pgvector, as the only (slow) DB
	testdbs.InitCustomDbs(nil, []testdbs.TargetDb{
		testdbs.NewPostgres("pgvector/pgvector:pg18"),
	})
	code := m.Run()
	if err := testdbs.Clean(); err != nil {
		os.Exit(1)
	}
	os.Exit(code)
}

func TestSearch(t *testing.T) {
	// a plain `go test` selects no slow DBs, so skip
	dbs := testdbs.DBs()
	if len(dbs) == 0 {
		t.Skip("set TESTDBS_ALL=1 (needs Docker) to run the Postgres tests")
	}
	// extensions are per database: create them in every database you open
	db := dbs[0].ConnDbName(t.Name())
	db.Exec("CREATE EXTENSION IF NOT EXISTS vector")
}
Run your tests
go test ./...                 # embedded SQLite only
go test ./... -alldbs         # every DB, needs Docker
TESTDBS_ALL=1 go test ./...   # same, for modules where some packages don't import testdbs
LOCAL_SQLITE=1 go test ./...  # keep the SQLite files in the working dir to inspect them

Full API: pkg.go.dev/github.com/go-bumbu/testdbs.

Development

See DEVELOPMENT.md.

Licensed under the GNU LGPL v3.

Documentation

Index

Constants

View Source
const (
	CgoSqliteSuffix = "with_CGO"
	DBTypeSqliteCgo = "SqliteWithCgo"
)
View Source
const (
	LocalSqliteEnv = "LOCAL_SQLITE"
	RunAllDBsEnv   = "TESTDBS_ALL"
)
View Source
const (
	DBTypeMysql = "mysql"
)
View Source
const (
	DBTypePostgres = "postgres"
)
View Source
const (
	DBTypeSqliteNOCgo = "SqliteNoCgo"
)

Variables

This section is empty.

Functions

func Clean

func Clean() error

Clean closes all db connections and deletes related test files

func InitCustomDbs added in v0.2.0

func InitCustomDbs(fastDbs, longDBs []TargetDb)

InitCustomDbs initializes the given DBs and makes them available through DBs(). fastDbs always run; longDBs run only when the -alldbs flag or the TESTDBS_ALL env var is set. Call it once, from TestMain.

func InitDBS

func InitDBS()

Types

type ConnParams added in v0.4.0

type ConnParams struct {
	Host     string
	Port     int
	User     string
	Password string
	DbName   string
	// SslMode is libpq's sslmode; "disable" for Postgres. Empty for MySQL,
	// which has no such setting.
	SslMode string
}

ConnParams holds what a caller needs to open its own connection to a test database, e.g. to test code that builds its own DSN or gorm.Config.

type ConnParamsProvider added in v0.4.0

type ConnParamsProvider interface {
	// ConnParams returns the parameters of the default database, the one
	// Conn() uses.
	ConnParams() ConnParams
	// ConnParamsDbName returns the parameters of the database ConnDbName(name)
	// uses, creating it if needed.
	ConnParamsDbName(name string) ConnParams
}

ConnParamsProvider is implemented by the targets that run a database server (Postgres and MySQL), not by SQLite. Type-assert a TargetDb from DBs() to get it:

if p, ok := dbt.(testdbs.ConnParamsProvider); ok {
	params := p.ConnParamsDbName(t.Name())
}

It is a separate interface so that custom TargetDb implementations passed to InitCustomDbs do not have to implement it.

type SqliteCgo added in v0.2.0

type SqliteCgo struct {
	// contains filtered or unexported fields
}

SqliteCgo is safe for concurrent use: mu guards pool, and ConnDbName holds it while creating a DB so parallel callers asking for one name share one pool.

func (*SqliteCgo) Close added in v0.2.0

func (c *SqliteCgo) Close(name string) error

func (*SqliteCgo) CloseAll added in v0.2.0

func (c *SqliteCgo) CloseAll() error

CloseAll closes every DB and, outside local mode, deletes the temp dir.

func (*SqliteCgo) Conn added in v0.2.0

func (c *SqliteCgo) Conn() *gorm.DB

func (*SqliteCgo) ConnDbName added in v0.2.0

func (c *SqliteCgo) ConnDbName(name string) *gorm.DB

func (*SqliteCgo) DbType added in v0.2.0

func (c *SqliteCgo) DbType() string

func (*SqliteCgo) Init added in v0.2.0

func (c *SqliteCgo) Init(logger logger.Interface)

type SqliteNoCgo added in v0.2.0

type SqliteNoCgo struct {
	// contains filtered or unexported fields
}

SqliteNoCgo is safe for concurrent use: mu guards pool, and ConnDbName holds it while creating a DB so parallel callers asking for one name share one pool.

func (*SqliteNoCgo) Close added in v0.2.0

func (c *SqliteNoCgo) Close(name string) error

func (*SqliteNoCgo) CloseAll added in v0.2.0

func (c *SqliteNoCgo) CloseAll() error

CloseAll closes every DB and, outside local mode, deletes the temp dir.

func (*SqliteNoCgo) Conn added in v0.2.0

func (c *SqliteNoCgo) Conn() *gorm.DB

func (*SqliteNoCgo) ConnDbName added in v0.2.0

func (c *SqliteNoCgo) ConnDbName(name string) *gorm.DB

func (*SqliteNoCgo) DbType added in v0.2.0

func (c *SqliteNoCgo) DbType() string

func (*SqliteNoCgo) Init added in v0.2.0

func (c *SqliteNoCgo) Init(logger logger.Interface)

type TargetDb added in v0.2.0

type TargetDb interface {
	DbType() string
	Init(logger logger.Interface)
	Conn() *gorm.DB
	ConnDbName(name string) *gorm.DB
	Close(name string) error
	CloseAll() error
}

func DBs added in v0.2.0

func DBs() []TargetDb

DBs returns the DBs selected by InitDBS or InitCustomDbs. The list is empty when only slow DBs were registered and neither -alldbs nor TESTDBS_ALL is set, so tests should skip in that case. DBs panics if no init function ran.

func NewPostgres added in v0.3.0

func NewPostgres(image string) TargetDb

NewPostgres returns a Postgres target that runs image instead of the default postgres:18, e.g. "pgvector/pgvector:pg18" for the vector extension. An empty image keeps the default. The image must start like the official postgres image: same env vars, and "database system is ready to accept connections" logged twice (initdb's temporary server, then the real one).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL