package schema

const (
	// ModeReplay computes the current state by replaying the migration directory on the connected database.
	ModeReplay = iota
	// ModeInspect computes the current state by inspecting the connected database.
	ModeInspect
)

const (
	// TypeTable defines the table name holding the type information.
	TypeTable = "ent_types"

	// MaxTypes defines the max number of types can be created when
	// defining universal ids. The left 16-bits are reserved.
	MaxTypes = math.MaxUint16
)

const (
	// DefaultStringLen describes the default length for string/varchar types.
	DefaultStringLen int64 = 255
	// Null is the string representation of NULL in SQL.
	Null = "NULL"
	// PrimaryKey is the string representation of PKs in SQL.
	PrimaryKey = "PRI"
	// UniqueKey is the string representation of PKs in SQL.
	UniqueKey = "UNI"
)

Functions ¶

func Diff ¶

func Diff(ctx context.Context, u, name string, tables []*Table, opts ...MigrateOption) (err error)

Diff compares the state read from a database connection or migration directory with the state defined by the Ent schema. Changes will be written to new migration files.

func Dump ¶

func Dump(ctx context.Context, dialect, version string, tables []*Table, opts ...migrate.PlanOption) (string, error)

Dump the schema DDL for the given tables.

Types ¶

type Applier ¶

type Applier interface {
	// Apply applies the given migrate.Plan on the database.
	Apply(context.Context, dialect.ExecQuerier, *migrate.Plan) error
}

Applier is the interface that wraps the Apply method.

type ApplyFunc ¶

type ApplyFunc func(context.Context, dialect.ExecQuerier, *migrate.Plan) error

The ApplyFunc type is an adapter to allow the use of ordinary function as Applier. If f is a function with the appropriate signature, ApplyFunc(f) is an Applier that calls f.

func (ApplyFunc) Apply ¶

func (f ApplyFunc) Apply(ctx context.Context, conn dialect.ExecQuerier, plan *migrate.Plan) error

Apply calls f(ctx, tables...).

type ApplyHook ¶

type ApplyHook func(Applier) Applier

ApplyHook defines the "migration applying middleware". A function that gets an Applier and returns an Applier.

type Atlas ¶

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

Atlas atlas migration engine.

func NewMigrate ¶

func NewMigrate(drv dialect.Driver, opts ...MigrateOption) (*Atlas, error)

NewMigrate creates a new Atlas form the given dialect.Driver.

func NewMigrateURL ¶

func NewMigrateURL(u string, opts ...MigrateOption) (*Atlas, error)

NewMigrateURL create a new Atlas from the given url.

func (*Atlas) Create ¶

func (a *Atlas) Create(ctx context.Context, tables ...*Table) (err error)

Create creates all schema resources in the database. It works in an "append-only" mode, which means, it only creates tables, appends columns to tables or modifies column types.

Column can be modified by turning into a NULL from NOT NULL, or having a type conversion not resulting data altering. From example, changing varchar(255) to varchar(120) is invalid, but changing varchar(120) to varchar(255) is valid. For more info, see the convert function below.

func (*Atlas) Diff ¶

func (a *Atlas) Diff(ctx context.Context, tables ...*Table) error

Diff compares the state read from the connected database with the state defined by Ent. Changes will be written to migration files by the configured Planner.

func (*Atlas) NamedDiff ¶

func (a *Atlas) NamedDiff(ctx context.Context, name string, tables ...*Table) error

NamedDiff compares the state read from the connected database with the state defined by Ent. Changes will be written to migration files by the configured Planner.

func (*Atlas) StateReader ¶

func (a *Atlas) StateReader(tables ...*Table) migrate.StateReaderFunc

StateReader returns an atlas migrate.StateReader returning the state as described by the Ent table slice.

func (*Atlas) VerifyTableRange ¶

func (a *Atlas) VerifyTableRange(ctx context.Context, tables []*Table) error

