GitHub Actions

GitHub Actions is a popular CI/CD product from GitHub. With GitHub Actions, users can easily define workflows that are triggered in various lifecycle events related to a Git repository. For example, many teams configure GitHub actions to run all unit tests in a repository on each change that is committed to a repository.

One of the powerful features of GitHub Actions is its extensibility: it is very easy to package a piece of functionality as a module (called an "action") that can later be re-used by many projects.

Atlas provides a number of GitHub Actions that can be used to automate database schema management tasks.

Action	Use Case
ariga/setup-atlas	Install Atlas from a GitHub Actions workflow
ariga/atlas-action/migrate/push	Push your migration directory to Atlas Cloud (atlasgo.cloud)
ariga/atlas-action/migrate/lint	CI for schema changes
ariga/atlas-action/migrate/apply	Deploy versioned migrations from GitHub Actions
ariga/atlas-action/migrate/down	Revert migrations to a database
ariga/atlas-action/migrate/test	Test migrations on a database
ariga/atlas-action/schema/test	Test schema on a database
ariga/atlas-action/schema/apply	Apply a declarative migrations to a database
ariga/atlas-action/schema/push	Push a schema to Atlas Registry
ariga/atlas-action/schema/plan	Plan a declarative migration for a schema transition
ariga/atlas-action/schema/plan/approve	Approve a declarative migration plan

`ariga/setup-atlas`

The ariga/setup-atlas action can be used to install Atlas from a GitHub Actions workflow.

Usage

.github/workflows/atlas.yaml
name: Deploy schema changes
run-name: I'm using Atlas 🚀
on: [push]
jobs:
  use-atlas:
    runs-on: ubuntu-latest
    steps:
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - run: atlas version
      # - run: atlas schema apply ...

Inputs

cloud-token - (Optional) The Atlas Cloud token to use for authentication. To create a cloud token see the docs.
version - (Optional) The version of the Atlas CLI to install. Defaults to the latest version.

`ariga/atlas-action/migrate/push`

Push the current version of your migration directory to Atlas Cloud.

Usage

name: Push Migrations
on:
  # Run whenever code is changed in the master branch,
  # change this to your main branch.
  push:
    branches:
      - master
jobs:
  push:
    services:
      # Spin up a mysql:8 container to be used as the dev-database.
      mysql:
        image: mysql:8
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - 3306:3306
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/push@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project'
          dev-url: 'mysql://root:pass@localhost:3306/dev'

name: Push Migrations
on:
  # Run whenever code is changed in the master branch,
  # change this to your main branch.
  push:
    branches:
      - master
jobs:
  push:
    services:
      # Spin up a mariadb:11 container to be used as the dev-database.
      maria11:
        image: mariadb:11
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - 3306:3306
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/push@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project'
          dev-url: 'maria://root:pass@localhost:3306/dev'

name: Push Migrations
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
jobs:
  push:
    services:
      # Spin up a postgres:15 container to be used as the dev-database.
      postgres15:
        image: postgres:15
        env:
          POSTGRES_DB: test
          POSTGRES_PASSWORD: pass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/push@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project'
          dev-url: postgres://postgres:pass@localhost:5432/test?sslmode=disable

name: Push Migrations
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
jobs:
  push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/push@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project'
          dev-url: sqlite://file?mode=memory&_fk=1

name: Push Migrations
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
jobs:
  push:
    services:
      # Spin up a SQL Server container to be used as the dev-database.
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_PID: Developer
          MSSQL_SA_PASSWORD: P@ssw0rd0995
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools/bin/sqlcmd -U sa -P P@ssw0rd0995 -Q \"SELECT 1\""
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/push@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project'
          dev-url: sqlserver://sa:P@ssw0rd0995@localhost:1433?database=master

name: Push Migrations
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
jobs:
  push:
    services:
      # Spin up a Clickhouse container to be used as the dev-database.
      clickhouse:
        image: clickhouse/clickhouse-server:23.10
        env:
          CLICKHOUSE_DB: test
          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
          CLICKHOUSE_PASSWORD: pass
          CLICKHOUSE_USER: root
        ports:
          - 9000:9000
        options: >-
          --health-cmd "clickhouse-client --host localhost --query 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/push@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project'
          dev-url: 'clickhouse://root:pass@localhost:9000/test'

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dir - The URL of the migration directory to push. For example: file://migrations. Read more about Atlas URLs.
dir-name - The name (slug) of the project in Atlas Cloud.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
tag - The tag to apply to the pushed migration directory. By default the current git commit hash is used.
latest - Whether to implicitly push the "latest" tag. True by default.
config - The path to the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

url - The URL of the migration directory in Atlas Cloud, containing an ERD visualization of the schema.

`ariga/atlas-action/migrate/lint`

Teams using GitHub that wish to ensure all changes to their database schema are safe can use the atlas-action/migrate/lint GitHub Action.

This action is used for linting migration directories using the atlas migrate lint command. This command validates and analyzes the contents of migration directories and generates insights and diagnostics on the selected changes:

Ensure the migration history can be replayed from any point at time.
Protect from unexpected history changes when concurrent migrations are written to the migration directory by multiple team members. Read more about the consistency checks in the section below.
Detect whether destructive or irreversible changes have been made or whether they are dependent on tables'
contents and can cause a migration failure.

Usage

Add .github/workflows/atlas-ci.yaml to your repo with the following contents:

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  lint:
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - "3306:3306"
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: "mysql://root:pass@localhost:3306/dev"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  lint:
    services:
      # Spin up a maria:11 container to be used as the dev-database for analysis.
      mariadb:
        image: mariadb:11
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - 3306:3306
        options: >-
          --health-cmd "healthcheck.sh --su-mysql --connect --innodb_initialized"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: "maria://root:pass@localhost:3306/dev"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  lint:
    services:
      # Spin up a postgres:15 container to be used as the dev-database for analysis.
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: dev
          POSTGRES_PASSWORD: pass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: postgres://postgres:pass@localhost:5432/dev?sslmode=disable

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: sqlite://file?mode=memory&_fk=1

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  lint:
    services:
      # Spin up a SQL Server container to be used as the dev-database for analysis.
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_PID: Developer
          MSSQL_SA_PASSWORD: P@ssw0rd0995
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools/bin/sqlcmd -U sa -P P@ssw0rd0995 -Q \"SELECT 1\""
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: sqlserver://sa:P@ssw0rd0995@localhost:1433?database=master

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  lint:
    services:
      # Spin up a Clickhouse container to be used as the dev-database for analysis.
      clickhouse:
        image: clickhouse/clickhouse-server:23.10
        env:
          CLICKHOUSE_DB: test
          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
          CLICKHOUSE_PASSWORD: pass
          CLICKHOUSE_USER: root
        ports:
          - 9000:9000
        options: >-
          --health-cmd "clickhouse-client --host localhost --query 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/lint@v1
        with:
          dir: 'file://migrations'
          dir-name: 'my-project' # The name of the project in Atlas Cloud
          dev-url: 'clickhouse://root:pass@localhost:9000/test'

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dir - The URL of the migration directory to lint. For example: file://migrations. Read more about Atlas URLs.
dir-name - The name (slug) of the project in Atlas Cloud.
tag - The tag of migrations to used as base for linting. By default, the latest tag is used.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
config - The path to the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

url - The URL of the CI report in Atlas Cloud, containing an ERD visualization and analysis of the schema migrations.

`ariga/atlas-action/migrate/apply`

You can use ariga/atlas-action/migrate-apply to deploy migrations to your database directly from GitHub Actions.

info

Atlas needs network access to your database to deploy migrations, so make sure your database is either publicly accessible or that you have otherwise enabled network access to it from your GitHub Actions runners.

This action supports two workflows:

Local - the migration directory is checked in to the repository.
Cloud - the migration directory is connected to Atlas Cloud. Runs are reported to your Atlas Cloud account.

Usage

Notice that the following examples rely on a DATABASE_URL secret being set in your repository.

To learn how to set secrets, read GitHub's documentation.

The DATABASE_URL secret should be set to the URL of your database, for examples please see Atlas URL formats.

Local

name: Deploy Database Migrations
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
      - name: Deploy Atlas Migrations
        uses: ariga/atlas-action/migrate/apply@v1
        with:
          url: ${{ secrets.DATABASE_URL }}
          dir: path/to/migrations

Deploy from Cloud

name: Deploy Database Migrations
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
      - name: Deploy Atlas Migrations
        uses: ariga/atlas-action/migrate/apply@v1
        with:
          url: ${{ secrets.DATABASE_URL }}
          dir: atlas://my-project # name (slug) of your project in Atlas Cloud. Add `?tag=<tag>` to deploy a specific tag.

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

url - The URL of the target database. For example: mysql://root:pass@localhost:3306/prod.
dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
dry-run - Print SQL without executing it. Defaults to false
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.
allow-dirty - Allow applying migration on a non-clean database. Defaults to false.

Outputs

current - The current version of the database. (before applying migrations)
target - The target version of the database.
pending_count - The number of migrations that will be applied.
applied_count - The number of migrations that were applied.

`ariga/atlas-action/migrate/down`

Revert migrations to a database.

Usage

Add .github/workflows/atlas-ci.yaml to your repo with the following contents:

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  down:
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - "3306:3306"
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/down@v1
        with:
          dir: my-project
          url: "mysql://root:pass@localhost:3306/example"
          dev-url: "mysql://root:pass@localhost:3306/dev"
          amount: 1

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  down:
    services:
      # Spin up a maria:11 container to be used as the dev-database for analysis.
      mariadb:
        image: mariadb:11
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - 3306:3306
        options: >-
          --health-cmd "healthcheck.sh --su-mysql --connect --innodb_initialized"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/down@v1
        with:
          dir: atlas://my-project
          url: "maria://root:pass@localhost:3306/example"
          dev-url: "maria://root:pass@localhost:3306/dev"
          amount: 1

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  down:
    services:
      # Spin up a postgres:15 container to be used as the dev-database for analysis.
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: dev
          POSTGRES_PASSWORD: pass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/down@v1
        with:
          dir: atlas://my-project
          url: "postgres://postgres:pass@localhost:5432/example?sslmode=disable"
          dev-url: "postgres://postgres:pass@localhost:5432/dev"
          amount: 1

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  down:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/down@v1
        with:
          dir: atlas://my-project
          url: "sqlite://file?mode=memory&_fk=1"
          dev-url: "sqlite://file2?mode=memory&_fk=1"
          amount: 1

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  down:
    services:
      # Spin up a SQL Server container to be used as the dev-database for analysis.
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_PID: Developer
          MSSQL_SA_PASSWORD: P@ssw0rd0995
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools/bin/sqlcmd -U sa -P P@ssw0rd0995 -Q \"SELECT 1\""
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/down@v1
        with:
          dir: atlas://my-project
          url: "sqlserver://sa:P@ssw0rd0995@localhost:1433?database=master"
          dev-url: "sqlserver://sa:P@ssw0rd0995@localhost:1433?database=dev"
          amount: 1

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  down:
    services:
      # Spin up a Clickhouse container to be used as the dev-database for analysis.
      clickhouse:
        image: clickhouse/clickhouse-server:23.10
        env:
          CLICKHOUSE_DB: test
          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
          CLICKHOUSE_PASSWORD: pass
          CLICKHOUSE_USER: root
        ports:
          - 9000:9000
        options: >-
          --health-cmd "clickhouse-client --host localhost --query 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/down@v1
        with:
          dir: atlas://my-project
          url: "clickhouse://root:pass@localhost:9000/test"
          dev-url: "clickhouse://root:pass@localhost:9000/dev"
          amount: 1

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

url - The URL of the target database. For example: mysql://root:pass@localhost:3306/dev.
dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
amount - The amount of applied migrations to revert, defaults to 1.
to-version - To which version to revert.
to-tag - To which tag to revert.
wait-timeout - Time after which no other retry attempt is made and the action exits. If not set, only one attempt is made.
wait-interval - Time in seconds between different migrate down attempts, useful when waiting for plan approval, defaults to 1s.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

`ariga/atlas-action/migrate/test`

Test migrations on a database.

Usage

Add .github/workflows/atlas-ci.yaml to your repo with the following contents:

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - "3306:3306"
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/test@v1
        with:
          dir: file://migrations
          dev-url: mysql://root:pass@localhost:3306/dev
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a maria:11 container to be used as the dev-database for analysis.
      mariadb:
        image: mariadb:11
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - 3306:3306
        options: >-
          --health-cmd "healthcheck.sh --su-mysql --connect --innodb_initialized"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/test@v1
        with:
          dir: file://migrations
          dev-url: maria://root:pass@localhost:3306/dev
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a postgres:15 container to be used as the dev-database for analysis.
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: dev
          POSTGRES_PASSWORD: pass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/test@v1
        with:
          dir: file://migrations
          dev-url: postgres://postgres:pass@localhost:5432/dev
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/test@v1
        with:
          dir: file://migrations
          dev-url: sqlite://file2?mode=memory&_fk=1"
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a SQL Server container to be used as the dev-database for analysis.
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_PID: Developer
          MSSQL_SA_PASSWORD: P@ssw0rd0995
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools/bin/sqlcmd -U sa -P P@ssw0rd0995 -Q \"SELECT 1\""
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/test@v1
        with:
          dir: file://migrations
          dev-url: "sqlserver://sa:P@ssw0rd0995@localhost:1433?database=dev"
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a Clickhouse container to be used as the dev-database for analysis.
      clickhouse:
        image: clickhouse/clickhouse-server:23.10
        env:
          CLICKHOUSE_DB: test
          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
          CLICKHOUSE_PASSWORD: pass
          CLICKHOUSE_USER: root
        ports:
          - 9000:9000
        options: >-
          --health-cmd "clickhouse-client --host localhost --query 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/migrate/test@v1
        with:
          dir: file://migrations
          dev-url: "clickhouse://root:pass@localhost:9000/dev"
          run: "example"

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
dir - The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
run - Filter tests to run by regexp. For example, ^test_.* will only run tests that start with test_. Default is to run all tests.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

`ariga/atlas-action/schema/test`

Test schema on a database.

Usage

Add .github/workflows/atlas-ci.yaml to your repo with the following contents:

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a mysql:8 container to be used as the dev-database for analysis.
      mysql:
        image: mysql:8
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - "3306:3306"
        options: >-
          --health-cmd "mysqladmin ping -ppass"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/test@v1
        with:
          url: file://schema.hcl
          dev-url: mysql://root:pass@localhost:3306/dev
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `migrations/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a maria:11 container to be used as the dev-database for analysis.
      mariadb:
        image: mariadb:11
        env:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
        ports:
          - 3306:3306
        options: >-
          --health-cmd "healthcheck.sh --su-mysql --connect --innodb_initialized"
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 10
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/test@v1
        with:
          url: file://schema.hcl
          dev-url: maria://root:pass@localhost:3306/dev
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a postgres:15 container to be used as the dev-database for analysis.
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: dev
          POSTGRES_PASSWORD: pass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-start-period 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/test@v1
        with:
          url: file://schema.hcl
          dev-url: postgres://postgres:pass@localhost:5432/dev
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/test@v1
        with:
          url: file://schema.hcl
          dev-url: sqlite://file2?mode=memory&_fk=1"
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a SQL Server container to be used as the dev-database for analysis.
      sqlserver:
        image: mcr.microsoft.com/mssql/server:2022-latest
        env:
          ACCEPT_EULA: Y
          MSSQL_PID: Developer
          MSSQL_SA_PASSWORD: P@ssw0rd0995
        ports:
          - 1433:1433
        options: >-
          --health-cmd "/opt/mssql-tools/bin/sqlcmd -U sa -P P@ssw0rd0995 -Q \"SELECT 1\""
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/test@v1
        with:
          url: file://schema.hcl
          dev-url: "sqlserver://sa:P@ssw0rd0995@localhost:1433?database=dev"
          run: "example"

name: Atlas CI
on:
  # Run whenever code is changed in the master branch,
  # change this to your root branch.
  push:
    branches:
      - master
  # Run on PRs where something changed under the `path/to/migration/dir/` directory.
  pull_request:
    paths:
      - 'migrations/*'
jobs:
  test:
    services:
      # Spin up a Clickhouse container to be used as the dev-database for analysis.
      clickhouse:
        image: clickhouse/clickhouse-server:23.10
        env:
          CLICKHOUSE_DB: test
          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
          CLICKHOUSE_PASSWORD: pass
          CLICKHOUSE_USER: root
        ports:
          - 9000:9000
        options: >-
          --health-cmd "clickhouse-client --host localhost --query 'SELECT 1'"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/test@v1
        with:
          url: file://schema.hcl
          dev-url: clickhouse://root:pass@localhost:9000/dev
          run: "example"

Inputs

All inputs are optional as they may be specified in the Atlas configuration file.

dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
url - The desired schema URL(s) to test. For Example: file://schema.hcl
run - Filter tests to run by regexp. For example, ^test_.* will only run tests that start with test_. Default is to run all tests.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

`ariga/atlas-action/schema/apply`

Apply a declarative migrations to a database. See a full example of declarative workflow.

Inputs

to - The URL(s) of the desired schema state.
url - The URL of the target database. For example: mysql://root:pass@localhost:3306/prod.
plan - Optional plan file to use for applying the migrations. For example: atlas://<schema>/plans/<id>.
dry-run - Print SQL (and optional analysis) without executing it. Either true or false. Defaults to false.
auto-approve - Automatically approve and apply changes. Either true or false. Defaults to false.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
schema - The database schema(s). For example: public.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

error - The error message if the action fails.

`ariga/atlas-action/schema/push`

Push a schema to Atlas Registry with an optional tag.

Inputs

schema-name - The name (slug) of the schema repository in Atlas Registry.
url - Desired schema URL(s) to push. For example: file://schema.hcl.
tag - The tag to apply to the pushed schema. By default, the current git commit hash is used.
latest - Whether to implicitly push the latest tag. True by default.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
schema - The database schema(s) to push. For example: public.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

slug - The slug of the schema repository in Atlas Registry.
link - The URL of the schema in Atlas Registry.
url - The URL of the pushed schema version in Atlas format. For example, atlas://app.

`ariga/atlas-action/schema/plan`

Plan a declarative migration for a schema transition.

Inputs

schema-name - The name (slug) of the schema repository in Atlas Registry.
from - URL(s) of the current schema state to transition from.
to - URL(s) of the desired schema state to transition to.
name - Optional name for the plan. If not provided, a default plan is generated by Atlas.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
schema - The database schema(s). For example: public.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

plan - The URL of the generated plan in Atlas format. For example, atlas://app/plans/123.
link - The URL of the plan in Atlas Registry.
status - The status of the plan. For example, PENDING or APPROVED.

`ariga/atlas-action/schema/plan/approve`

Approve a declarative migration plan.

Inputs

schema-name - The name (slug) of the schema repository in Atlas Registry.
from - URL(s) of the current schema state to transition from.
to - URL(s) of the desired schema state to transition to.
plan - Optional URL of the plan to be approved. For example, atlas://<schema>/plans/<id>. By default, Atlas searches in the registry for a plan corresponding to the given schema transition and approves it (typically, this plan is created during the PR stage). If multiple plans are found, an error will be thrown.
dev-url - The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev-databases.
config - The URL of the Atlas configuration file. By default, Atlas will look for a file named atlas.hcl in the current directory. For example, file://config/atlas.hcl. Learn more about Atlas configuration files.
env - The environment to use from the Atlas configuration file. For example, dev.
vars - Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'.
working-directory - The working directory to run from. Defaults to project root.

Outputs

plan - The URL of the generated plan in Atlas format. For example, atlas://app/plans/123.
link - The URL of the plan in Atlas Registry.
status - The status of the plan. For example, PENDING or APPROVED.

ariga/setup-atlas​

Usage​

Inputs​

ariga/atlas-action/migrate/push​

Usage​

Inputs​

Outputs​

ariga/atlas-action/migrate/lint​

Usage​

Inputs​

Outputs​

ariga/atlas-action/migrate/apply​

Usage​

Local​

Deploy from Cloud​

Inputs​

Outputs​

ariga/atlas-action/migrate/down​

Usage​

Inputs​

ariga/atlas-action/migrate/test​

Usage​

Inputs​

ariga/atlas-action/schema/test​

Usage​

Inputs​

ariga/atlas-action/schema/apply​

Inputs​

Outputs​

ariga/atlas-action/schema/push​

Inputs​

Outputs​

ariga/atlas-action/schema/plan​

Inputs​

Outputs​

ariga/atlas-action/schema/plan/approve​

Inputs​

Outputs​

`ariga/setup-atlas`

Usage

Inputs

`ariga/atlas-action/migrate/push`

Usage

Inputs

Outputs

`ariga/atlas-action/migrate/lint`

Usage

Inputs

Outputs

`ariga/atlas-action/migrate/apply`

Usage

Local

Deploy from Cloud

Inputs

Outputs

`ariga/atlas-action/migrate/down`

Usage

Inputs

`ariga/atlas-action/migrate/test`

Usage

Inputs

`ariga/atlas-action/schema/test`

Usage

Inputs

`ariga/atlas-action/schema/apply`

Inputs

Outputs

`ariga/atlas-action/schema/push`

Inputs

Outputs

`ariga/atlas-action/schema/plan`

Inputs

Outputs

`ariga/atlas-action/schema/plan/approve`

Inputs

Outputs