dbinitiator

package module
v0.3.10 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2026 License: MIT Imports: 28 Imported by: 3

README

DB Initiator

A Go library for database testing and migrations. Spin up ephemeral containerized databases for integration tests or run migrations against existing databases.

Features

  • Ephemeral test databases – Start Docker containers for isolated integration testing
  • Database migrations – Run schema and data migrations using golang-migrate

Supported Databases

Database Container Migrations
PostgreSQL ✓ ✓*
Spanner ✓ (emulator) ✓
*PostgreSQL Limitations

Compared to the Spanner implementation, PostgreSQL currently has the following limitations:

  • No separate schema vs data migrations (single MigrateUp only)
  • No configurable migrations table name
  • PostgresMigrator only supports MigrateUp (no down/drop migrations)

License

See LICENSE for details.

Documentation

Overview

Implements tooling to setup a Spanner database configured for running integration tests against.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewSpannerInstance 

func NewSpannerInstance(ctx context.Context, projectID, instanceID string, opts ...option.ClientOption) error

NewSpannerInstance creates a spanner instance. This is intended for use with a spanner emulator.

func PostgresConnStr added in v0.1.2 

func PostgresConnStr(username, password, host, port, database string, sslMode SSLMode) string

PostgresConnStr builds a postgres connection URL. sslMode sets the sslmode query parameter. Pass an empty string to use the default, which is SSLModeRequire.

Types

type Migrator added in v0.3.0 

type Migrator interface {
	// MigrateUpSchema applies all up migrations for the database schema.
	MigrateUpSchema(ctx context.Context, sourceURL string) error

	// MigrateUpData applies all up migrations for the database data.
	MigrateUpData(ctx context.Context, sourceURL string) error

	// MigrateDropSchema drops the database schema.
	MigrateDropSchema(ctx context.Context) error
}

Migrator is an interface for database migration.

type PostgresContainer added in v0.1.2 

type PostgresContainer struct {
	testcontainers.Container
	// contains filtered or unexported fields
}

PostgresContainer represents a docker container running a postgres instance.

func NewPostgresContainer added in v0.1.2 

func NewPostgresContainer(ctx context.Context, imageVersion string) (*PostgresContainer, error)

NewPostgresContainer returns a new PostgresContainer ready to use with postgres.

func (*PostgresContainer) Close added in v0.1.2 

func (pc *PostgresContainer) Close()

Close closes all connections to the postgres instance

func (*PostgresContainer) CreateDatabase added in v0.1.2 

func (pc *PostgresContainer) CreateDatabase(ctx context.Context, dbName string) (*PostgresDatabase, error)

CreateDatabase creates a new database with the given name and returns a connection to it.

type PostgresDatabase added in v0.1.2 

type PostgresDatabase struct {
	*pgxpool.Pool
	// contains filtered or unexported fields
}

PostgresDatabase represents a postgres database created and ready for migrations

func NewPostgresDatabase added in v0.1.2 

func NewPostgresDatabase(ctx context.Context, username, password, host, port, databaseToCreate, schemaToCreate string, sslMode SSLMode) (*PostgresDatabase, error)

NewPostgresDatabase creates a new database and schema, then connects to it.

func (*PostgresDatabase) Close added in v0.1.2 

func (db *PostgresDatabase) Close()

Close closes the database connection

func (*PostgresDatabase) MigrateDown added in v0.1.2 

func (db *PostgresDatabase) MigrateDown(sourceURL string) error

MigrateDown will migrate all the way down

func (*PostgresDatabase) MigrateUp added in v0.1.2 

func (db *PostgresDatabase) MigrateUp(sourceURL ...string) error

MigrateUp will migrate all the way up, applying all up migrations from all sourceURL's

func (*PostgresDatabase) Schema added in v0.1.2 

func (db *PostgresDatabase) Schema() string

Schema returns the default schema

type PostgresMigrator added in v0.3.0 

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

func NewPostgresMigrator added in v0.3.0 

func NewPostgresMigrator(username, password, host, port, database string, sslMode SSLMode) *PostgresMigrator

NewPostgresMigrator returns a new PostgresMigrator. It does not attempt to create the database or schema.

