Skip to main content

CircleCI Orbs

CircleCI Orbs are reusable packages of CircleCI configuration that can be shared across projects. They provide a way to simplify your CircleCI configuration by encapsulating common tasks into a single line of code.

Atlas provides a number of Orbs to help you integrate Atlas into your CircleCI workflows.

ActionUse Case
atlas-orb/setupInstall Atlas and authenticate with Atlas Cloud
atlas-orb/migrate_pushPush your migration directory to Atlas Cloud (atlasgo.cloud)
atlas-orb/migrate_lintLint migration changes with Atlas (Required atlas login)
atlas-orb/migrate_applyApply migrations to a database
atlas-orb/migrate_downRevert migrations to a database.

atlas-orb/setup​

The atlas-orb/setup action can be used to install the Atlas CLI and authenticate with Atlas Cloud.

Usage​

.circleci/config.yml
version: 2.1
orbs:
  atlas-orb: ariga/atlas-orb@0.0.6
jobs:
  push-dir:
    environment:
      # Define those envs in CircleCI context to keep them secure
      ATLAS_TOKEN: "your-atlas-token"
    steps:
      - checkout
      - atlas-orb/setup:
          version: "latest"
workflows:
  use-atlas:
    jobs:
      - push-dir

Inputs​

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

atlas-orb/migrate_push​

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

Usage​

version: 2.1
orbs:
  atlas-orb: ariga/atlas-orb@0.0.6
jobs:
  push-dir:
    docker:
      - image: cimg/base:current
      - image: cimg/mysql:8
        environment:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
    environment:
      # Define those envs in CircleCI context to keep them secure
      ATLAS_TOKEN: "your-atlas-token"
    steps:
      - checkout
      - run:
          name: Wait for MySQL
          command: dockerize -wait tcp://127.0.0.1:3306 -timeout 60s
      - atlas-orb/setup:
          version: "latest"
      - atlas-orb/migrate_push:
          dir_name: my-project
          dev_url: "mysql://root:pass@localhost:3306/dev"
workflows:
  use-atlas:
    jobs:
      - push-dir

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.
  • 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 - Extra variables to pass to the Atlas configuration file. For example, key=value key2=values.
  • working_directory - The working directory to run from. Defaults to project root.

atlas-orb/migrate_lint (Required atlas login)​

Teams using CircleCI that wish to ensure all changes to their database schema are safe can use the atlas-orb/migrate_lint CircleCI Orb.

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 .circleci/config.yml to your repo with the following contents:

version: 2.1
orbs:
  atlas-orb: ariga/atlas-orb@0.0.6
jobs:
  push-dir:
    docker:
      - image: cimg/base:current
      - image: cimg/mysql:8
        environment:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
    environment:
      # Define those envs in CircleCI context to keep them secure
      ATLAS_TOKEN: "your-atlas-token"
      GITHUB_TOKEN: "your-github-token"
      GITHUB_REPOSITORY: "your-repo-name" # for example, "ariga/atlas-orb"
    steps:
      - checkout
      - run:
          name: Wait for MySQL
          command: dockerize -wait tcp://127.0.0.1:3306 -timeout 60s
      - atlas-orb/setup:
          version: "latest"
      - atlas-orb/migrate_lint:
          dir_name: my-project
          dev_url: "mysql://root:pass@localhost:3306/dev"
workflows:
  use-atlas:
    jobs:
      - push-dir

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.
  • 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 - Extra variables to pass to the Atlas configuration file. For example, key=value key2=values.
  • working_directory - The working directory to run from. Defaults to project root.
  • github_token_env - Specify the environment variable name that contains the GitHub token. Defaults to GITHUB_TOKEN environment variable.
  • github_repository_env - Specify the environment variable name that contains the GitHub repository name in the format owner/repo. Defaults to GITHUB_REPOSITORY environment variable.
note

The GITHUB_TOKEN and GITHUB_REPOSITORY environment variables are required for the atlas-orb/migrate_lint action to work. These variables are used to post lint results to the GitHub Pull Request as comments. If you want to use a different environment variable name, you can specify it using the github_token_env and github_repository_env inputs

atlas-orb/migrate_apply​

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

Usage​

version: 2.1
orbs:
  atlas-orb: ariga/atlas-orb@0.0.6
jobs:
  push-dir:
    docker:
      - image: cimg/base:current
      - image: cimg/mysql:8
        environment:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
    environment:
      # Define those envs in CircleCI context to keep them secure
      ATLAS_TOKEN: "your-atlas-token"
    steps:
      - checkout
      - run:
          name: Wait for MySQL
          command: dockerize -wait tcp://127.0.0.1:3306 -timeout 60s
      - atlas-orb/setup:
          version: "latest"
      - atlas-orb/migrate_apply:
          dir: my-project
          url: "mysql://root:pass@localhost:3306/dev"
workflows:
  use-atlas:
    jobs:
      - push-dir

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 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.
  • dry_run - Print SQL without executing it. Defaults to false.
  • vars - Extra variables to pass to the Atlas configuration file. For example, key=value key2=values.
  • working_directory - The working directory to run from. Defaults to project root.

atlas-orb/migrate_down​

Revert migrations to a database.

Usage​

version: 2.1
orbs:
  atlas-orb: ariga/atlas-orb@0.0.6
jobs:
  push-dir:
    docker:
      - image: cimg/base:current
      - image: cimg/mysql:8
        environment:
          MYSQL_DATABASE: dev
          MYSQL_ROOT_PASSWORD: pass
    environment:
      # Define those envs in CircleCI context to keep them secure
      ATLAS_TOKEN: "your-atlas-token"
    steps:
      - checkout
      - run:
          name: Wait for MySQL
          command: dockerize -wait tcp://127.0.0.1:3306 -timeout 60s
      - atlas-orb/setup:
          version: "latest"
      - atlas-orb/migrate_down:
          dir: my-project
          url: "mysql://root:pass@localhost:3306/example"
          dev_url: "mysql://root:pass@localhost:3306/dev"
          amount: 1
workflows:
  use-atlas:
    jobs:
      - push-dir

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 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.
  • amount - The number of 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 - Extra variables to pass to the Atlas configuration file. For example, key=value key2=values.
  • working_directory - The working directory to run from. Defaults to project root.