dbcontainers

package module
v0.0.0-...-e33ba19 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2025 License: Apache-2.0 Imports: 27 Imported by: 0

README

dbcontainers

A robust, flexible Go library for running database containers in tests. Supports PostgreSQL, MySQL, MariaDB, and ClickHouse.

Features

  • Simple, fluent API for container configuration
  • Supports multiple database types:
    • PostgreSQL
    • MySQL
    • MariaDB
    • ClickHouse
  • Robust container orchestration with health checks and retry logic
  • VM-aware networking for Docker Machine environments
  • Support for initialization scripts (SQL files and embedded FS)
  • Detailed logging and error reporting

Installation

go get -u github.com/panta/dbcontainers

Quick Start

package main

import (
    "context"
    "database/sql"
    "testing"
    
    "github.com/panta/dbcontainers"
)

func TestWithPostgres(t *testing.T) {
    ctx := context.Background()
    
    // Create and start a Postgres container
    container, err := dbcontainers.NewPostgresBuiler(nil).
        WithVersion("15-bullseye").
        WithDatabase("testdb").
        WithCredentials("testuser", "testpass").
        WithInitScript(`
            CREATE TABLE users (
                id SERIAL PRIMARY KEY,
                name TEXT
            );
        `).
        Build(ctx)
    
    if err != nil {
        t.Fatal(err)
    }
    defer container.Stop(ctx)
    
    // Use the container
    db, err := sql.Open("postgres", container.ConnectionString())
    if err != nil {
        t.Fatal(err)
    }
    defer db.Close()
    
    // Run your tests...
}

Database Adapters

PostgreSQL
container, err := dbcontainers.NewPostgresBuiler(nil).
    WithVersion("15-bullseye").
    WithDatabase("mydb").
    WithCredentials("user", "pass").
    Build(ctx)
MySQL
container, err := dbcontainers.NewMySQLBuilder(nil).
    WithVersion("8").
    WithDatabase("mydb").
    WithCredentials("user", "pass").
    Build(ctx)
MariaDB
container, err := dbcontainers.NewMariaDBBuiler(nil).
    WithVersion("10.11").
    WithDatabase("mydb").
    WithCredentials("user", "pass").
    Build(ctx)
ClickHouse
container, err := dbcontainers.NewClickHouseBuilder(nil).
    WithVersion("23.8").
    WithDatabase("mydb").
    WithCredentials("user", "pass").
    Build(ctx)

Advanced Usage

Initialization Scripts
// From string
builder.WithInitScript("CREATE TABLE users (id SERIAL PRIMARY KEY);")

// From file
builder.WithInitScriptFile("testdata/schema.sql")

// From multiple files
builder.WithInitScriptFiles([]string{
    "testdata/schema.sql",
    "testdata/seed.sql",
})

// From embedded FS
//go:embed testdata/init/*.sql
var initFS embed.FS

builder.WithInitScriptFS(initFS, "testdata/init/*.sql")
VM-Aware Networking

The library automatically handles Docker networking in VM environments.

The docker host is determined automatically, but in case you need to override or force it:

builder.WithDockerHost("192.168.99.100") // For Docker Machine
Custom Retry Policy
builder.WithRetryPolicy(
    5,                  // attempts
    time.Second,        // delay
    time.Minute,        // timeout
)
Debug Logging

You can optionally pass a slog handler to the builders:

logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))

container, err := dbcontainers.NewPostgresBuiler(logger).
    WithDebug(true).
    Build(ctx)
Container Interface

All database containers implement this interface:

type Container interface {
    Start(ctx context.Context) error
    Stop(ctx context.Context) error
    ConnectionString() string
    Logs(ctx context.Context) ([]byte, error)
    RunSQL(ctx context.Context, script string) error
}

Integration

dbcontainers works seamlessly with other testing libraries. See the INTEGRATION.md document for more information.

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details.

Acknowledgments

Documentation

Overview

Package dbcontainers is the main access point for the library functionality.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClickHouseBuilder 

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

ClickHouseBuilder implements a fluent interface for configuring ClickHouse containers

