Atlas 官方 Docker 镜像文档

镜像概述与主要用途

本镜像为 Atlas 的官方 Docker 镜像。Atlas 是一款语言无关的数据库 schema 管理与迁移工具，基于现代 DevOps 原则设计，支持通过声明式或版本化工作流管理数据库结构，适用于各类数据库的 schema 生命周期管理。

核心功能与特性

两种核心工作流

• 声明式工作流：类似 Terraform，通过比较数据库当前状态与期望状态（定义于 HCL、SQL 或 ORM schema），自动生成并执行迁移计划，将数据库过渡到目标状态。
• 版本化工作流：自动为用户规划 schema 迁移。用户通过 HCL、SQL 或 ORM 定义目标 schema 后，Atlas 可自动完成迁移计划生成、 lint 校验及应用。

支持的数据库

MySQL、MariaDB、PostgreSQL、SQLite、TiDB、CockroachDB、SQL Server、ClickHouse、Redshift。

使用场景与适用范围

• 声明式场景：需通过基础设施即代码（IaC）方式管理数据库状态，追求状态一致性与可追溯性的场景（如生产环境 schema 变更）。
• 版本化场景：需自动化生成迁移脚本，减少手动编写迁移文件工作量的场景（如开发环境快速迭代、CI/CD 流程集成）。
• 多数据库环境：支持主流关系型与分布式数据库，适用于混合数据库架构的企业级应用。

使用方法与配置说明

拉取镜像

docker pull arigaio/atlas:latest

基本使用

查看命令帮助

docker run --rm -it arigaio/atlas:latest --help

输出示例：

A database toolkit.

Usage:
  atlas [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  license     Display license information
  login       Log in to Atlas Cloud
  logout      Logout from Atlas Cloud
  migrate     Manage versioned migration files
  schema      Work with atlas schemas
  version     Prints this Atlas CLI version information

Flags:
  -h, --help   help for atlas

Use "atlas [command] --help" for more information about a command.

常用命令示例

1. 检查数据库当前 schema（声明式工作流）

通过 schema inspect 命令获取数据库当前 schema：

docker run --rm -it arigaio/atlas:latest \
  schema inspect \
  --url "mysql://user:password@host:port/dbname"

说明：--url 参数指定数据库连接串，格式为 <driver>://<user>:<password>@<host>:<port>/<database>（不同数据库驱动语法略有差异，详见 官方文档）。

2. 生成迁移计划（声明式工作流）

挂载本地 schema 文件（HCL/SQL），生成将数据库迁移至目标状态的计划：

# 本地目录结构：./schema/schema.hcl（定义目标 schema）
docker run --rm -it \
  -v $(pwd)/schema:/schema \  # 挂载本地 schema 目录至容器内 /schema
  arigaio/atlas:latest \
  schema plan \
  --url "mysql://user:password@host:port/dbname" \  # 目标数据库连接串
  -f /schema/schema.hcl  # 指定容器内 schema 文件路径

3. 管理版本化迁移文件（版本化工作流）

初始化迁移目录并生成迁移文件：

# 初始化迁移目录（本地 ./migrations）
docker run --rm -it \
  -v $(pwd)/migrations:/migrations \  # 挂载迁移文件目录
  arigaio/atlas:latest \
  migrate init \
  --dir /migrations \  # 容器内迁移文件目录
  --driver mysql  # 指定数据库驱动

# 根据 schema 变更生成迁移文件
docker run --rm -it \
  -v $(pwd)/migrations:/migrations \
  -v $(pwd)/schema:/schema \
  arigaio/atlas:latest \
  migrate diff \
  --dir /migrations \
  --to /schema/schema.hcl \  # 目标 schema 文件
  --driver mysql \
  --dev-url "mysql://root:pass@dev-mysql:3306/dev_db"  # 开发环境数据库（用于生成迁移）

Docker Compose 配置示例

以下示例通过 Docker Compose 集成 Atlas 与 MySQL，实现本地 schema 管理：

version: '3.8'

services:
  # 目标数据库（MySQL）
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: app_db
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u root", "-prootpass"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Atlas 服务（用于执行 schema 操作）
  atlas:
    image: arigaio/atlas:latest
    volumes:
      - ./schema:/schema        # 挂载本地 schema 目录
      - ./migrations:/migrations  # 挂载迁移文件目录
    depends_on:
      mysql:
        condition: service_healthy
    # 示例命令：生成迁移计划
    command: >
      schema plan 
      --url "mysql://root:rootpass@mysql:3306/app_db" 
      -f /schema/schema.hcl

启动服务并执行命令：

docker-compose up

配置参数说明

学***资源

• 官方文档
• 博客
• GitHub 仓库
• *** 社区