darwin

package module
Version: v1.2.3 Latest Latest
Warning

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

Go to latest
Published: Apr 15, 2021 License: MIT Imports: 9 Imported by: 0

README

Darwin

CircleCI

note: this is a temporary repo for internal use and/or tracking pull requests only. Please use the one maintained by Ardan Labs.

Copyright (c) 2016 Claudemiro
Copyright 2021, Ardan Labs
info@ardanlabs.com

Project fork history:

https://github.com/ardanlabs/darwin

https://github.com/GuiaBolso/darwin

Licensing

The MIT License (MIT)

Copyright (c) 2016 Claudemiro

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

About The Project

Package darwin provides a database schema evolution api for Go.

All of the documentation can be found on the go.dev website.

Documentation

Overview

Package darwin provides a database schema evolution api for Go. The purpose of this library is just be a library. You can implement your own way of building the migration list. It is not recommended to put more than one database change per migration, if some migration fail, you exactly what statement caused the error. Also only postgres correctly handle rollback in DDL transactions.

The best way to version your migrations is like this: 1.0, 1.1, 1.2

Please read the following posts for more information on the design principles if this package.

https://flywaydb.org/documentation/faq#downgrade https://flywaydb.org/documentation/faq#rollback https://flywaydb.org/documentation/faq#hot-fixes

Given this file:

-- Version: 1.1
-- Description: Create table users
CREATE TABLE users (
	user_id       UUID,
	name          TEXT,
	email         TEXT UNIQUE,
	roles         TEXT[],
	password_hash TEXT,
	date_created  TIMESTAMP,
	date_updated  TIMESTAMP,

	-- may include full-line only comments,
	-- trailing comments are not supported
	PRIMARY KEY (user_id)
);

-- Version: 1.2
-- Description: Create table products
CREATE TABLE products (
	product_id   UUID,
	name         TEXT,
	cost         INT,
	quantity     INT,
	date_created TIMESTAMP,
	date_updated TIMESTAMP,

	PRIMARY KEY (product_id)
);

You can write this code:

package main

import (
	"database/sql"
	"log"

	"github.com/ardanlabs/darwin"
	_ "github.com/go-sql-driver/mysql"
)

var (
	//go:embed sql/schema.sql
	schemaDoc string
)