sslMode sets the sslmode query parameter. Pass an empty string to use the default, which is SSLModeRequire. Use SSLModeDisable only for local test containers.

func (*PostgresMigrator) MigrateDropSchema added in v0.3.0 

func (p *PostgresMigrator) MigrateDropSchema(_ context.Context) error

FIXME(zredinger): implement this method

func (*PostgresMigrator) MigrateUpData added in v0.3.0 

func (p *PostgresMigrator) MigrateUpData(_ context.Context, sourceURL string) error

FIXME(zredinger): implement this method

func (*PostgresMigrator) MigrateUpSchema added in v0.3.0 

func (p *PostgresMigrator) MigrateUpSchema(_ context.Context, sourceURL string) error

MigrateUp will migrate all the way up, applying all up migrations from the sourceURL

Example 
ctx := context.Background()
container, err := NewPostgresContainer(ctx, "latest")
if err != nil {
	panic(err)
}
defer container.Close()

db, err := container.CreateDatabase(ctx, "test_db")
if err != nil {
	panic(err)
}
defer db.Close()

migrator := NewPostgresMigrator(container.superUsername, "password", container.host, container.port.Port(), db.dbName, SSLModeDisable)

if err := migrator.MigrateUpSchema(ctx, "file://testdata/postgres/migrations"); err != nil {
	panic(err)
}

type SSLMode added in v0.3.9 

type SSLMode string

SSLMode represents the sslmode parameter for PostgreSQL connections. 

const (
	// SSLModeDisable disables SSL entirely. Use only for local test containers.
	SSLModeDisable SSLMode = "disable"
	// SSLModeAllow prefers non-SSL but will use SSL if the server requires it.
	SSLModeAllow SSLMode = "allow"
	// SSLModePrefer prefers SSL but will use non-SSL if the server does not support it.
	SSLModePrefer SSLMode = "prefer"
	// SSLModeRequire requires SSL but does not verify the server certificate.
	SSLModeRequire SSLMode = "require"
	// SSLModeVerifyCA requires SSL and verifies the server certificate is signed by a trusted CA.
	SSLModeVerifyCA SSLMode = "verify-ca"
	// SSLModeVerifyFull requires SSL, verifies the CA, and verifies the server hostname matches the certificate.
	SSLModeVerifyFull SSLMode = "verify-full"
)

type SpannerContainer 

type SpannerContainer struct {
	testcontainers.Container
	// contains filtered or unexported fields
}

SpannerContainer represents a docker container running a spanner instance. SpannerContainer.Close should be called to cleanup resources.

func NewSpannerContainer 

func NewSpannerContainer(ctx context.Context, imageVersion string) (*SpannerContainer, error)

NewSpannerContainer returns a initialized SpannerContainer ready to run to create databases for unit tests. SpannerContainer.Close should be called to cleanup resources.

func (*SpannerContainer) Close 

func (sc *SpannerContainer) Close() error

Close cleans up open resources

func (*SpannerContainer) CreateDatabase added in v0.2.0 

func (sc *SpannerContainer) CreateDatabase(ctx context.Context, dbName string) (*SpannerDB, error)

CreateDatabase creates a database with dbName. Each test should create their own database for testing

Example 
ctx := context.Background()
container, err := NewSpannerContainer(ctx, "latest")
if err != nil {
	panic(err)
}
defer func() {
	closeErr := container.Close()
	log.Println("Error closing container:", closeErr)
}()

db, err := container.CreateDatabase(ctx, "test_db")
if err != nil {
	panic(err)
}
defer func() {
	closeErr := db.Close()
	log.Println("Error closing database:", closeErr)
}()

// Use the database..
db.Single().Query(ctx, spanner.NewStatement("SELECT 1"))

type SpannerDB 

type SpannerDB struct {
	*spanner.Client
	// contains filtered or unexported fields
}

SpannerDB represents a database created and ready for migrations

func NewSpannerDatabase 

func NewSpannerDatabase(ctx context.Context, projectID, instanceID, dbName string, opts ...option.ClientOption) (*SpannerDB, error)

