dockerdb

README

dockerdb

This repository contains a package for fast database deployment in Docker container.

Why dockerdb?

Usage

Download and install it:

go get github.com/egorgasay/dockerdb/v3

Import it in your code:

import "github.com/egorgasay/dockerdb/v3"

The first launch should look like this:

vdb, err := dockerdb.New(ctx, config)
if err != nil {
  log.Fatal(err)
}

If the database was turned off, then you can turn it on using:

err := vdb.Run(ctx)
if err != nil {
  log.Fatal(err)
}

SQL DB Example

package main

import (
	"context"
	"fmt"
	"log"
	
	"github.com/egorgasay/dockerdb/v3"

	_ "github.com/lib/pq"
)

func main() {
	ctx := context.TODO()
	config := dockerdb.EmptyConfig().DBName("test").DBUser("test").
		DBPassword("test").StandardDBPort("5432").
		Vendor(dockerdb.Postgres15).SQL().PullImage()

	vdb, err := dockerdb.New(ctx, config.Build())
	if err != nil {
		log.Fatal(err)
	}
	defer vdb.Clear(ctx)

	var result string
	err = vdb.SQL().QueryRow("SELECT 'db is up'").Scan(&result)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result)
}

NoSQL DB Example

package main

import (
    "context"
	"fmt"
	"log"
	
	"github.com/egorgasay/dockerdb/v3"
	
	redis "github.com/redis/go-redis/v9"
)

func main() {
	var cl *keydb.Client
	var err error
	ctx := context.TODO()

	config := dockerdb.EmptyConfig().
		DBName("myredisdb").StandardDBPort("6379").
		Vendor("redis"). // name from dockerhub
		NoSQL(func(conf dockerdb.Config) (stop bool) { // func that will determine that the db is ready for use
			cl = redis.NewClient(&redis.Options{
				Addr: fmt.Sprintf("%s:%s", "127.0.0.1", conf.GetActualPort()),
				DB:   0,
			})

			_, err = cl.Ping(ctx).Result()
			log.Println(err)
			return err == nil
		}, 10, time.Second*2).PullImage()

	vdb, err := dockerdb.New(ctx, config.Build())
	if err != nil {
		log.Fatal(err)
	}
	defer vdb.Clear(ctx)

	fmt.Println("db is up")
}

Documentation

Overview

Package dockerdb allows user to create virtual databases using docker. Tested with PostgreSQL, MySQL, MS SQL.

Index

• Variables
• func Pull(ctx context.Context, image DockerHubName) error
• func Run(ctx context.Context, ID string) error
• func SetMaxWaitTime(sec time.Duration)
• type Config
  • func EmptyConfig() *Config
  • func (c *Config) ActualPort(port nat.Port) *Config
  • func (c *Config) Build() Config
  • func (c *Config) DBName(name string) *Config
  • func (c *Config) DBPassword(password string) *Config
  • func (c *Config) DBUser(user string) *Config
  • func (c *Config) DockerEnv(env []string) *Config
  • func (c *Config) GetActualPort() nat.Port
  • func (c *Config) GetDBName() string
  • func (c *Config) GetDBPassword() string
  • func (c *Config) GetDBUser() string
  • func (c *Config) GetEnvDocker() []string
  • func (c *Config) GetSQLConnStr() string
  • func (c *Config) GetStandardDBPort() nat.Port
  • func (c *Config) NoSQL(checkWakeUp func(conf Config) (stop bool), tries int, sleepTime time.Duration) *Config
  • func (c *Config) PullImage() *Config
  • func (c *Config) SQL() *Config
  • func (c *Config) SQLConnStr(connString string) *Config
  • func (c *Config) StandardDBPort(port nat.Port) *Config
  • func (c *Config) Vendor(vendor DockerHubName) *Config
• type DockerHubName
• type VDB
  • func New(ctx context.Context, conf Config) (*VDB, error)
  • func (ddb *VDB) Clear(ctx context.Context) (err error)
  • func (ddb *VDB) GetPort() (port nat.Port)
  • func (ddb *VDB) Kill(ctx context.Context, signal string) (err error)
  • func (ddb *VDB) Pause(ctx context.Context) (err error)
  • func (ddb *VDB) Remove(ctx context.Context) (err error)
  • func (ddb *VDB) Restart(ctx context.Context) (err error)
  • func (ddb *VDB) Run(ctx context.Context) (err error)
  • func (ddb *VDB) SQL() (db *sql.DB)
  • func (ddb *VDB) Stop(ctx context.Context) (err error)
  • func (ddb *VDB) Unpause(ctx context.Context) (err error)

Variables

var (
	ErrUnknown = errors.New("unknown error")
)

Functions

func Pull

func Pull(ctx context.Context, image DockerHubName) error

Pull pulls an image from net. WARNING!! USE IT CAREFULLY! DOWNLOADING SOME db IMAGES MAY TAKE SOME TIME. Tested with PostgreSQL, MySQL, MS SQL.

func Run

func Run(ctx context.Context, ID string) error

Run launches a docker container by ID.

func SetMaxWaitTime

func SetMaxWaitTime(sec time.Duration)

Types

type Config

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

func EmptyConfig

func EmptyConfig() *Config

func (*Config) ActualPort

func (c *Config) ActualPort(port nat.Port) *Config

ActualPort allows you to set the actual port for the database. Random unused port is used by default.

func (*Config) Build

func (c *Config) Build() Config

Build builds the config. After building, the config can be used and can't be changed.

func (*Config) DBName

func (c *Config) DBName(name string) *Config

DBName sets the name of the database.

func (*Config) DBPassword

func (c *Config) DBPassword(password string) *Config

DBPassword sets the password of the database.

func (*Config) DBUser

func (c *Config) DBUser(user string) *Config

DBUser sets the user of the database.

func (*Config) DockerEnv

func (c *Config) DockerEnv(env []string) *Config

DockerEnv sets the environment variables for docker.

func (*Config) GetActualPort

func (c *Config) GetActualPort() nat.Port

func (*Config) GetDBName

func (c *Config) GetDBName() string

func (*Config) GetDBPassword

func (c *Config) GetDBPassword() string

func (*Config) GetDBUser

func (c *Config) GetDBUser() string

func (*Config) GetEnvDocker

func (c *Config) GetEnvDocker() []string

func (*Config) GetSQLConnStr

func (c *Config) GetSQLConnStr() string

func (*Config) GetStandardDBPort

func (c *Config) GetStandardDBPort() nat.Port

func (*Config) NoSQL

func (c *Config) NoSQL(checkWakeUp func(conf Config) (stop bool), tries int, sleepTime time.Duration) *Config

NoSQL sets db kind to NoSQL.

func (*Config) PullImage

func (c *Config) PullImage() *Config

PullImage pulls the vendor image.

func (*Config) SQL

func (c *Config) SQL() *Config

SQL sets db kind to SQL.

func (*Config) SQLConnStr

func (c *Config) SQLConnStr(connString string) *Config

SQLConnStr sets the SQL connection string. (Use it only for unsupported databases).

func (*Config) StandardDBPort

func (c *Config) StandardDBPort(port nat.Port) *Config

StandardDBPort represents the standard port of the database which can be used to connect to it.

func (*Config) Vendor

func (c *Config) Vendor(vendor DockerHubName) *Config

Vendor sets the vendor of the database.

type DockerHubName

type DockerHubName string

const (
	Postgres15 DockerHubName = "postgres:15"
	Postgres14 DockerHubName = "postgres:14"
	Postgres13 DockerHubName = "postgres:13"
	Postgres12 DockerHubName = "postgres:12"
	Postgres11 DockerHubName = "postgres:11"

	MySQL5Image   DockerHubName = "mysql:5.7"
	MySQL8Image   DockerHubName = "mysql:8"
	KeyDBImage    DockerHubName = "eqalpha/keydb"
	RedisImage    DockerHubName = "redis"
	ScyllaDBImage DockerHubName = "scylladb/scylla"
)

type VDB

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

func New

func New(ctx context.Context, conf Config) (*VDB, error)

New creates a new docker container and launches it

func (*VDB) Clear

func (ddb *VDB) Clear(ctx context.Context) (err error)

Clear kills and removes a container.

func (*VDB) GetPort

func (ddb *VDB) GetPort() (port nat.Port)

func (*VDB) Kill

func (ddb *VDB) Kill(ctx context.Context, signal string) (err error)

Kill kills the docker container.

func (*VDB) Pause

func (ddb *VDB) Pause(ctx context.Context) (err error)

Pause suspends the docker container.

func (*VDB) Remove

func (ddb *VDB) Remove(ctx context.Context) (err error)

Remove removes a container.

func (*VDB) Restart

func (ddb *VDB) Restart(ctx context.Context) (err error)

Restart stops and starts a container again.

func (*VDB) Run

func (ddb *VDB) Run(ctx context.Context) (err error)

Run launches the docker container.

func (*VDB) SQL

func (ddb *VDB) SQL() (db *sql.DB)

SQL returns an *sql.DB instance.

func (*VDB) Stop

func (ddb *VDB) Stop(ctx context.Context) (err error)

Stop stops the docker container.

func (*VDB) Unpause

func (ddb *VDB) Unpause(ctx context.Context) (err error)

Unpause resumes the docker container.