func main() {
	database, err := sql.Open("mysql", "root:@/darwin")
	if err != nil {
		log.Fatal(err)
	}

	driver, err := darwin.NewGenericDriver(db.DB, darwin.PostgresDialect{})
	if err != nil {
		return err
	}

	d := darwin.New(driver, darwin.ParseMigrations(schemaDoc))
	if err := d.Migrate(); err != nil {
		log.Println(err)
	}
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Migrate

func Migrate(d Driver, migrations []Migration) error

Migrate executes the missing migrations in database.

func Validate

func Validate(d Driver, migrations []Migration) error

Validate if the database migrations are applied and consistent.

Types

type Darwin

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

Darwin is a helper struct to access the Validate and migration functions.

func New

func New(driver Driver, migrations []Migration) Darwin

New returns a new Darwin struct

func (Darwin) Info

func (d Darwin) Info() ([]MigrationInfo, error)

Info returns the status of all migrations.

func (Darwin) Migrate

func (d Darwin) Migrate() error

Migrate executes the missing migrations in database.

func (Darwin) Validate

func (d Darwin) Validate() error

Validate if the database migrations are applied and consistent.

type Dialect

type Dialect interface {
	CreateTableSQL() string
	InsertSQL() string
	AllSQL() string
}

Dialect is used to support multiple databases by returning proper SQL.

type Driver

type Driver interface {
	Create() error
	Insert(e MigrationRecord) error
	All() ([]MigrationRecord, error)
	Exec(string) (time.Duration, error)
}

Driver is a database driver abstraction.

type DuplicateMigrationVersionError

type DuplicateMigrationVersionError struct {
	Version float64
}

DuplicateMigrationVersionError is used to report when the migration list has duplicated entries.

func (DuplicateMigrationVersionError) Error

type GenericDriver

type GenericDriver struct {
	DB      *sql.DB
	Dialect Dialect
}

GenericDriver is the default Driver, it can be configured to any database.

func NewGenericDriver

func NewGenericDriver(db *sql.DB, dialect Dialect) (*GenericDriver, error)

NewGenericDriver creates a new GenericDriver configured with db and dialect.

func (*GenericDriver) All

func (m *GenericDriver) All() ([]MigrationRecord, error)

All returns all migrations applied.

func (*GenericDriver) Create

func (m *GenericDriver) Create() error

Create create the table darwin_migrations if necessary.

func (*GenericDriver) Exec

func (m *GenericDriver) Exec(script string) (time.Duration, error)

Exec execute sql scripts into database.

func (*GenericDriver) Insert

func (m *GenericDriver) Insert(e MigrationRecord) error

Insert insert a migration entry into database.

type IllegalMigrationVersionError

type IllegalMigrationVersionError struct {
	Version float64
}

IllegalMigrationVersionError is used to report when the migration has an illegal Version number.

func (IllegalMigrationVersionError) Error

type InvalidChecksumError

type InvalidChecksumError struct {
	Version float64
}

InvalidChecksumError is used to report when a migration was modified.

func (InvalidChecksumError) Error

func (i InvalidChecksumError) Error() string

type Migration

type Migration struct {
	Version     float64
	Description string
	Script      string
}

Migration represents a database migrations.

func ParseMigrations

func ParseMigrations(s string) []Migration

ParseMigrations takes a string that represents a text formatted set of migrations and parse them for use.

func (Migration) Checksum

func (m Migration) Checksum() string

Checksum calculate the Script md5.

type MigrationInfo

type MigrationInfo struct {
	Status    Status
	Error     error
	Migration Migration
}

MigrationInfo is a struct used in the infoChan to inform clients about the migration being applied.

func Info

func Info(d Driver, migrations []Migration) ([]MigrationInfo, error)

Info returns the status of all migrations.

type MigrationRecord

type MigrationRecord struct {
	Version       float64
	Description   string
	Checksum      string
	AppliedAt     time.Time
	ExecutionTime time.Duration
}

MigrationRecord is the entry in schema table.

type MySQLDialect

type MySQLDialect struct{}

MySQLDialect a Dialect configured for MySQL.

func (MySQLDialect) AllSQL

func (m MySQLDialect) AllSQL() string

AllSQL returns a SQL to get all entries in the table.

func (MySQLDialect) CreateTableSQL

func (m MySQLDialect) CreateTableSQL() string

CreateTableSQL returns the SQL to create the schema table.

func (MySQLDialect) InsertSQL

func (m MySQLDialect) InsertSQL() string

InsertSQL returns the SQL to insert a new migration in the schema table.

type PostgresDialect

type PostgresDialect struct{}

PostgresDialect a Dialect configured for PostgreSQL.

func (PostgresDialect) AllSQL

func (p PostgresDialect) AllSQL() string

AllSQL returns a SQL to get all entries in the table.

func (PostgresDialect) CreateTableSQL

func (p PostgresDialect) CreateTableSQL() string

CreateTableSQL returns the SQL to create the schema table.

func (PostgresDialect) InsertSQL

func (p PostgresDialect) InsertSQL() string

InsertSQL returns the SQL to insert a new migration in the schema table.

type QLDialect

type QLDialect struct{}

QLDialect implements Dialect interface for ql database.

func (QLDialect) AllSQL

func (QLDialect) AllSQL() string

AllSQL returns a SQL to get all entries in the table.

func (QLDialect) CreateTableSQL

func (QLDialect) CreateTableSQL() string

CreateTableSQL returns the SQL to create the schema table.

func (QLDialect) InsertSQL

func (QLDialect) InsertSQL() string

InsertSQL returns the SQL to insert a new migration in the schema table.

type RemovedMigrationError

type RemovedMigrationError struct {
	Version float64
}

RemovedMigrationError is used to report when a migration is removed from the list.

func (RemovedMigrationError) Error

func (r RemovedMigrationError) Error() string

type SqliteDialect

type SqliteDialect struct{}

SqliteDialect a Dialect configured for Sqlite3.

func (SqliteDialect) AllSQL

func (s SqliteDialect) AllSQL() string

AllSQL returns a SQL to get all entries in the table.

func (SqliteDialect) CreateTableSQL

func (s SqliteDialect) CreateTableSQL() string

CreateTableSQL returns the SQL to create the schema table.

func (SqliteDialect) InsertSQL

func (s SqliteDialect) InsertSQL() string

InsertSQL returns the SQL to insert a new migration in the schema table.

type Status

type Status int

Status is a migration status value.

const (

	// Ignored means that the migrations was not appied to the database.
	Ignored Status = iota

	// Applied means that the migrations was successfully applied to the database.
	Applied

	// Pending means that the migrations is a new migration and it is waiting
	// to be applied to the database.
	Pending

	// Error means that the migration could not be applied to the database.
	Error
)

func (Status) String

func (s Status) String() string

String implements the Stringer interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL