Documentation
¶
Overview ¶
Package atlas integrates the ariga.io/atlas migration engine with an implementation of the migration.Migrator interface.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithAtlas ¶
WithAtlas returns a configuration Option that registers the AtlasMigrator with the EmberKit instance.
This option creates an AtlasMigrator instance using the HCL path specified by WithAtlasHCLPath (or the default "atlas.hcl" if WithAtlasHCLPath is not used). A temporary Nop logger is used during this initial setup; the actual logger configured in the EmberKit instance will be passed to the migrator's Apply method during runtime.
Returns:
A config.Option function to be passed to emberkit.New().
WithAtlas configures the EmberKit to use Atlas for migrations. It uses the HCL path specified by WithAtlasHCLPath (or the default "atlas.hcl"). The logger passed to NewAtlasMigrator here is temporary; the actual logger from the EmberKit instance will be used during the Apply phase.
func WithAtlasHCLPath ¶
WithAtlasHCLPath returns a configuration Option that specifies a custom path for the atlas.hcl configuration file.
This path is used by the AtlasMigrator (configured via WithAtlas) to locate the migration settings and directory. If this option is not used, the migrator defaults to looking for "atlas.hcl" in the working directory.
Parameters:
path: The custom path to the atlas.hcl file.
Returns:
A config.Option function to be passed to emberkit.New().
WithAtlasHCLPath specifies the path to the atlas.hcl configuration file. This is used by the WithAtlas option to set up the migrator. It allows the user to specify a custom path for the HCL file. If not set, the default path "atlas.hcl" will be used.
Types ¶
type AtlasMigrator ¶
type AtlasMigrator struct {
// contains filtered or unexported fields
}
AtlasMigrator implements the migration.Migrator interface using the Atlas engine. It manages the state required to find and apply database migrations defined in an Atlas project (typically configured via an atlas.hcl file).
Initialization is performed lazily using sync.Once when the Apply method is first called. This involves parsing the HCL file, locating the migration directory specified for the 'local' environment (or falling back to the first defined environment), and preparing the Atlas migration directory object.
Fields:
hclPath: The file path to the atlas.hcl configuration file.
migrateDir: The Atlas migrate.Dir object representing the migration source directory.
Populated during lazy initialization.
dirPath: The resolved absolute file path to the migration source directory.
Populated during lazy initialization.
dirURL: The file URL (e.g., "file://...") of the migration source directory.
Populated during lazy initialization.
logger: A *zap.Logger instance used for logging migrator activities.
It includes the base logger provided during creation plus migrator-specific context.
initErr: Stores any error encountered during the lazy initialization process.
Checked within Apply to determine if migrations can proceed.
once: Ensures the initialization logic (initialise method) runs exactly once.
AtlasMigrator implements migration.Migrator backed by Atlas.
func NewAtlasMigrator ¶
func NewAtlasMigrator(hclPath string, log *zap.Logger) *AtlasMigrator
NewAtlasMigrator builds a lazily‑initialised migrator. NewAtlasMigrator creates a new, lazily-initialized AtlasMigrator instance. It requires the path to the atlas.hcl configuration file and a base logger. The migrator's core initialization (reading HCL, finding migration directory) is deferred until the Apply method is first called.
Parameters:
hclPath: Path to the atlas.hcl configuration file. log: A base *zap.Logger. The migrator creates a child logger with context.
Returns:
A pointer to the newly created AtlasMigrator.
func (*AtlasMigrator) Apply ¶
Apply satisfies migration.Migrator. Apply executes pending database migrations found in the configured migration directory. It implements the migration.Migrator interface.
This method handles the full migration lifecycle: 1. Ensures the migrator is initialized (reading HCL, locating migration dir). 2. Skips migrations if initialization failed or no directory is configured (logs warning). 3. Opens a database connection using the provided pool's DSN. 4. Creates an Atlas migration executor. 5. Executes all pending migrations (or logs if none are pending).
A 90-second timeout is applied to the Atlas driver operations within this method.
Parameters:
ctx: Context for cancellation and deadlines. pool: The *pgxpool.Pool to use for database operations. l: An optional *zap.Logger for adding call-specific context to logs.
Returns:
An error if initialization, database connection, or migration execution fails. Returns nil if migrations are applied successfully or if they are skipped due to incomplete initialization.
Source Files