darwin

package module
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 

func (d DuplicateMigrationVersionError) Error() string

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 

func (i IllegalMigrationVersionError) Error() string

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.

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.