Documentation ¶
Overview ¶
Package cmdapi holds the atlas commands used to build an atlas distribution.
Index ¶
- Variables
- func CheckForUpdate()
- func CmdApplyRun(cmd *cobra.Command, _ []string) error
- func CmdCleanRun(cmd *cobra.Command, _ []string) error
- func CmdFmtRun(cmd *cobra.Command, args []string)
- func CmdInspectRun(cmd *cobra.Command, _ []string) error
- func CmdMigrateApplyRun(cmd *cobra.Command, args []string) error
- func CmdMigrateDiffRun(cmd *cobra.Command, args []string) error
- func CmdMigrateHashRun(*cobra.Command, []string) error
- func CmdMigrateLintRun(cmd *cobra.Command, _ []string) error
- func CmdMigrateNewRun(_ *cobra.Command, args []string) error
- func CmdMigrateStatusRun(cmd *cobra.Command, _ []string) error
- func CmdMigrateValidateRun(cmd *cobra.Command, _ []string) error
- type Env
- type Lint
- type LoadOption
- type LogTTY
- type Migration
- type Project
Constants ¶
This section is empty.
Variables ¶
var ( // Root represents the root command when called without any subcommands. Root = &cobra.Command{ Use: "atlas", Short: "A database toolkit.", SilenceUsage: true, } // GlobalFlags contains flags common to many Atlas sub-commands. GlobalFlags struct { // SelectedEnv contains the environment selected from the active // project via the --env flag. SelectedEnv string // Vars contains the input variables passed from the CLI to // Atlas DDL or project files. Vars map[string]string } // EnvCmd represents the subcommand 'atlas env'. EnvCmd = &cobra.Command{ Use: "env", Short: "Print atlas environment variables.", Long: `'atlas env' prints atlas environment information. Every set environment param will be printed in the form of NAME=VALUE. List of supported environment parameters: * ATLAS_NO_UPDATE_NOTIFIER: On any command, the CLI will check for new releases using the GitHub API. This check will happen at most once every 24 hours. To cancel this behavior, set the environment variable "ATLAS_NO_UPDATE_NOTIFIER".`, Run: func(cmd *cobra.Command, args []string) { keys := []string{update.AtlasNoUpdateNotifier} for _, k := range keys { if v, ok := os.LookupEnv(k); ok { cmd.Println(fmt.Sprintf("%s=%s", k, v)) } } }, } )
var ( // MigrateFlags are the flags used in MigrateCmd (and sub-commands). MigrateFlags struct { URL string DevURL string ToURLs []string Schemas []string DirURL string DirFormat string RevisionSchema string Force bool Apply struct { DryRun bool LogFormat string AllowDirty bool FromVersion string BaselineVersion string TxMode string } Diff struct { Qualifier string // optional table qualifier } Lint struct { Format string // log formatting Latest uint // latest N migration files GitDir string // repository working dir GitBase string // branch name to compare with } } // MigrateCmd represents the migrate command. It wraps several other sub-commands. MigrateCmd = &cobra.Command{ Use: "migrate", Short: "Manage versioned migration files", Long: "'atlas migrate' wraps several sub-commands for migration management.", PersistentPreRunE: func(cmd *cobra.Command, _ []string) error { if err := migrateFlagsFromEnv(cmd, nil); err != nil { return err } if !MigrateFlags.Force { dir, err := dir(false) if err != nil { return err } if err := migrate.Validate(dir); err != nil { printChecksumErr(cmd.OutOrStderr()) cmd.SilenceUsage = true return err } } return nil }, } // MigrateApplyCmd represents the 'atlas migrate apply' subcommand. MigrateApplyCmd = &cobra.Command{ Use: "apply [flags] [count]", Short: "Applies pending migration files on the connected database.", Long: `'atlas migrate apply' reads the migration state of the connected database and computes what migrations are pending. It then attempts to apply the pending migration files in the correct order onto the database. The first argument denotes the maximum number of migration files to apply. As a safety measure 'atlas migrate apply' will abort with an error, if: - the migration directory is not in sync with the 'atlas.sum' file - the migration and database history do not match each other If run with the "--dry-run" flag, atlas will not execute any SQL.`, Example: ` atlas migrate apply -u mysql://user:pass@localhost:3306/dbname atlas migrate apply --dir file:///path/to/migration/directory --url mysql://user:pass@localhost:3306/dbname 1 atlas migrate apply --env dev 1 atlas migrate apply --dry-run --env dev 1`, Args: cobra.MaximumNArgs(1), RunE: CmdMigrateApplyRun, } // MigrateDiffCmd represents the 'atlas migrate diff' subcommand. MigrateDiffCmd = &cobra.Command{ Use: "diff [flags] [name]", Short: "Compute the diff between the migration directory and a desired state and create a new migration file.", Long: `'atlas migrate diff' uses the dev-database to re-run all migration files in the migration directory, compares it to a given desired state and create a new migration file containing SQL statements to migrate the migration directory state to the desired schema. The desired state can be another connected database or an HCL file.`, Example: ` atlas migrate diff --dev-url mysql://user:pass@localhost:3306/dev --to file://atlas.hcl atlas migrate diff --dev-url mysql://user:pass@localhost:3306/dev --to file://atlas.hcl add_users_table atlas migrate diff --dev-url mysql://user:pass@localhost:3306/dev --to mysql://user:pass@localhost:3306/dbname atlas migrate diff --env dev`, Args: cobra.MaximumNArgs(1), PersistentPreRunE: func(cmd *cobra.Command, _ []string) error { if err := migrateFlagsFromEnv(cmd, nil); err != nil { return err } if !MigrateFlags.Force { dir, err := dir(true) if err != nil { return err } if err := migrate.Validate(dir); err != nil { printChecksumErr(cmd.OutOrStderr()) cmd.SilenceUsage = true return err } } return nil }, RunE: CmdMigrateDiffRun, } // MigrateHashCmd represents the 'atlas migrate hash' command. MigrateHashCmd = &cobra.Command{ Use: "hash", Short: "Hash (re-)creates an integrity hash file for the migration directory.", Long: `'atlas migrate hash' computes the integrity hash sum of the migration directory and stores it in the atlas.sum file. This command should be used whenever a manual change in the migration directory was made.`, Example: ` atlas migrate hash --force`, RunE: CmdMigrateHashRun, } // MigrateNewCmd represents the 'atlas migrate new' command. MigrateNewCmd = &cobra.Command{ Use: "new [name]", Short: "Creates a new empty migration file in the migration directory.", Long: `'atlas migrate new' creates a new migration according to the configured formatter without any statements in it.`, Example: ` atlas migrate new my-new-migration`, Args: cobra.MaximumNArgs(1), RunE: CmdMigrateNewRun, } // MigrateStatusCmd represents the 'atlas migrate status' command. MigrateStatusCmd = &cobra.Command{ Use: "status [flags]", Short: "Get information about the current migration status.", Long: `'atlas migrate status' reports information about the current status of a connected database compared to the migration directory.`, Example: ` atlas migrate status --url mysql://user:pass@localhost:3306/ atlas migrate status --url mysql://user:pass@localhost:3306/ --dir file:///path/to/migration/directory`, RunE: CmdMigrateStatusRun, } // MigrateValidateCmd represents the 'atlas migrate validate' command. MigrateValidateCmd = &cobra.Command{ Use: "validate [flags]", Short: "Validates the migration directories checksum and SQL statements.", Long: `'atlas migrate validate' computes the integrity hash sum of the migration directory and compares it to the atlas.sum file. If there is a mismatch it will be reported. If the --dev-url flag is given, the migration files are executed on the connected database in order to validate SQL semantics.`, Example: ` atlas migrate validate atlas migrate validate --dir file:///path/to/migration/directory atlas migrate validate --dir file:///path/to/migration/directory --dev-url mysql://user:pass@localhost:3306/dev atlas migrate validate --env dev`, RunE: CmdMigrateValidateRun, } // MigrateLintCmd represents the 'atlas migrate Lint' command. MigrateLintCmd = &cobra.Command{ Use: "lint", Short: "Run analysis on the migration directory", Example: ` atlas migrate lint --env dev atlas migrate lint --dir file:///path/to/migration/directory --dev-url mysql://root:pass@localhost:3306 --latest 1 atlas migrate lint --dir file:///path/to/migration/directory --dev-url mysql://root:pass@localhost:3306 --git-base master atlas migrate lint --dir file:///path/to/migration/directory --dev-url mysql://root:pass@localhost:3306 --log '{{ json .Files }}'`, PersistentPreRunE: migrateFlagsFromEnv, RunE: CmdMigrateLintRun, } )
var ( // SchemaFlags are common flags used by schema commands. SchemaFlags struct { URL string Schemas []string Exclude []string // Deprecated: DSN is an alias for URL. DSN string } // ApplyFlags are the flags used in SchemaApply command. ApplyFlags struct { DevURL string Paths []string DryRun bool AutoApprove bool } // CleanFlags are the flags used in SchemaClean command. CleanFlags struct { URL string AutoApprove bool } // SchemaApply represents the 'atlas schema apply' subcommand command. SchemaApply = &cobra.Command{ Use: "apply", Short: "Apply an atlas schema to a target database.", Long: `'atlas schema apply' plans and executes a database migration to bring a given database to the state described in the provided Atlas schema. Before running the migration, Atlas will print the migration plan and prompt the user for approval. The schema is provided by one or more paths (to a file or directory) using the "-f" flag: atlas schema apply -u URL -f file1.hcl -f file2.hcl atlas schema apply -u URL -f schema/ -f override.hcl As a convenience, schemas may also be provided via an environment definition in the project file (see: https://atlasgo.io/cli/projects). If run with the "--dry-run" flag, atlas will exit after printing out the planned migration.`, PreRunE: schemaFlagsFromEnv, RunE: CmdApplyRun, Example: ` atlas schema apply -u "mysql://user:pass@localhost/dbname" -f atlas.hcl atlas schema apply -u "mysql://localhost" -f schema.hcl --schema prod --schema staging atlas schema apply -u "mysql://user:pass@localhost:3306/dbname" -f schema.hcl --dry-run atlas schema apply -u "mariadb://user:pass@localhost:3306/dbname" -f schema.hcl atlas schema apply --url "postgres://user:pass@host:port/dbname?sslmode=disable" -f schema.hcl atlas schema apply -u "sqlite://file:ex1.db?_fk=1" -f schema.hcl`, } // SchemaClean represents the 'atlas schema clean' subcommand. SchemaClean = &cobra.Command{ Use: "clean [flags]", Short: "Removes all objects from the connected database.", Long: `'atlas schema clean' drops all objects in the connected database and leaves it in an empty state. As a safety feature, 'atlas schema clean' will ask for confirmation before attempting to execute any SQL.`, Example: ` atlas schema clean -u mysql://user:pass@localhost:3306/dbname atlas schema clean -u mysql://user:pass@localhost:3306/`, PreRunE: schemaFlagsFromEnv, RunE: CmdCleanRun, } // SchemaInspect represents the 'atlas schema inspect' subcommand. SchemaInspect = &cobra.Command{ Use: "inspect", Short: "Inspect a database and print its schema in Atlas DDL syntax.", Long: `'atlas schema inspect' connects to the given database and inspects its schema. It then prints to the screen the schema of that database in Atlas DDL syntax. This output can be saved to a file, commonly by redirecting the output to a file named with a ".hcl" suffix: atlas schema inspect -u "mysql://user:pass@localhost:3306/dbname" > schema.hcl This file can then be edited and used with the` + " `atlas schema apply` " + `command to plan and execute schema migrations against the given database. In cases where users wish to inspect all multiple schemas in a given database (for instance a MySQL server may contain multiple named databases), omit the relevant part from the url, e.g. "mysql://user:pass@localhost:3306/". To select specific schemas from the databases, users may use the "--schema" (or "-s" shorthand) flag. `, PreRunE: schemaFlagsFromEnv, RunE: CmdInspectRun, Example: ` atlas schema inspect -u "mysql://user:pass@localhost:3306/dbname" atlas schema inspect -u "mariadb://user:pass@localhost:3306/" --schema=schemaA,schemaB -s schemaC atlas schema inspect --url "postgres://user:pass@host:port/dbname?sslmode=disable" atlas schema inspect -u "sqlite://file:ex1.db?_fk=1"`, } // SchemaFmt represents the 'atlas schema fmt' subcommand. SchemaFmt = &cobra.Command{ Use: "fmt [path ...]", Short: "Formats Atlas HCL files", Long: `'atlas schema fmt' formats all ".hcl" files under the given path using canonical HCL layout style as defined by the github.com/hashicorp/hcl/v2/hclwrite package. Unless stated otherwise, the fmt command will use the current directory. After running, the command will print the names of the files it has formatted. If all files in the directory are formatted, no input will be printed out. `, Run: CmdFmtRun, } )
Functions ¶
func CmdApplyRun ¶
CmdApplyRun is the command used when running CLI.
func CmdCleanRun ¶ added in v0.6.5
CmdCleanRun is the command executed when running the CLI with 'schema clean' args.
func CmdFmtRun ¶
CmdFmtRun formats all HCL files in a given directory using canonical HCL formatting rules.
func CmdInspectRun ¶
CmdInspectRun is the command used when running CLI.
func CmdMigrateApplyRun ¶
CmdMigrateApplyRun is the command executed when running the CLI with 'migrate apply' args.
func CmdMigrateDiffRun ¶
CmdMigrateDiffRun is the command executed when running the CLI with 'migrate diff' args.
func CmdMigrateHashRun ¶
CmdMigrateHashRun is the command executed when running the CLI with 'migrate hash' args.
func CmdMigrateLintRun ¶
CmdMigrateLintRun is the command executed when running the CLI with 'migrate lint' args.
func CmdMigrateNewRun ¶
CmdMigrateNewRun is the command executed when running the CLI with 'migrate new' args.
func CmdMigrateStatusRun ¶ added in v0.5.0
CmdMigrateStatusRun is the command executed when running the CLI with 'migrate status' args.
Types ¶
type Env ¶
type Env struct { // Name for this environment. Name string `spec:"name,name"` // URL of the database. URL string `spec:"url"` // URL of the dev-database for this environment. // See: https://atlasgo.io/dev-database DevURL string `spec:"dev"` // List of schemas in this database that are managed by Atlas. Schemas []string `spec:"schemas"` // Exclude defines a list of glob patterns used to filter // resources on inspection. Exclude []string `spec:"exclude"` // Migration containing the migration configuration of the env. Migration *Migration `spec:"migration"` // Lint of the environment. Lint *Lint `spec:"lint"` schemahcl.DefaultExtension }
Env represents an Atlas environment.
type Lint ¶ added in v0.6.5
type Lint struct { // Log configures the --log option. Log string `spec:"log"` // Latest configures the --latest option. Latest int `spec:"latest"` Git struct { // Dir configures the --git-dir option. Dir string `spec:"dir"` // Base configures the --git-base option. Base string `spec:"base"` } `spec:"git"` schemahcl.DefaultExtension }
Lint represents the configuration of migration linting.
type LoadOption ¶
type LoadOption func(*loadConfig)
LoadOption configures the LoadEnv function.
func WithInput ¶
func WithInput(vals map[string]string) LoadOption
WithInput is a LoadOption that sets the input values for the LoadEnv function.
type LogTTY ¶
type LogTTY struct {
// contains filtered or unexported fields
}
LogTTY is a migrate.Logger that pretty prints execution progress. If the connected out is not a tty, it will fall back to a non-colorful output.