NewSpannerDatabase will create a spanner database

func (*SpannerDB) Close 

func (db *SpannerDB) Close() error

Close cleans up open resources

func (*SpannerDB) DropDatabase 

func (db *SpannerDB) DropDatabase(ctx context.Context) error

func (*SpannerDB) MigrateDown 

func (db *SpannerDB) MigrateDown(sourceURL string) error

MigrateDown will migrate all the way down

func (*SpannerDB) MigrateUp 

func (db *SpannerDB) MigrateUp(sourceURL ...string) error

MigrateUp will migrate all the way up, applying all up migrations from all sourceURL's

type SpannerMigrator added in v0.3.0 

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

SpannerMigrator handles connecting to an existing spanner database and running migrations

func NewSpannerMigrator added in v0.3.0 

func NewSpannerMigrator(ctx context.Context, projectID, instanceID, dbName string, opts ...option.ClientOption) (*SpannerMigrator, error)

NewSpannerMigrator connects to an existing spanner database and returns a SpannerMigrator

Uses the following tables by default to store migration versions:

  • Data Migrations table: "DataMigrations"
  • Schema Migrations table: "SchemaMigrations"

func (*SpannerMigrator) Close added in v0.3.0 

func (s *SpannerMigrator) Close() error

Close cleans up resources

func (*SpannerMigrator) MigrateDropSchema added in v0.3.0 

func (s *SpannerMigrator) MigrateDropSchema(ctx context.Context) error

MigrateDropSchema drops all objects in the schema

This happens in the following order:

  1. Drop views
  2. Drop FK constraints
  3. Drop Search Indexes
  4. Drop Indexes
  5. Drop tables

func (*SpannerMigrator) MigrateUpData added in v0.3.0 

func (s *SpannerMigrator) MigrateUpData(ctx context.Context, sourceURL string) error

MigrateUpData will apply all data migrations from the sourceURL

Use for DML migrations

Example 
ctx := context.Background()
container, err := NewSpannerContainer(ctx, "latest")
if err != nil {
	panic(err)
}
defer func() {
	closeErr := container.Close()
	log.Println("Error closing container:", closeErr)
}()

db, err := container.CreateDatabase(ctx, "test_db")
if err != nil {
	panic(err)
}
defer func() {
	closeErr := db.Close()
	log.Println("Error closing database:", closeErr)
}()

migrator, err := NewSpannerMigrator(ctx, container.projectID, container.instanceID, "test_db", container.opts...)
if err != nil {
	panic(err)
}

if err := migrator.MigrateUpData(ctx, "file://testdata/spanner/migrations"); err != nil {
	panic(err)
}

func (*SpannerMigrator) MigrateUpSchema added in v0.3.0 

func (s *SpannerMigrator) MigrateUpSchema(ctx context.Context, sourceURL string) error

MigrateUpSchema will migrate all the way up, applying all up migrations from the sourceURL

Use for DDL migrations

Example 
ctx := context.Background()
container, err := NewSpannerContainer(ctx, "latest")
if err != nil {
	panic(err)
}
defer func() {
	closeErr := container.Close()
	log.Println("Error closing container:", closeErr)
}()

db, err := container.CreateDatabase(ctx, "test_db")
if err != nil {
	panic(err)
}
defer func() {
	closeErr := db.Close()
	log.Println("Error closing database:", closeErr)
}()

migrator, err := NewSpannerMigrator(ctx, container.projectID, container.instanceID, "test_db", container.opts...)
if err != nil {
	panic(err)
}

if err := migrator.MigrateUpSchema(ctx, "file://testdata/spanner/migrations"); err != nil {
	panic(err)
}

func (*SpannerMigrator) WithDataMigrationsTable added in v0.3.0 

func (s *SpannerMigrator) WithDataMigrationsTable(table string) *SpannerMigrator

WithDataMigrationsTable allows setting the data migration table to be used

func (*SpannerMigrator) WithSchemaMigrationsTable added in v0.3.0 

func (s *SpannerMigrator) WithSchemaMigrationsTable(table string) *SpannerMigrator

WithSchemaMigrationsTable allows setting the schema migration table to be used

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.