VerifyTableRange ensures, that the defined autoincrement starting value is set for each table as defined by the TypTable. This is necessary for MySQL versions < 8.0. In those versions the defined starting value for AUTOINCREMENT columns was stored in memory, and when a server restarts happens and there are no rows yet in a table, the defined starting value is lost, which will result in incorrect behavior when working with global unique ids. Calling this method on service start ensures the information are correct and are set again, if they aren't. For MySQL versions > 8 calling this method is only required once after the upgrade.

type ChangeKind ¶

type ChangeKind uint

A ChangeKind denotes the kind of schema change.

const (
	NoChange  ChangeKind = 0
	AddSchema ChangeKind = 1 << (iota - 1)
	ModifySchema
	DropSchema
	AddTable
	ModifyTable
	DropTable
	AddColumn
	ModifyColumn
	DropColumn
	AddIndex
	ModifyIndex
	DropIndex
	AddForeignKey
	ModifyForeignKey
	DropForeignKey
	AddCheck
	ModifyCheck
	DropCheck
)

List of change types.

func (ChangeKind) Is ¶

func (k ChangeKind) Is(c ChangeKind) bool

Is reports whether c is match the given change kind.

type Column ¶

type Column struct {
	Name       string            // column name.
	Type       field.Type        // column type.
	SchemaType map[string]string // optional schema type per dialect.
	Attr       string            // extra attributes.
	Size       int64             // max size parameter for string, blob, etc.
	Key        string            // key definition (PRI, UNI or MUL).
	Unique     bool              // column with unique constraint.
	Increment  bool              // auto increment attribute.
	Nullable   bool              // null or not null attribute.
	Default    any               // default value.
	Enums      []string          // enum values.
	Collation  string            // collation type (utf8mb4_unicode_ci, utf8mb4_general_ci)

	Comment string // optional column comment.
	// contains filtered or unexported fields
}

Column schema definition for SQL dialects.

func (*Column) ConvertibleTo ¶

func (c *Column) ConvertibleTo(d *Column) bool

ConvertibleTo reports whether a column can be converted to the new column without altering its data.

func (Column) FloatType ¶

func (c Column) FloatType() bool

FloatType reports of the given type is a float type (float32, float64).

func (Column) IntType ¶

func (c Column) IntType() bool

IntType reports whether the column is an int type (int8 ... int64).

func (*Column) PrimaryKey ¶

func (c *Column) PrimaryKey() bool

PrimaryKey returns boolean indicates if this column is on of the primary key columns. Used by the migration tool when parsing the `DESCRIBE TABLE` output Go objects.

func (*Column) ScanDefault ¶

func (c *Column) ScanDefault(value string) error

ScanDefault scans the default value string to its interface type.

func (Column) UintType ¶

func (c Column) UintType() bool

UintType reports of the given type is a uint type (int8 ... int64).

func (*Column) UniqueKey ¶

func (c *Column) UniqueKey() bool

UniqueKey returns boolean indicates if this column is a unique key. Used by the migration tool when parsing the `DESCRIBE TABLE` output Go objects.

type CreateFunc ¶

type CreateFunc func(context.Context, ...*Table) error

The CreateFunc type is an adapter to allow the use of ordinary function as Creator. If f is a function with the appropriate signature, CreateFunc(f) is a Creator that calls f.

func (CreateFunc) Create ¶

func (f CreateFunc) Create(ctx context.Context, tables ...*Table) error

Create calls f(ctx, tables...).

type Creator ¶

type Creator interface {
	// Create creates the given tables in the database. See Migrate.Create for more details.
	Create(context.Context, ...*Table) error
}

Creator is the interface that wraps the Create method.

type DiffFunc ¶

type DiffFunc func(current, desired *schema.Schema) ([]schema.Change, error)

The DiffFunc type is an adapter to allow the use of ordinary function as Differ. If f is a function with the appropriate signature, DiffFunc(f) is a Differ that calls f.

func (DiffFunc) Diff ¶

func (f DiffFunc) Diff(current, desired *schema.Schema) ([]schema.Change, error)

Diff calls f(current, desired).

type DiffHook ¶

type DiffHook func(Differ) Differ

DiffHook defines the "diff middleware". A function that gets a Differ and returns a Differ.

type Differ ¶

