ezdb

README

ezdb

EZDB (easy database) provides lightweight, simple database tooling for go applications, inspired by Rails. The specific featureset is:

• create databases
• manage migration files
• apply / rollback migrations

Quick Start

package main

import (
  "github.com/rileyr/ezdb"
  "log"
)


func main() {
  db := ezdb.New()

  // Create the database for the first time:
  if err := db.CreateDatabase(); err != nil {
    log.Fatal(err)
  }

  // Create a new migration:
  if err := db.CreateMigration("create_some_new_table"); err != nil {
    log.Fatal(err)
  }

  // Manually edit the migration file...

  // Apply all pending migrations:
  if err := db.MigrateAll(); err != nil {
    log.Fatal(err)
  }

  // Apply exactly one migration:
  if err := db.MigrateSteps(1); err != nil {
    log.Fatal(err)
  }

  // Roll back one migration:
  if err := db.MigrateSteps(-1); err != nil {
    log.Fatal(err)
  }
}

Connection Details

By default, EZDB uses the default postgres environment variables:

• PGUSER - database username
• PGPASSWORD - database password
• PGHOST - database host
• PGDATABASE - database name
• PGPORT - database port

CLI

You can use the entrypoint defined in ./cmd/cli/main.go as a standalone entrypoint, or, you can include it into your application's CLI:

package main

import(
  "github.com/spf13/cobra"
  "github.com/rileyr/ezdb/cmd"
)

func myAppCLI() *cobra.Command {
  c := &cobra.Command{}
  // blah blah blah
  return c
}

func main() {
  c := myAppCLI()
  c.AddCommand(cmd.NewCommand())
  c.Execute()
}

Documentation

Index

• type ConnectionData
  • func (cd ConnectionData) ConnString() string
  • func (cd ConnectionData) DSN() string
• type Connector
• type ConnectorFunc
  • func (cf ConnectorFunc) Data() (ConnectionData, error)
• type DB
  • func New(opts ...Option) *DB
  • func (db *DB) CreateDatabase() error
  • func (db *DB) CreateMigration(name string) error
  • func (db *DB) MigrateAll() error
  • func (db *DB) MigrateSteps(steps int) error
• type EnvConnector
  • func NewDefaultEnvConnector() EnvConnector
  • func (e EnvConnector) Data() (ConnectionData, error)
• type Option
  • func WithConnector(c Connector) Option
  • func WithMigrationDir(dir string) Option

Types

type ConnectionData

type ConnectionData struct {
	User     string
	Password string
	Host     string
	Db       string
	Port     string
}

func (ConnectionData) ConnString

func (cd ConnectionData) ConnString() string

func (ConnectionData) DSN

func (cd ConnectionData) DSN() string

type Connector

type Connector interface {
	Data() (ConnectionData, error)
}

Connector defines the interface for obtaining database connection information.

type ConnectorFunc

type ConnectorFunc func() (ConnectionData, error)

ConnectorFunc is a helper type for function-only implementations of Connector

func (ConnectorFunc) Data

func (cf ConnectorFunc) Data() (ConnectionData, error)

type DB

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

DB implements the functionality provided by the ezdb package

func New

func New(opts ...Option) *DB

New returns a new DB with the given options.

func (*DB) CreateDatabase

func (db *DB) CreateDatabase() error

CreateDatabase creates the database, for initial environment setup.

func (*DB) CreateMigration

func (db *DB) CreateMigration(name string) error

CreateMigration creates set of migration files with the current timestamp and given name.

func (*DB) MigrateAll

func (db *DB) MigrateAll() error

MigrateAll applies all outstanding migrations to the database.

func (*DB) MigrateSteps

func (db *DB) MigrateSteps(steps int) error

MigrateSteps applies a specific number of migrations to the database. If steps are negative, migrations will be rolled back.

type EnvConnector

type EnvConnector struct {
	UserKey     string
	PasswordKey string
	HostKey     string
	DbKey       string
	PortKey     string
}

EnvConnector implements Connector by pulling values from environment variables.

func NewDefaultEnvConnector

func NewDefaultEnvConnector() EnvConnector

func (EnvConnector) Data

func (e EnvConnector) Data() (ConnectionData, error)

type Option

type Option func(*DB)

func WithConnector

func WithConnector(c Connector) Option

func WithMigrationDir

func WithMigrationDir(dir string) Option