atlas

Documentation

Index

• func TempFile(content, ext string) (string, func() error, error)
• type AppliedFile
• type ApplyParams
• type ApplyReport
• type Changes
• type Client
  • func NewClient(dir, name string) (*Client, error)
  • func NewClientWithPath(path string) *Client
  • func (c *Client) Apply(ctx context.Context, data *ApplyParams) (*ApplyReport, error)
  • func (c *Client) Lint(ctx context.Context, data *LintParams) (*SummaryReport, error)
  • func (c *Client) SchemaApply(ctx context.Context, data *SchemaApplyParams) (*SchemaApply, error)
  • func (c *Client) SchemaInspect(ctx context.Context, data *SchemaInspectParams) (string, error)
  • func (c *Client) Status(ctx context.Context, data *StatusParams) (*StatusReport, error)
• type Env
• type File
• type FileReport
• type LintParams
• type Revision
• type SchemaApply
• type SchemaApplyParams
• type SchemaInspectParams
• type StatusParams
• type StatusReport
  • func (r StatusReport) Amount(version string) (amount uint64, ok bool)
  • func (r StatusReport) LatestVersion() string
• type StmtError
• type SummaryReport
• type Vars
  • func (v Vars) AsArgs() []string

Functions

func TempFile

func TempFile(content, ext string) (string, func() error, error)

Types

type AppliedFile

type AppliedFile struct {
	File
	Start   time.Time
	End     time.Time
	Skipped int      // Amount of skipped SQL statements in a partially applied file.
	Applied []string // SQL statements applied with success
	Error   *struct {
		SQL   string // SQL statement that failed.
		Error string // Error returned by the database.
	}
}

AppliedFile is part of an ApplyReport containing information about an applied file in a migration attempt.

type ApplyParams

type ApplyParams struct {
	DirURL          string
	URL             string
	RevisionsSchema string
	BaselineVersion string
	TxMode          string
	Amount          uint64
}

ApplyParams are the parameters for the `migrate apply` command.

type ApplyReport

type ApplyReport struct {
	Pending []File         `json:"Pending,omitempty"` // Pending migration files
	Applied []*AppliedFile `json:"Applied,omitempty"` // Applied files
	Current string         `json:"Current,omitempty"` // Current migration version
	Target  string         `json:"Target,omitempty"`  // Target migration version
	Start   time.Time
	End     time.Time
	// Error is set even then, if it was not caused by a statement in a migration file,
	// but by Atlas, e.g. when committing or rolling back a transaction.
	Error string `json:"Error,omitempty"`
}

ApplyReport contains a summary of a migration applying attempt on a database.

type Changes

type Changes struct {
	Applied []string   `json:"Applied,omitempty"` // SQL changes applied with success
	Pending []string   `json:"Pending,omitempty"` // SQL changes that were not applied
	Error   *StmtError `json:"Error,omitempty"`   // Error that occurred during applying
}

Changes represents a list of changes that are pending or applied.

type Client

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

Client is a client for the Atlas CLI.

func NewClient

func NewClient(dir, name string) (*Client, error)

NewClient returns a new Atlas client. The client will try to find the Atlas CLI in the current directory, and in the PATH.

func NewClientWithPath

func NewClientWithPath(path string) *Client

NewClientWithPath returns a new Atlas client with the given atlas-cli path.

func (*Client) Apply

func (c *Client) Apply(ctx context.Context, data *ApplyParams) (*ApplyReport, error)

Apply runs the 'migrate apply' command.

func (*Client) Lint

func (c *Client) Lint(ctx context.Context, data *LintParams) (*SummaryReport, error)

Lint runs the 'migrate lint' command.

func (*Client) SchemaApply

func (c *Client) SchemaApply(ctx context.Context, data *SchemaApplyParams) (*SchemaApply, error)

SchemaApply runs the 'schema apply' command.

func (*Client) SchemaInspect

func (c *Client) SchemaInspect(ctx context.Context, data *SchemaInspectParams) (string, error)

SchemaInspect runs the 'schema inspect' command.

func (*Client) Status

func (c *Client) Status(ctx context.Context, data *StatusParams) (*StatusReport, error)

Status runs the 'migrate status' command.

type Env

type Env struct {
	Driver string         `json:"Driver,omitempty"` // Driver name.
	URL    *sqlclient.URL `json:"URL,omitempty"`    // URL to dev database.
	Dir    string         `json:"Dir,omitempty"`    // Path to migration directory.
}

Env holds the environment information.

type File

type File struct {
	Name        string `json:"Name,omitempty"`
	Version     string `json:"Version,omitempty"`
	Description string `json:"Description,omitempty"`
}

File wraps migrate.File to implement json.Marshaler.

type FileReport

type FileReport struct {
	Name    string            `json:"Name,omitempty"`    // Name of the file.
	Text    string            `json:"Text,omitempty"`    // Contents of the file.
	Reports []sqlcheck.Report `json:"Reports,omitempty"` // List of reports.
	Error   string            `json:"Error,omitempty"`   // File specific error.
}

FileReport contains a summary of the analysis of a single file.

type LintParams

type LintParams struct {
	ConfigURL string
	DevURL    string
	DirURL    string
	Latest    uint64
	Vars      Vars
}

LintParams are the parameters for the `migrate lint` command.

type Revision

type Revision struct {
	Version         string        `json:"Version"`             // Version of the migration.
	Description     string        `json:"Description"`         // Description of this migration.
	Type            string        `json:"Type"`                // Type of the migration.
	Applied         int           `json:"Applied"`             // Applied amount of statements in the migration.
	Total           int           `json:"Total"`               // Total amount of statements in the migration.
	ExecutedAt      time.Time     `json:"ExecutedAt"`          // ExecutedAt is the starting point of execution.
	ExecutionTime   time.Duration `json:"ExecutionTime"`       // ExecutionTime of the migration.
	Error           string        `json:"Error,omitempty"`     // Error of the migration, if any occurred.
	ErrorStmt       string        `json:"ErrorStmt,omitempty"` // ErrorStmt is the statement that raised Error.
	OperatorVersion string        `json:"OperatorVersion"`     // OperatorVersion that executed this migration.
}

A Revision denotes an applied migration in a deployment. Used to track migration executions state of a database.

type SchemaApply

type SchemaApply struct {
	Env
	Changes Changes `json:"Changes,omitempty"`
	// General error that occurred during execution.
	// e.g., when committing or rolling back a transaction.
	Error string `json:"Error,omitempty"`
}

SchemaApply contains a summary of a 'schema apply' execution on a database.

type SchemaApplyParams

type SchemaApplyParams struct {
	ConfigURL string
	DevURL    string
	DryRun    bool
	Exclude   []string
	Schema    []string
	To        string
	URL       string
	Vars      Vars
}

SchemaApplyParams are the parameters for the `schema apply` command.

type SchemaInspectParams

type SchemaInspectParams struct {
	ConfigURL string
	DevURL    string
	Exclude   []string
	Format    string
	Schema    []string
	URL       string
}

SchemaInspectParams are the parameters for the `schema inspect` command.

type StatusParams

type StatusParams struct {
	DirURL          string
	URL             string
	RevisionsSchema string
}

StatusParams are the parameters for the `migrate status` command.

type StatusReport

type StatusReport struct {
	Available []File      `json:"Available,omitempty"` // Available migration files
	Pending   []File      `json:"Pending,omitempty"`   // Pending migration files
	Applied   []*Revision `json:"Applied,omitempty"`   // Applied migration files
	Current   string      `json:"Current,omitempty"`   // Current migration version
	Next      string      `json:"Next,omitempty"`      // Next migration version
	Count     int         `json:"Count,omitempty"`     // Count of applied statements of the last revision
	Total     int         `json:"Total,omitempty"`     // Total statements of the last migration
	Status    string      `json:"Status,omitempty"`    // Status of migration (OK, PENDING)
	Error     string      `json:"Error,omitempty"`     // Last Error that occurred
	SQL       string      `json:"SQL,omitempty"`       // SQL that caused the last Error
}

StatusReport contains a summary of the migration status of a database.

func (StatusReport) Amount

func (r StatusReport) Amount(version string) (amount uint64, ok bool)

Amount returns the number of migrations need to apply for the given version.

The second return value is true if the version is found and the database is up-to-date.

If the version is not found, it returns 0 and the second return value is false.

func (StatusReport) LatestVersion

func (r StatusReport) LatestVersion() string

LatestVersion returns the latest version of the migrations directory.

type StmtError

type StmtError struct {
	Stmt string `json:"Stmt,omitempty"` // SQL statement that failed.
	Text string `json:"Text,omitempty"` // Error message as returned by the database.
}

StmtError groups a statement with its execution error.

type SummaryReport

type SummaryReport struct {
	// Steps of the analysis. Added in verbose mode.
	Steps []struct {
		Name   string `json:"Name,omitempty"`   // Step name.
		Text   string `json:"Text,omitempty"`   // Step description.
		Error  string `json:"Error,omitempty"`  // Error that cause the execution to halt.
		Result any    `json:"Result,omitempty"` // Result of the step. For example, a diagnostic.
	}

	// Schema versions found by the runner.
	Schema struct {
		Current string `json:"Current,omitempty"` // Current schema.
		Desired string `json:"Desired,omitempty"` // Desired schema.
	}

	// Files reports. Non-empty in case there are findings.
	Files []*FileReport `json:"Files,omitempty"`
}

A SummaryReport contains a summary of the analysis of all files. It is used as an input to templates to report the CI results.

type Vars

type Vars map[string]string

func (Vars) AsArgs

func (v Vars) AsArgs() []string