type Differ interface {
	// Diff returns a list of changes that construct a migration plan.
	Diff(current, desired *schema.Schema) ([]schema.Change, error)
}

Differ is the interface that wraps the Diff method.

type DirWriter ¶

type DirWriter struct {
	Dir       migrate.Dir       // target directory.
	Formatter migrate.Formatter // optional formatter.
	// contains filtered or unexported fields
}

DirWriter implements the io.Writer interface for writing to an Atlas managed directory.

func (*DirWriter) Change ¶

func (d *DirWriter) Change(comment string)

Change converts all written statement so far into a migration change with the given comment.

func (*DirWriter) Flush ¶

func (d *DirWriter) Flush(name string) error

Flush flushes the written statements to the directory.

func (*DirWriter) FlushChange ¶

func (d *DirWriter) FlushChange(name, comment string) error

FlushChange combines Change and Flush.

func (*DirWriter) Write ¶

func (d *DirWriter) Write(p []byte) (int, error)

Write implements the io.Writer interface.

type Expr ¶

type Expr string

Expr represents a raw expression. It is used to distinguish between literal values and raw expressions when defining default values.

type ForeignKey ¶

type ForeignKey struct {
	Symbol     string          // foreign-key name. Generated if empty.
	Columns    []*Column       // table column
	RefTable   *Table          // referenced table.
	RefColumns []*Column       // referenced columns.
	OnUpdate   ReferenceOption // action on update.
	OnDelete   ReferenceOption // action on delete.
}

ForeignKey definition for creation.

func (ForeignKey) DSL ¶

func (fk ForeignKey) DSL() *sql.ForeignKeyBuilder

DSL returns a default DSL query for a foreign-key.

type Hook ¶

type Hook func(Creator) Creator

Hook defines the "create middleware". A function that gets a Creator and returns a Creator. For example:

hook := func(next schema.Creator) schema.Creator {
	return schema.CreateFunc(func(ctx context.Context, tables ...*schema.Table) error {
		fmt.Println("Tables:", tables)
		return next.Create(ctx, tables...)
	})
}

type Index ¶

type Index struct {
	Name       string                  // index name.
	Unique     bool                    // uniqueness.
	Columns    []*Column               // actual table columns.
	Annotation *entsql.IndexAnnotation // index annotation.
	// contains filtered or unexported fields
}

Index definition for table index.

func (*Index) Builder ¶

func (i *Index) Builder(table string) *sql.IndexBuilder

Builder returns the query builder for index creation. The DSL is identical in all dialects.

func (*Index) DropBuilder ¶

func (i *Index) DropBuilder(table string) *sql.DropIndexBuilder

DropBuilder returns the query builder for the drop index.

type Indexes ¶

type Indexes []*Index

Indexes used for scanning all sql.Rows into a list of indexes, because multiple sql rows can represent the same index (multi-columns indexes).

type MigrateOption ¶

type MigrateOption func(*Atlas)

MigrateOption allows configuring Atlas using functional arguments.

func WithApplyHook ¶

func WithApplyHook(hooks ...ApplyHook) MigrateOption

WithApplyHook adds a list of ApplyHook to the schema migration.

schema.WithApplyHook(func(next schema.Applier) schema.Applier {
	return schema.ApplyFunc(func(ctx context.Context, conn dialect.ExecQuerier, plan *migrate.Plan) error {
		// Example to hook into the apply process, or implement
		// a custom applier.
		//
		//	for _, c := range plan.Changes {
		//		fmt.Printf("%s: %s", c.Comment, c.Cmd)
		//	}
		//
		return next.Apply(ctx, conn, plan)
	})
})

func WithDialect ¶

func WithDialect(d string) MigrateOption

WithDialect configures the Ent dialect to use when migrating for an Atlas supported dialect flavor. As an example, Ent can work with TiDB in MySQL dialect and Atlas can handle TiDB migrations.

func WithDiffHook ¶

func WithDiffHook(hooks ...DiffHook) MigrateOption

WithDiffHook adds a list of DiffHook to the schema migration.

