package module
v1.14.4 Latest Latest

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

Go to latest
Published: Oct 6, 2022 License: MIT Imports: 12 Imported by: 151



Actions Status Go Reference

A Common DSL for Migrating Databases

Supported Database Engines

Fizz supports minimum supported version of all supported database engines. Currently, the following database engines are officially supported. (Since Fizz is used with the migration feature of Pop, supported databases and the versions are correlated with Pop.)

  • PostgreSQL 10
  • MySQL 5.7 / MariaDB 10.3
  • SQLite3 3.22
  • CockroachDB v21.1
  • MSSQL 2017 (not fully supported)


Create a Table
create_table("users") {
  t.Column("id", "integer", {primary: true})
  t.Column("email", "string", {})
  t.Column("twitter_handle", "string", {"size": 50})
  t.Column("age", "integer", {"default": 0})
  t.Column("admin", "bool", {"default": false})
  t.Column("company_id", "uuid", {"default_raw": "uuid_generate_v1()"})
  t.Column("bio", "text", {"null": true})
  t.Column("joined_at", "timestamp", {})
  t.Index("email", {"unique": true})

create_table("todos") {
  t.Column("user_id", "integer", {})
  t.Column("title", "string", {"size": 100})
  t.Column("details", "text", {"null": true})
  t.ForeignKey("user_id", {"users": ["id"]}, {"on_delete": "cascade"})

The id column don't have to be an integer. For instance, your can use an UUID type instead:

create_table("users") {
  t.Column("id", "uuid", {primary: true})
  // ...

By default, fizz will generate two timestamp columns: created_at and updated_at.

The t.Columns method takes the following arguments: name of the column, the type of the field, and finally the last argument is any options you want to set on that column.

"Common" Types:
  • string
  • text
  • timestamp, time, datetime
  • integer
  • bool
  • uuid

Any other type passed it will be be passed straight through to the underlying database.

For example for PostgreSQL you could pass jsonband it will be supported, however, SQLite will yell very loudly at you if you do the same thing!

Supported Options:
  • size - The size of the column. For example if you wanted a varchar(50) in Postgres you would do: t.Column("column_name", "string", {"size": 50})
  • null - By default columns are not allowed to be null.
  • default - The default value you want for this column. By default this is null.
  • default_raw - The default value defined as a database function.
  • after - (MySQL Only) Add a column after another column in the table. example: {"after":"created_at"}
  • first - (MySQL Only) Add a column to the first position in the table. example: {"first": true}
Composite primary key
create_table("user_privileges") {
	t.Column("user_id", "int")
	t.Column("privilege_id", "int")
	t.PrimaryKey("user_id", "privilege_id")

Please note that the t.PrimaryKey statement MUST be after the columns definitions.

Drop a Table
Rename a Table
rename_table("old_table_name", "new_table_name")
Add a Column
add_column("table_name", "column_name", "string", {})

See above for more details on column types and options.

Alter a column
change_column("table_name", "column_name", "string", {})
Rename a Column
rename_column("table_name", "old_column_name", "new_column_name")
Drop a Column
drop_column("table_name", "column_name")
Add an Index
Supported Options:
  • name - This defaults to table_name_column_name_idx
  • unique
Simple Index:
add_index("table_name", "column_name", {})
Multi-Column Index:
add_index("table_name", ["column_1", "column_2"], {})
Unique Index:
add_index("table_name", "column_name", {"unique": true})
Index Names:
add_index("table_name", "column_name", {}) # name => table_name_column_name_idx
add_index("table_name", "column_name", {"name": "custom_index_name"})
Rename an Index
rename_index("table_name", "old_index_name", "new_index_name")
Drop an Index
drop_index("table_name", "index_name")
Add a Foreign Key
add_foreign_key("table_name", "field", {"ref_table_name": ["ref_column"]}, {
    "name": "optional_fk_name",
    "on_delete": "action",
    "on_update": "action",

Supported Options
  • name - This defaults to table_name_ref_table_name_ref_column_name_fk
  • on_delete - CASCADE, SET NULL, ...
  • on_update

Note: on_update and on_delete are not supported on CockroachDB yet.

Drop a Foreign Key
drop_foreign_key("table_name", "fk_name", {"if_exists": true})
Supported Options
  • if_exists - Adds IF EXISTS condition
sql("select * from users;")
Execute an External Command

Sometimes during a migration you need to shell out to an external command.

exec("echo hello")



To run end-to-end tests, use

make test

If you made changes to the end-to-end tests and want to update the fixtures, run the following command a couple of times until tests pass:

REFRESH_FIXTURES=true make test



Package fizz is a common DSL for writing SQL migrations



View Source
const Version = "v1.14.3"

Version gives the current fizz version.


View Source
var CREATED_COL = Column{Name: "created_at", ColType: "timestamp", Options: nil}
View Source
var INT_ID_COL = Column{
	Name:    "id",
	Primary: true,
	ColType: "integer",
	Options: Options{},

Deprecated: Fizz won't force you to have an ID field now.

View Source
var UPDATED_COL = Column{Name: "updated_at", ColType: "timestamp", Options: nil}
View Source
var UUID_ID_COL = Column{
	Name:    "id",
	Primary: true,
	ColType: "uuid",
	Options: Options{},

Deprecated: Fizz won't force you to have an ID field now.


func AFile

func AFile(f io.Reader, t Translator) (string, error)

AFile reads in a fizz migration from an io.Reader and translates its contents to SQL.

func AString

func AString(s string, t Translator) (string, error)

AString reads a fizz string, and translates its contents to SQL.


type BubbleType

type BubbleType int

type Bubbler

type Bubbler struct {
	// contains filtered or unexported fields

func NewBubbler

func NewBubbler(t Translator) *Bubbler

func (*Bubbler) Bubble

func (b *Bubbler) Bubble(s string) (string, error)

func (*Bubbler) String

func (b *Bubbler) String() string

type Column

type Column struct {
	Name    string
	ColType string
	Primary bool
	Options map[string]interface{}

func (Column) String added in v1.0.8

func (c Column) String() string

type ForeignKey

type ForeignKey struct {
	Name       string
	Column     string
	References ForeignKeyRef
	Options    Options

func (ForeignKey) String added in v1.6.0

func (f ForeignKey) String() string

type ForeignKeyRef

type ForeignKeyRef struct {
	Table   string
	Columns []string

type Index

type Index struct {
	Name    string
	Columns []string
	Unique  bool
	Options Options

Index is the index definition for fizz.

func (Index) String added in v1.5.0

func (i Index) String() string

type Options

type Options map[string]interface{}

Options is a generic map of options.

type Table

type Table struct {
	Name        string `db:"name"`
	Columns     []Column
	Indexes     []Index
	ForeignKeys []ForeignKey

	Options map[string]interface{}
	// contains filtered or unexported fields

Table is the table definition for fizz.

func NewTable added in v1.4.0

func NewTable(name string, opts map[string]interface{}) Table

NewTable creates a new Table.

func (*Table) Column

func (t *Table) Column(name string, colType string, options Options) error

Column adds a column to the table definition.

func (*Table) ColumnNames

func (t *Table) ColumnNames() []string

ColumnNames returns the names of the Table's columns.

func (*Table) DisableTimestamps

func (t *Table) DisableTimestamps()

func (Table) Fizz added in v1.3.1

func (t Table) Fizz() string

Fizz returns the fizz DDL to create the table.

func (*Table) ForeignKey

func (t *Table) ForeignKey(column string, refs interface{}, options Options) error

ForeignKey adds a new foreign key to the table definition.

func (*Table) HasColumns

func (t *Table) HasColumns(args ...string) bool

HasColumns checks if the Table has all the given columns.

func (*Table) Index added in v1.5.0

func (t *Table) Index(columns interface{}, options Options) error

Index adds a new index to the table definition.

func (*Table) PrimaryKey added in v1.7.0

func (t *Table) PrimaryKey(pk ...string) error

PrimaryKey adds a primary key to the table. It's useful to define a composite primary key.

func (*Table) PrimaryKeys added in v1.7.0

func (t *Table) PrimaryKeys() []string

PrimaryKeys gets the list of registered primary key fields.

func (Table) String added in v1.0.8

func (t Table) String() string

func (*Table) Timestamp

func (t *Table) Timestamp(name string) error

Timestamp is a shortcut to add a timestamp column with default options.

func (*Table) Timestamps

func (t *Table) Timestamps() error

Timestamps adds created_at and updated_at columns to the Table definition.

func (Table) UnFizz added in v1.3.1

func (t Table) UnFizz() string

UnFizz returns the fizz DDL to remove the table.

type Translator

type Translator interface {
	CreateTable(Table) (string, error)
	DropTable(Table) (string, error)
	RenameTable([]Table) (string, error)
	AddColumn(Table) (string, error)
	ChangeColumn(Table) (string, error)
	DropColumn(Table) (string, error)
	RenameColumn(Table) (string, error)
	AddIndex(Table) (string, error)
	DropIndex(Table) (string, error)
	RenameIndex(Table) (string, error)
	AddForeignKey(Table) (string, error)
	DropForeignKey(Table) (string, error)

Translator describes the common interface to define a fizz to SQL translator.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL