dockerdb

package module
v3.4.1 Latest Latest
Warning

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

 Go to latest Published: May 30, 2024 License: MIT Imports: 14 Imported by: 0

README

dockerdb

PkgGoDev

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)
}

Prepared Config Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/egorgasay/dockerdb/v3"

	_ "github.com/lib/pq"
)

func main() {
	ctx := context.TODO()
	vdb, err := dockerdb.New(ctx, dockerdb.PostgresConfig("simple-postgres").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

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnknown = errors.New("unknown error")
	ErrWarning = errors.New("warning")
)

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. DEPRECATED: USE vdb.Run() instead.

func SetMaxActualPortTries added in v3.2.4 

func SetMaxActualPortTries(n int)

func SetMaxWaitTime 

func SetMaxWaitTime(sec time.Duration)

func With added in v3.1.0 

func With(ctx context.Context, c Config, fn func(c Config, vdb *VDB) error) (err error)

func WithKeyDB added in v3.1.0 

func WithKeyDB(
	ctx context.Context, name string,
	checkWakeUp func(c Config) (stop bool),
	fn func(c Config, vdb *VDB) error,
) (err error)

func WithMySQL added in v3.1.0 

func WithMySQL(ctx context.Context, name string, fn func(c Config, vdb *VDB) error) (err error)

func WithPostgres added in v3.1.0 

func WithPostgres(ctx context.Context, name string, fn func(c Config, vdb *VDB) error) (err error)

func WithRedis added in v3.1.0 

func WithRedis(
	ctx context.Context, name string,
	checkWakeUp func(c Config) (stop bool),
	fn func(c Config, vdb *VDB) error,
) (err error)

func WithScyllaDB added in v3.1.0 

func WithScyllaDB(
	ctx context.Context, name string,
	checkWakeUp func(c Config) (stop bool),
	fn func(c Config, vdb *VDB) error,
) (err error)

Types

type Config 

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

func EmptyConfig 

func EmptyConfig() *Config

func KeyDBConfig added in v3.1.0 

func KeyDBConfig(dbname string, closure func(c Config) (stop bool)) *Config

func MySQLConfig added in v3.1.0 

func MySQLConfig(dbname string) *Config

func PostgresConfig added in v3.1.0 

func PostgresConfig(dbname string) *Config

func RedisConfig added in v3.1.0 

func RedisConfig(dbname string, closure func(c Config) (stop bool)) *Config

func ScyllaDBConfig added in v3.1.0 

func ScyllaDBConfig(dbname string, closure func(c Config) (stop bool)) *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) Cmd added in v3.4.0 

func (c *Config) Cmd(cmd []string) *Config

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) LimitResources added in v3.3.0 

func (c *Config) LimitResources(resources *container.Resources) *Config

LimitResources limits the resources of the container.

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

func (*Config) SQL 

func (c *Config) SQL() *Config

func (*Config) SetPullImage added in v3.4.1 

func (c *Config) SetPullImage(pull bool) *Config

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) UnimplementedSQL added in v3.1.0 

func (c *Config) UnimplementedSQL(connStringFormat string) *Config

UnimplementedSQL sets the SQL connection string format. Example template: "{user}:{password}@127.0.0.1:{port}/{dbname}"

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 *VDB, err 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) GetSQLConnStr added in v3.1.2 

func (ddb *VDB) GetSQLConnStr() string

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. Can return ErrWarning that must be not necessary to handle

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.

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.