schema.WithDiffHook(func(next schema.Differ) schema.Differ {
	return schema.DiffFunc(func(current, desired *atlas.Schema) ([]atlas.Change, error) {
		// Code before standard diff.
		changes, err := next.Diff(current, desired)
		if err != nil {
			return nil, err
		}
		// After diff, you can filter
		// changes or return new ones.
		return changes, nil
	})
})

func WithDiffOptions ¶

func WithDiffOptions(opts ...schema.DiffOption) MigrateOption

WithDiffOptions adds a list of options to pass to the diff engine.

func WithDir ¶

func WithDir(dir migrate.Dir) MigrateOption

WithDir sets the atlas migration directory to use to store migration files.

func WithDropColumn ¶

func WithDropColumn(b bool) MigrateOption

WithDropColumn sets the columns dropping option to the migration. Defaults to false.

func WithDropIndex ¶

func WithDropIndex(b bool) MigrateOption

WithDropIndex sets the indexes dropping option to the migration. Defaults to false.

func WithErrNoPlan ¶

func WithErrNoPlan(b bool) MigrateOption

WithErrNoPlan sets Atlas to returns a migrate.ErrNoPlan in case the migration plan is empty. Defaults to false.

func WithForeignKeys ¶

func WithForeignKeys(b bool) MigrateOption

WithForeignKeys enables creating foreign-key in ddl. Defaults to true.

func WithFormatter ¶

func WithFormatter(fmt migrate.Formatter) MigrateOption

WithFormatter sets atlas formatter to use to write changes to migration files.

func WithGlobalUniqueID ¶

func WithGlobalUniqueID(b bool) MigrateOption

WithGlobalUniqueID sets the universal ids options to the migration. Defaults to false.

func WithHooks ¶

func WithHooks(hooks ...Hook) MigrateOption

WithHooks adds a list of hooks to the schema migration.

func WithIndent ¶

func WithIndent(indent string) MigrateOption

WithIndent sets Atlas to generate SQL statements with indentation. An empty string indicates no indentation.

func WithMigrationMode ¶

func WithMigrationMode(mode Mode) MigrateOption

WithMigrationMode instructs atlas how to compute the current state of the schema. This can be done by either replaying (ModeReplay) the migration directory on the connected database, or by inspecting (ModeInspect) the connection. Currently, ModeReplay is opt-in, and ModeInspect is the default. In future versions, ModeReplay will become the default behavior. This option has no effect when using online migrations.

func WithSchemaName ¶

func WithSchemaName(ns string) MigrateOption

WithSchemaName sets the database schema for the migration. If not set, the CURRENT_SCHEMA() is used.

func WithSkipChanges ¶

func WithSkipChanges(skip ChangeKind) MigrateOption

WithSkipChanges allows skipping/filtering list of changes returned by the Differ before executing migration planning.

SkipChanges(schema.DropTable|schema.DropColumn)

type Mode ¶

type Mode uint

Mode to compute the current state.

type MySQL ¶

type MySQL struct {
	dialect.Driver
	// contains filtered or unexported fields
}

MySQL adapter for Atlas migration engine.

type Postgres ¶

type Postgres struct {
	dialect.Driver
	// contains filtered or unexported fields
}

Postgres adapter for Atlas migration engine.

type ReferenceOption ¶

type ReferenceOption string

ReferenceOption for constraint actions.

const (
	NoAction   ReferenceOption = "NO ACTION"
	Restrict   ReferenceOption = "RESTRICT"
	Cascade    ReferenceOption = "CASCADE"
	SetNull    ReferenceOption = "SET NULL"
	SetDefault ReferenceOption = "SET DEFAULT"
)

Reference options.

func (ReferenceOption) ConstName ¶

func (r ReferenceOption) ConstName() string

ConstName returns the constant name of a reference option. It's used by entc for printing the constant name in templates.

type SQLite ¶

type SQLite struct {
	dialect.Driver
	WithForeignKeys bool
}

SQLite adapter for Atlas migration engine.

func (*SQLite) Tx ¶

func (d *SQLite) Tx(ctx context.Context) (dialect.Tx, error)

Tx implements opens a transaction.

type SQLiteTx ¶

type SQLiteTx struct {
	dialect.Tx
	// contains filtered or unexported fields
}