func NewClickHouseBuilder 

func NewClickHouseBuilder(logger *slog.Logger) *ClickHouseBuilder

NewClickHouseBuilder creates a new ClickHouse container builder

func (*ClickHouseBuilder) Build 

func (b *ClickHouseBuilder) Build(ctx context.Context) (Container, error)

Build creates and returns a new ClickHouse container

func (*ClickHouseBuilder) WithBindMount 

func (b *ClickHouseBuilder) WithBindMount(enable bool) *ClickHouseBuilder

WithBindMount controls whether to use bind mounting for init scripts

func (*ClickHouseBuilder) WithCredentials 

func (b *ClickHouseBuilder) WithCredentials(username, password string) *ClickHouseBuilder

WithCredentials sets the database credentials

func (*ClickHouseBuilder) WithDatabase 

func (b *ClickHouseBuilder) WithDatabase(name string) *ClickHouseBuilder

WithDatabase sets the database name

func (*ClickHouseBuilder) WithDebug 

func (b *ClickHouseBuilder) WithDebug(debug bool) *ClickHouseBuilder

WithDebug enables debug logging

func (*ClickHouseBuilder) WithDockerHost 

func (b *ClickHouseBuilder) WithDockerHost(dockerHost string) *ClickHouseBuilder

WithDockerHost sets the docker machine IP/hostname

func (*ClickHouseBuilder) WithInitScript 

func (b *ClickHouseBuilder) WithInitScript(script string) *ClickHouseBuilder

WithInitScript adds a single initialization script

func (*ClickHouseBuilder) WithInitScriptFS 

func (b *ClickHouseBuilder) WithInitScriptFS(fsys fs.FS, patterns ...string) *ClickHouseBuilder

WithInitScriptFS adds initialization scripts from an fs.FS using glob patterns

func (*ClickHouseBuilder) WithInitScriptFile 

func (b *ClickHouseBuilder) WithInitScriptFile(filename string) *ClickHouseBuilder

WithInitScriptFile adds initialization scripts from a file

func (*ClickHouseBuilder) WithInitScriptFiles 

func (b *ClickHouseBuilder) WithInitScriptFiles(filenames []string) *ClickHouseBuilder

WithInitScriptFiles adds initialization scripts from multiple files

func (*ClickHouseBuilder) WithPort 

func (b *ClickHouseBuilder) WithPort(port int) *ClickHouseBuilder

WithPort sets the container port

func (*ClickHouseBuilder) WithRetryPolicy 

func (b *ClickHouseBuilder) WithRetryPolicy(attempts int, delay time.Duration, timeout time.Duration) *ClickHouseBuilder

WithRetryPolicy sets the retry policy for container operations

func (*ClickHouseBuilder) WithTmpBase 

func (b *ClickHouseBuilder) WithTmpBase(tmpBase string) *ClickHouseBuilder

WithTmpBase sets the temporary directory base path

func (*ClickHouseBuilder) WithVersion 

func (b *ClickHouseBuilder) WithVersion(version string) *ClickHouseBuilder

WithVersion sets the ClickHouse version

type ClickHouseContainer 

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

ClickHouseContainer implements the Container interface for ClickHouse

func NewClickHouse 

func NewClickHouse(logger *slog.Logger, config *Config) (*ClickHouseContainer, error)

NewClickHouse creates a new ClickHouse container instance

func (*ClickHouseContainer) ConnectionString 

func (c *ClickHouseContainer) ConnectionString() string

func (*ClickHouseContainer) Logs 

func (c *ClickHouseContainer) Logs(ctx context.Context) ([]byte, error)

func (*ClickHouseContainer) RunSQL 

func (c *ClickHouseContainer) RunSQL(ctx context.Context, script string) error

func (*ClickHouseContainer) Start 

func (c *ClickHouseContainer) Start(ctx context.Context) error

func (*ClickHouseContainer) Stop 

func (c *ClickHouseContainer) Stop(ctx context.Context) error

type Config 

type Config struct {
	Image         string
	Port          int
	Database      string
	Username      string
	Password      string
	InitScripts   []string
	Retry         *RetryConfig
	DockerHost    string
	SkipBindMount bool
	TmpBase       string
	Debug         bool
}

Config holds common container configuration

type Container 

type Container interface {
	// Start initializes and runs the container
	Start(ctx context.Context) error

	// Stop terminates the container
	Stop(ctx context.Context) error

	// ConnectionString returns the database connection string
	ConnectionString() string

	// Logs returns container logs for debugging
	Logs(ctx context.Context) ([]byte, error)

	// RunSQL executes SQL scripts against the database
	RunSQL(ctx context.Context, script string) error
}

Container defines the interface for database containers

type MariaDBBuilder 

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

MariaDBBuilder implements a fluent interface for configuring MariaDB containers

func NewMariaDBBuiler 

func NewMariaDBBuiler(logger *slog.Logger) *MariaDBBuilder

NewMariaDBBuiler creates a new MariaDB container builder

func (*MariaDBBuilder) Build 

func (b *MariaDBBuilder) Build(ctx context.Context) (Container, error)

Build creates and returns a new MariaDB container

func (*MariaDBBuilder) WithBindMound 

func (b *MariaDBBuilder) WithBindMound(enable bool) *MariaDBBuilder

func (*MariaDBBuilder) WithCredentials 

func (b *MariaDBBuilder) WithCredentials(username, password string) *MariaDBBuilder

WithCredentials sets the database credentials

func (*MariaDBBuilder) WithDatabase 

func (b *MariaDBBuilder) WithDatabase(name string) *MariaDBBuilder

WithDatabase sets the database name

func (*MariaDBBuilder) WithDebug 

func (b *MariaDBBuilder) WithDebug(debug bool) *MariaDBBuilder

WithDebug enables debug logging

func (*MariaDBBuilder) WithDockerHost 

func (b *MariaDBBuilder) WithDockerHost(dockerHost string) *MariaDBBuilder

WithDockerHost sets the docker machine IP/hostname.

func (*MariaDBBuilder) WithInitScript 

func (b *MariaDBBuilder) WithInitScript(script string) *MariaDBBuilder

WithInitScript adds a single initialization script

func (*MariaDBBuilder) WithInitScriptFS 

func (b *MariaDBBuilder) WithInitScriptFS(fsys fs.FS, patterns ...string) *MariaDBBuilder

WithInitScriptFS adds initialization scripts from an fs.FS using glob patterns

func (*MariaDBBuilder) WithInitScriptFile 

func (b *MariaDBBuilder) WithInitScriptFile(filename string) *MariaDBBuilder

WithInitScriptFile adds initialization scripts from a file

func (*MariaDBBuilder) WithInitScriptFiles 

func (b *MariaDBBuilder) WithInitScriptFiles(filenames []string) *MariaDBBuilder

WithInitScriptFiles adds initialization scripts from multiple files

func (*MariaDBBuilder) WithPort 

func (b *MariaDBBuilder) WithPort(port int) *MariaDBBuilder

WithPort sets the container port

func (*MariaDBBuilder) WithRetryPolicy 

func (b *MariaDBBuilder) WithRetryPolicy(attempts int, delay time.Duration, timeout time.Duration) *MariaDBBuilder

WithRetryPolicy sets the retry policy for container operations

func (*MariaDBBuilder) WithTmpBase 

func (b *MariaDBBuilder) WithTmpBase(tmpBase string) *MariaDBBuilder

func (*MariaDBBuilder) WithVersion 

func (b *MariaDBBuilder) WithVersion(version string) *MariaDBBuilder

WithVersion sets the MariaDB version

type MariaDBContainer 

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

MariaDBContainer implements the Container interface for MariaDB

func NewMariaDB 

func NewMariaDB(logger *slog.Logger, config *Config) (*MariaDBContainer, error)

NewMariaDB creates a new MariaDB container instance

func (*MariaDBContainer) ConnectionString 

func (m *MariaDBContainer) ConnectionString() string

func (*MariaDBContainer) Logs 

func (m *MariaDBContainer) Logs(ctx context.Context) ([]byte, error)

func (*MariaDBContainer) RunSQL 

func (m *MariaDBContainer) RunSQL(ctx context.Context, script string) error

func (*MariaDBContainer) Start 

func (m *MariaDBContainer) Start(ctx context.Context) error

func (*MariaDBContainer) Stop 

func (m *MariaDBContainer) Stop(ctx context.Context) error

type MySQLBuilder 

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

MySQLBuilder implements a fluent interface for configuring MySQL containers

func NewMySQLBuilder 

func NewMySQLBuilder(logger *slog.Logger) *MySQLBuilder

NewMySQLBuilder creates a new MySQL container builder

func (*MySQLBuilder) Build 

func (b *MySQLBuilder) Build(ctx context.Context) (Container, error)

Build creates and returns a new MySQL container

func (*MySQLBuilder) WithBindMound 

func (b *MySQLBuilder) WithBindMound(enable bool) *MySQLBuilder

func (*MySQLBuilder) WithCredentials 

func (b *MySQLBuilder) WithCredentials(username, password string) *MySQLBuilder

WithCredentials sets the database credentials

func (*MySQLBuilder) WithDatabase 

func (b *MySQLBuilder) WithDatabase(name string) *MySQLBuilder

WithDatabase sets the database name

func (*MySQLBuilder) WithDebug 

func (b *MySQLBuilder) WithDebug(debug bool) *MySQLBuilder

WithDebug enables debug logging

func (*MySQLBuilder) WithDockerHost 

func (b *MySQLBuilder) WithDockerHost(dockerHost string) *MySQLBuilder

WithDockerHost sets the docker machine IP/hostname.

func (*MySQLBuilder) WithInitScript 

func (b *MySQLBuilder) WithInitScript(script string) *MySQLBuilder

WithInitScript adds a single initialization script

func (*MySQLBuilder) WithInitScriptFS 

func (b *MySQLBuilder) WithInitScriptFS(fsys fs.FS, patterns ...string) *MySQLBuilder

WithInitScriptFS adds initialization scripts from an fs.FS using glob patterns

func (*MySQLBuilder) WithInitScriptFile 

func (b *MySQLBuilder) WithInitScriptFile(filename string) *MySQLBuilder

WithInitScriptFile adds initialization scripts from a file

func (*MySQLBuilder) WithInitScriptFiles 

func (b *MySQLBuilder) WithInitScriptFiles(filenames []string) *MySQLBuilder

WithInitScriptFiles adds initialization scripts from multiple files

func (*MySQLBuilder) WithPort 

func (b *MySQLBuilder) WithPort(port int) *MySQLBuilder

WithPort sets the container port

func (*MySQLBuilder) WithRetryPolicy 

func (b *MySQLBuilder) WithRetryPolicy(attempts int, delay time.Duration, timeout time.Duration) *MySQLBuilder

WithRetryPolicy sets the retry policy for container operations

func (*MySQLBuilder) WithTmpBase 

func (b *MySQLBuilder) WithTmpBase(tmpBase string) *MySQLBuilder

func (*MySQLBuilder) WithVersion 

func (b *MySQLBuilder) WithVersion(version string) *MySQLBuilder

WithVersion sets the MySQL version

type MySQLContainer 

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

MySQLContainer implements the Container interface for MySQL

func NewMySQL 

func NewMySQL(logger *slog.Logger, config *Config) (*MySQLContainer, error)

NewMySQL creates a new MySQL container instance

func (*MySQLContainer) ConnectionString 

func (m *MySQLContainer) ConnectionString() string

func (*MySQLContainer) Logs 

func (m *MySQLContainer) Logs(ctx context.Context) ([]byte, error)

func (*MySQLContainer) RunSQL 

func (m *MySQLContainer) RunSQL(ctx context.Context, script string) error

func (*MySQLContainer) Start 

func (m *MySQLContainer) Start(ctx context.Context) error

func (*MySQLContainer) Stop 

func (m *MySQLContainer) Stop(ctx context.Context) error

type PostgresBuilder 

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

PostgresBuilder implements a fluent interface for configuring PostgreSQL containers

func NewPostgresBuiler 

func NewPostgresBuiler(logger *slog.Logger) *PostgresBuilder

NewPostgresBuiler creates a new PostgreSQL container builder

func (*PostgresBuilder) Build 

func (b *PostgresBuilder) Build(ctx context.Context) (Container, error)

Build creates and returns a new PostgreSQL container

func (*PostgresBuilder) WithBindMound 

func (b *PostgresBuilder) WithBindMound(enable bool) *PostgresBuilder

func (*PostgresBuilder) WithCredentials 

func (b *PostgresBuilder) WithCredentials(username, password string) *PostgresBuilder

WithCredentials sets the database credentials

func (*PostgresBuilder) WithDatabase 

func (b *PostgresBuilder) WithDatabase(name string) *PostgresBuilder

WithDatabase sets the database name

func (*PostgresBuilder) WithDebug 

func (b *PostgresBuilder) WithDebug(debug bool) *PostgresBuilder

WithDebug enables debug logging

func (*PostgresBuilder) WithDockerHost 

func (b *PostgresBuilder) WithDockerHost(dockerHost string) *PostgresBuilder

WithDockerHost sets the docker machine IP/hostname.

func (*PostgresBuilder) WithInitScript 

func (b *PostgresBuilder) WithInitScript(script string) *PostgresBuilder

WithInitScript adds a single initialization script

func (*PostgresBuilder) WithInitScriptFS 

func (b *PostgresBuilder) WithInitScriptFS(fsys fs.FS, patterns ...string) *PostgresBuilder

WithInitScriptFS adds initialization scripts from an fs.FS using glob patterns

func (*PostgresBuilder) WithInitScriptFile 

func (b *PostgresBuilder) WithInitScriptFile(filename string) *PostgresBuilder

WithInitScriptFile adds initialization scripts from a file

func (*PostgresBuilder) WithInitScriptFiles 

func (b *PostgresBuilder) WithInitScriptFiles(filenames []string) *PostgresBuilder

WithInitScriptFiles adds initialization scripts from multiple files

func (*PostgresBuilder) WithPort 

func (b *PostgresBuilder) WithPort(port int) *PostgresBuilder

WithPort sets the container port

func (*PostgresBuilder) WithRetryPolicy 

func (b *PostgresBuilder) WithRetryPolicy(attempts int, delay time.Duration, timeout time.Duration) *PostgresBuilder

WithRetryPolicy sets the retry policy for container operations

func (*PostgresBuilder) WithTmpBase 

func (b *PostgresBuilder) WithTmpBase(tmpBase string) *PostgresBuilder

func (*PostgresBuilder) WithVersion 

func (b *PostgresBuilder) WithVersion(version string) *PostgresBuilder

WithVersion sets the PostgreSQL version

type PostgresContainer 

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

PostgresContainer implements the Container interface for PostgreSQL

func NewPostgres 

func NewPostgres(logger *slog.Logger, config *Config) (*PostgresContainer, error)

NewPostgres creates a new PostgreSQL container instance

func (*PostgresContainer) ConnectionString 

func (p *PostgresContainer) ConnectionString() string

ConnectionString returns the database connection string

func (*PostgresContainer) Logs 

func (p *PostgresContainer) Logs(ctx context.Context) ([]byte, error)

Logs returns container logs

func (*PostgresContainer) RunSQL 

func (p *PostgresContainer) RunSQL(ctx context.Context, script string) error

RunSQL executes SQL scripts against the database

func (*PostgresContainer) Start 

func (p *PostgresContainer) Start(ctx context.Context) error

Start initializes and runs the container

func (*PostgresContainer) Stop 

func (p *PostgresContainer) Stop(ctx context.Context) error

Stop terminates the container

type RetryConfig 

type RetryConfig struct {
	MaxAttempts int
	Delay       time.Duration
	Timeout     time.Duration
}

RetryConfig defines retry behavior for operations

func DefaultRetryConfig 

func DefaultRetryConfig() *RetryConfig

DefaultRetryConfig returns sensible defaults for retry configuration

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.