Skip to main content

Automate Database CI/CD with 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.

ActionUse Case
ariga/setup-atlasInstall Atlas from a GitHub Actions workflow
ariga/atlas-action/migrate/pushPush your migration directory to Atlas Cloud (atlasgo.cloud)
ariga/atlas-action/migrate/lintCI for schema changes
ariga/atlas-action/migrate/applyDeploy versioned migrations from GitHub Actions
ariga/atlas-action/migrate/downRevert migrations to a database
ariga/atlas-action/migrate/testTest migrations on a database
ariga/atlas-action/migrate/autorebaseFix atlas.sum conflicts in migration directory
ariga/atlas-action/migrate/diffRun Migrate diff and commit the changes to the migration directory
ariga/atlas-action/schema/testTest schema on a database
ariga/atlas-action/schema/lintLint schema
ariga/atlas-action/schema/applyApply a declarative migrations to a database
ariga/atlas-action/schema/pushPush a schema to Atlas Registry
ariga/atlas-action/schema/planPlan a declarative migration for a schema transition
ariga/atlas-action/schema/plan/approveApprove a declarative migration plan
ariga/atlas-action/monitor/schemaSync the database schema to Atlas Cloud Monitoring
ariga/atlas-action/script/testTest Data Scripts before they run against a real database
ariga/atlas-action/script/pushPush Data Scripts to Atlas Registry
ariga/atlas-action/script/execRun script "exec" transactional mutations on a database
ariga/atlas-action/script/queryRun script "query" reads and reports on a database
ariga/atlas-action/script/loopRun script "loop" batched operations on a database

Offline Access​

ariga/setup-atlas includes built-in grant caching for ~/.atlas and restores it across workflow runs. This ensures Atlas Cloud is not a single point of failure in your GitHub workflow, keeping your pipelines operational even without connectivity to Atlas Cloud.

No additional cache configuration is required beyond using ariga/setup-atlas with cloud-token.

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'

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'

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.
  • tx-mode - The transaction mode for migrations. It can be either file, all, or none. The default is file.

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

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'

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/migrate/autorebase​

Automatically resolves atlas.sum conflicts and rebases the migration directory onto the target branch.

Note

Users should set the migrate/lint action to ensure no logical conflicts occur after this action.

After the rebase is done and a commit is pushed by the action, no other workflows will be triggered unless the action is running with a personal access token (PAT).

  - uses: actions/checkout@v4
    with:
      token: ${{ secrets.PAT }}

Usage​

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

name: Rebase Atlas Migrations
on:
  # Run on push event and not pull request because github action does not run when there is a conflict in the PR.
  push:
    branches-ignore:
      - master
jobs:
  migrate-auto-rebase:
    permissions:
      # Allow pushing changes to repo
      contents: write
    runs-on: ubuntu-latest
    steps:
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: actions/checkout@v4
        with:
          # Use personal access token to trigger workflows after commits are pushed by the action.
          token: ${{ secrets.PAT }}
          # Need to fetch the branch history for rebase.
          fetch-depth: 0
      # Skip the step below if your CI is already configured with a Git account.
      - name: config git to commit changes
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
      - uses: ariga/atlas-action/migrate/autorebase@v1
        with:
          base-branch: master
          dir: file://migrations

Inputs​

dir, to and dev-url are required, but they can be specified in the Atlas configuration file via config and env.

  • dir - The URL of the migration directory. For example: file://migrations.
  • to - The URL of the desired schema state to transition to. For example: file://schema.hcl.
  • 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.
  • remote - The remote to fetch from. Defaults to origin.

ariga/atlas-action/migrate/diff​

Automatically generate versioned migrations whenever the schema is changed, and commit them to the migration directory.

Note

After committing the changes to the migration directory, no other workflows will be triggered unless the action is run with a personal access token (PAT).

  - uses: actions/checkout@v4
    with:
      token: ${{ secrets.PAT }}

Usage​

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

jobs:
  migrate-diff:
    permissions:
      # Allow pushing changes to repo and comments on the pull request
      contents: write
      pull-requests: write
    env:
      GITHUB_TOKEN: ${{ github.token }}
    runs-on: ubuntu-latest
    steps:
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: actions/checkout@v4
        with:
          # Use personal access token to trigger workflows after commits are pushed by the action.
          token: ${{ secrets.PAT }}
          fetch-depth: 0
      # Skip the step below if your CI is already configured with a Git account.
      - name: config git to commit changes
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
      - uses: ariga/atlas-action/migrate/diff@v1
        with:
          dev-url: 'mysql://root:pass@localhost:3306/dev'
          dir: file://migrations
          to: file://schema.sql # The desired schema state to transition to.

Inputs​

dir, to and dev-url are required, but they can be specified in the Atlas configuration file via config and env.

  • dir - The URL of the migration directory. For example: file://migrations.
  • to - The URL of the desired schema state to transition to. For example: file://schema.hcl.
  • 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.
  • remote - The remote to fetch from. Defaults to origin.

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'

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/lint​

Lint a schema to ensure it is valid and follows best practices.

Usage​

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

name: Atlas CI
on:
  # Run on PRs where something changed under the `path/to/schema/dir/` directory.
  pull_request:
    paths:
      - 'schema/*'
permissions:
  contents: read # Required to check out the code
  pull-requests: write # Required to comment on the PR with lint results
jobs:
  schema-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ariga/setup-atlas@v1
        with:
          cloud-token: ${{ secrets.ATLAS_CLOUD_TOKEN }}
      - uses: ariga/atlas-action/schema/lint@v1
        with:
          url: file://schema.hcl
          config: file://config/atlas.hcl
          env: dev

Inputs​

url and dev-url are required, but they can be specified in the Atlas configuration file via config and env.

  • url - The desired schema URL(s) to lint. For Example: file://schema.hcl
  • 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.

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.
  • tx-mode - The transaction mode for migrations. It can be either file, all, or none. The default is file.

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/atlas-action/monitor/schema​

Monitor changes of the database schema and track them in Atlas Cloud. Can be used periodically to monitor changes in the database schema.

Inputs​

  • cloud-token - (required) The Atlas Cloud token to use for authentication. To create a cloud token see the docs.
  • url - (optional) The URL of the database to monitor. For example: mysql://root:pass@localhost:3306/prod (mutually exclusive with config and env).
  • config - (optional) 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 (mutually exclusive with url).
  • env - (optional) The environment to use from the Atlas configuration file. For example, dev (mutually exclusive with url).
  • slug - (optional) Unique identifier for the database server.
  • schemas - (optional) List of database schemas to include (by default includes all schemas). see.
  • exclude - (optional) List of exclude patterns from inspection. see.
  • include - (optional) List of include patterns from inspection. see.
  • collect-stats - (optional) Collect table statistics. Defaults to true.

Outputs​

  • url - URL of the schema of the database inside Atlas Cloud.

Data Scripts Actions​

Data Scripts define data operations as code: transactional mutations (script "exec"), reads and reports (script "query"), and batched work (script "loop"). The actions below let you test scripts on pull requests, publish them to the Atlas Registry, and run them from a workflow, either on a schedule or on demand with workflow_dispatch.

Atlas Pro Feature

Data Scripts are available to Atlas Pro users that purchased Atlas Pipelines. Set the cloud-token input of ariga/setup-atlas to log in before using the actions below.

All five actions accept files (or paths, for script/test) pointing at the script source, and can instead read it from the selected environment in your Atlas configuration file, via the config and env inputs:

atlas.hcl
env "prod" {
  url = getenv("DATABASE_URL")
  script {
    src = "file://scripts"
    repo {
      name = "my-scripts"
    }
  }
  test {
    script {
      src = ["scripts.test.hcl"]
    }
  }
}

ariga/atlas-action/script/test​

Run tests for your Data Scripts. Use it on pull requests to verify a script's effect on the database, its expected failures, and the permissions it runs under, before it ever touches production data.

Usage​

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

name: Test Data Scripts
on:
  pull_request:
    paths:
      - 'scripts/**'
      - 'atlas.hcl'
jobs:
  script-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/script/test@v1
        with:
          paths: file://scripts
          dev-url: 'docker://postgres/15/dev'

Inputs​

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

  • paths - List of directories containing test files.
  • run - Filter tests to run by regexp. For example, ^test_.* will only run tests that start with test_. Default is to run all tests.
  • 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.

ariga/atlas-action/script/push​

Push your Data Scripts to the Atlas Registry. Once pushed, workflows and deployment tools can run them by name with an atlas://<name> URL, instead of checking the script source out on every runner.

Usage​

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

name: Push Data Scripts
on:
  # Run whenever scripts are changed in the master branch,
  # change this to your main branch.
  push:
    branches:
      - master
    paths:
      - 'scripts/**'
jobs:
  script-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/script/push@v1
        id: push
        with:
          script-name: my-scripts
          files: file://scripts
      - run: echo "Pushed ${{ steps.push.outputs.files }} file(s) to ${{ steps.push.outputs.link }}"

Inputs​

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

  • script-name - The name (slug) of the script repository in Atlas Registry. Can also be set with env.script.repo.name in the configuration file.
  • files - URL(s) of the script files or directories to push. For example: file://scripts. If not set, Atlas uses the scripts defined in the Atlas configuration file.
  • 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​

  • files - The number of script files that were pushed.
  • link - Link to the scripts in Atlas Registry.
  • name - The name of the script repository that was pushed to.

ariga/atlas-action/script/exec​

Execute script "exec" transactional mutations, such as a backfill, an archive, or a GDPR erasure, on a target database. The statements of each script run in a single transaction, guarded by its condition, assert, and check blocks, and a failing guard rolls the whole batch back.

The action fails if the run fails, or if any script in it fails, including a failed assert or check. An unmet condition stops its script gracefully and is not treated as a failure.

info

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

Usage​

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

name: Erase User Data
on:
  # Run this script on demand, with the user to erase as an input.
  workflow_dispatch:
    inputs:
      user_id:
        description: The ID of the user to erase.
        required: true
jobs:
  script-exec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/script/exec@v1
        id: exec
        with:
          url: ${{ secrets.DATABASE_URL }}
          files: file://scripts
          # Anchor the pattern, otherwise `erase_user` also selects `erase_user_v2`.
          match: '^erase_user$'
          vars: '{"user_id": "${{ inputs.user_id }}"}'
      - run: echo "${{ steps.exec.outputs.output }}"

Instead of checking the scripts out, point files at a repository pushed to the registry, for example files: atlas://my-scripts.

Inputs​

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

  • url - The URL of the target database to run the scripts against. For example: mysql://root:pass@localhost:3306/prod.
  • files - URL(s) of the script files or directories to run. For example: file://scripts. If not set, Atlas uses the scripts defined in the Atlas configuration file.
  • match - Run only the scripts matching the given regexp. For example, ^purge_.* will only run scripts that start with purge_. Default is to run all scripts. Note that the pattern is not anchored, and that a pattern matching nothing runs no scripts and succeeds.
  • 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​

  • output - The output of the executed scripts, joined by newlines. It contains the values emitted by their output blocks and the results of their query blocks.
  • report - A JSON report of the run, containing the result of each executed script.

ariga/atlas-action/script/query​

Run script "query" scripts on a target database and collect what they print. Use it for scheduled reports and data-health checks, with sensitive columns masked before they leave Atlas.

Usage​

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

name: Daily Data Report
on:
  schedule:
    - cron: '0 6 * * *'
  workflow_dispatch:
jobs:
  script-query:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/script/query@v1
        id: query
        with:
          url: ${{ secrets.DATABASE_URL }}
          files: file://scripts
          match: '^data_health$'
      - name: Add the report to the job summary
        run: |
          echo '${{ steps.query.outputs.output }}' >> $GITHUB_STEP_SUMMARY

Inputs​

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

  • url - The URL of the target database to run the scripts against. For example: mysql://root:pass@localhost:3306/prod.
  • files - URL(s) of the script files or directories to run. For example: file://scripts. If not set, Atlas uses the scripts defined in the Atlas configuration file.
  • match - Run only the scripts matching the given regexp. For example, ^report_.* will only run scripts that start with report_. Default is to run all scripts.
  • 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​

  • output - The output of the executed scripts, joined by newlines. It contains the values emitted by their output blocks and the results of their query blocks.
  • report - A JSON report of the run, containing the result of each executed script.

ariga/atlas-action/script/loop​

Run script "loop" scripts, which process rows in batches, on a target database. Each iteration runs in its own transaction, so a long purge or backfill makes progress without holding a single, long-lived transaction open.

Usage​

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

name: Purge Inactive Users
on:
  schedule:
    - cron: '0 3 * * 0'
  workflow_dispatch:
jobs:
  script-loop:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ariga/setup-atlas@v0
        with:
          cloud-token: ${{ secrets.ATLAS_TOKEN }}
      - uses: ariga/atlas-action/script/loop@v1
        id: loop
        with:
          url: ${{ secrets.DATABASE_URL }}
          files: file://scripts
          match: '^purge_inactive$'
      - run: echo "${{ steps.loop.outputs.output }}"

Long-running purges may exceed the GitHub Actions job timeout. Bound the work each run does with the loop's batch size and limits, and let the schedule pick the rest up on the next run.

Inputs​

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

  • url - The URL of the target database to run the scripts against. For example: mysql://root:pass@localhost:3306/prod.
  • files - URL(s) of the script files or directories to run. For example: file://scripts. If not set, Atlas uses the scripts defined in the Atlas configuration file.
  • match - Run only the scripts matching the given regexp. For example, ^purge_.* will only run scripts that start with purge_. Default is to run all scripts.
  • 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​

  • output - The output of the executed scripts, joined by newlines. It contains the values emitted by their output blocks and the results of their query blocks.
  • report - A JSON report of the run, containing the result of each executed script.