SQLiteTx implements dialect.Tx.

func (*SQLiteTx) Commit ¶

func (tx *SQLiteTx) Commit() error

Commit ensures foreign keys are toggled back on after commit.

func (*SQLiteTx) Rollback ¶

func (tx *SQLiteTx) Rollback() error

Rollback ensures foreign keys are toggled back on after rollback.

type Table ¶

type Table struct {
	Name    string
	Schema  string
	Columns []*Column

	Indexes     []*Index
	PrimaryKey  []*Column
	ForeignKeys []*ForeignKey
	Annotation  *entsql.Annotation
	Comment     string
	View        bool // Indicate the table is a view.
	// contains filtered or unexported fields
}

Table schema definition for SQL dialects.

func CopyTables ¶

func CopyTables(tables []*Table) ([]*Table, error)

CopyTables returns a deep-copy of the given tables. This utility function is useful for copying the generated schema tables (i.e. migrate.Tables) before running schema migration when there is a need for execute multiple migrations concurrently. e.g. running parallel unit-tests using the generated enttest package.

func NewTable ¶

func NewTable(name string) *Table

NewTable returns a new table with the given name.

func NewTypesTable ¶

func NewTypesTable() *Table

NewTypesTable returns a new table for holding the global-id information.

func NewView ¶

func NewView(name string) *Table

NewView returns a new view with the given name.

func (*Table) AddColumn ¶

func (t *Table) AddColumn(c *Column) *Table

AddColumn adds a new column to the table.

func (*Table) AddForeignKey ¶

func (t *Table) AddForeignKey(fk *ForeignKey) *Table

AddForeignKey adds a foreign key to the table.

func (*Table) AddIndex ¶

func (t *Table) AddIndex(name string, unique bool, columns []string) *Table

AddIndex creates and adds a new index to the table from the given options.

func (*Table) AddPrimary ¶

func (t *Table) AddPrimary(c *Column) *Table

AddPrimary adds a new primary key to the table.

func (*Table) Column ¶

func (t *Table) Column(name string) (*Column, bool)

Column returns the column with the given name. If exists.

func (*Table) HasColumn ¶

func (t *Table) HasColumn(name string) bool

HasColumn reports if the table contains a column with the given name.

func (*Table) Index ¶

func (t *Table) Index(name string) (*Index, bool)

Index returns a table index by its exact name.

func (*Table) SetAnnotation ¶

func (t *Table) SetAnnotation(ant *entsql.Annotation) *Table

SetAnnotation the entsql.Annotation on the table.

func (*Table) SetComment ¶

func (t *Table) SetComment(c string) *Table

SetComment sets the table comment.

func (*Table) SetSchema ¶

func (t *Table) SetSchema(s string) *Table

SetSchema sets the table schema.

type WriteDriver ¶

type WriteDriver struct {
	dialect.Driver // optional driver for query calls.
	io.Writer      // target for exec statements.
	FormatFunc     func(string) (string, error)
}

WriteDriver is a driver that writes all driver exec operations to its writer. Note that this driver is used only for printing or writing statements to SQL files, and may require manual changes to the generated SQL statements.

func NewWriteDriver ¶

func NewWriteDriver(dialect string, w io.Writer) *WriteDriver

NewWriteDriver creates a dialect.Driver that writes all driver exec statement to its writer.

func (*WriteDriver) Exec ¶

func (w *WriteDriver) Exec(_ context.Context, query string, args, res any) error

Exec implements the dialect.Driver.Exec method.

func (*WriteDriver) Query ¶

func (w *WriteDriver) Query(ctx context.Context, query string, args, res any) error

Query implements the dialect.Driver.Query method.

func (*WriteDriver) Tx ¶

func (w *WriteDriver) Tx(context.Context) (dialect.Tx, error)

Tx writes the transaction start.

Source Files ¶

atlas.go migrate.go mysql.go postgres.go schema.go sqlite.go writer.go

Version: v0.14.4 (latest)
Published: Mar 17, 2025
Platform: linux/amd64
Imports: 30 packages
Last checked: 3 hours ago –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples