> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# ariga/atlas-orb

CircleCI Orb for https://atlasgo.io


## Commands

### migrate_apply

This command apply migrations to a database.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dir` | string |  | The URL of the migration directory to lint. For example: file://migrations.
Read more about [Atlas URLs](https://atlasgo.io/concepts/url)
 |
| `dry_run` | boolean | false | Print SQL without executing it. Defaults to `false`
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `url` | string |  | The URL of the target database. For example: `mysql://root:pass@localhost:3306/dev`.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### migrate_auto_rebase

This command rebases migrations to a database.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `base_branch` | string | main | The base branch to rebase the migration directory onto. Default to the default branch of the repository.
 |
| `dir` | string | file://migrations | The URL of the migration directory to rebase on. By default: `file://migrations`.
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### migrate_down

Revert migrations to a database.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `amount` | integer | 1 | The number of migrations to revert. Defaults to 1.
 |
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `dir` | string |  | The URL of the migration directory to push. For example: file://migrations.
Read more about [Atlas URLs](https://atlasgo.io/concepts/url)
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `github_repo_env` | env_var_name | GITHUB_REPOSITORY | The repository name that linting results will be posted to.
 |
| `github_token_env` | env_var_name | GITHUB_TOKEN | Environment variable containing the GitHub token.
If provided, the command will authenticate to GitHub.
(e.g. `GITHUB_TOKEN`)
 |
| `to_tag` | string |  | To which tag to revert.
 |
| `to_version` | string |  | To which version to revert.
 |
| `url` | string |  | The URL of the target database. For example: `mysql://root:pass@localhost:3306/dev`.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `wait_interval` | string | 1s | Time in seconds between different migrate down attempts, useful when waiting for plan approval, defaults to 1s.
 |
| `wait_timeout` | string |  | Time after which no other retry attempt is made and the action exits. If not set, only one attempt is made.
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### migrate_lint

This command lints the migration directory before pushing to Atlas Cloud.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `dir` | string |  | The URL of the migration directory to lint. For example: file://migrations.
Read more about [Atlas URLs](https://atlasgo.io/concepts/url)
 |
| `dir_name` | string |  | The name (slug) of the project in Atlas Cloud.
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `github_repo_env` | env_var_name | GITHUB_REPOSITORY | The repository name that linting results will be posted to.
 |
| `github_token_env` | env_var_name | GITHUB_TOKEN | Environment variable containing the GitHub token.
If provided, the command will authenticate to GitHub.
(e.g. `GITHUB_TOKEN`)
 |
| `tag` | string |  | The tag of migrations to used as base for linting. By default, the `latest` tag is used.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### migrate_push

This command push the migrations directory to the Atlas Cloud.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `dir` | string |  | The URL of the migration directory to push. For example: file://migrations.
Read more about [Atlas URLs](https://atlasgo.io/concepts/url)
 |
| `dir_name` | string |  | The name (slug) of the project in Atlas Cloud.
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `github_repo_env` | env_var_name | GITHUB_REPOSITORY | The repository name that linting results will be posted to.
 |
| `github_token_env` | env_var_name | GITHUB_TOKEN | Environment variable containing the GitHub token.
If provided, the command will authenticate to GitHub.
(e.g. `GITHUB_TOKEN`)
 |
| `tag` | string |  | The tag to apply to the pushed migration directory. By default the current git commit hash is used.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### migrate_test

This command test migrations on a database.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `dir` | string |  | The URL of the migration directory to test. For example: file://migrations.
Read more about [Atlas URLs](https://atlasgo.io/concepts/url)
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `run` | string |  | Filter tests to run by regexp. For example, `^test_.*` will only run tests that start with `test_`. Default is to run all tests.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### monitor_schema

Sync the database schema to Atlas Cloud


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cloud_token_env` | env_var_name | ATLAS_TOKEN | Environment variable containing the Atlas Cloud token.
If provided, the command will authenticate to Atlas Cloud.
(e.g. `ATLAS_TOKEN`)
 |
| `config` | string |  | The URL of the Atlas configuration file (mutually exclusive with `url`). For example, `file://config/atlas.hcl`, learn more about [Atlas configuration files](https://atlasgo.io/atlas-schema/projects). |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev` (mutually exclusive with `url`). |
| `exclude` | string |  | List of exclude patterns from inspection. See: https://atlasgo.io/declarative/inspect#exclude-schemas |
| `schemas` | string |  | List of database schemas to include (by default includes all schemas). See: https://atlasgo.io/declarative/inspect#inspect-multiple-schemas |
| `slug` | string |  | Optional unique identifier for the database server. |
| `url` | string |  | URL of the database to sync (mutually exclusive with `config` and `env`). |
| `working_directory` | string | . | Atlas working directory, default is project root |

### schema_apply

Apply a declarative migrations to a database.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto_approve` | boolean | false | Automatically approve and apply changes. Either `true` or `false`. Defaults to `false`.
 |
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `dry_run` | boolean | false | Print SQL (and optional analysis) without executing it. Either `true` or `false`. Defaults to `false`.
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `plan` | string |  | Optional plan file to use for applying the migrations. For example: `atlas://<schema>/plans/<id>`.
 |
| `to` | string |  | The URL(s) of the desired schema state.
 |
| `url` | string |  | The URL of the target database. For example: `mysql://root:pass@localhost:3306/prod`.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### schema_plan

Plan a declarative migration for a schema transition.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `from` | string |  | URL(s) of the current schema state to transition from.
 |
| `github_repo_env` | env_var_name | GITHUB_REPOSITORY | The repository name that linting results will be posted to.
 |
| `github_token_env` | env_var_name | GITHUB_TOKEN | Environment variable containing the GitHub token.
If provided, the command will authenticate to GitHub.
(e.g. `GITHUB_TOKEN`)
 |
| `plan_name` | string |  | Optional name for the plan. If not provided, a default plan is generated by Atlas.
 |
| `schema_name` | string |  | The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
 |
| `to` | string |  | URL(s) of the desired schema state to transition to.
 |
| `vars` | string |  | Extra variables to pass to the Atlas configuration file. For example, `key=value`.
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### schema_plan_approve

Approve a declarative migration plan.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `from` | string |  | URL(s) of the current schema state to transition from.
 |
| `github_repo_env` | env_var_name | GITHUB_REPOSITORY | The repository name that linting results will be posted to.
 |
| `github_token_env` | env_var_name | GITHUB_TOKEN | Environment variable containing the GitHub token.
If provided, the command will authenticate to GitHub.
(e.g. `GITHUB_TOKEN`)
 |
| `plan` | string |  | 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.
 |
| `schema_name` | string |  | The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
 |
| `to` | string |  | URL(s) of the desired schema state to transition to.
 |
| `vars` | string |  | Extra variables to pass to the Atlas configuration file. For example, `key=value`.
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### schema_push

Push a schema to [Atlas Registry](https://atlasgo.io/registry) with an optional tag.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `latest` | boolean | false | If true, the pushed schema will be tagged as `latest`.
 |
| `schema_name` | string |  | The name (slug) of the schema repository in [Atlas Registry](https://atlasgo.io/registry).
 |
| `tag` | string |  | The tag to apply to the pushed schema. By default, the current git commit hash is used.
 |
| `url` | string |  | Desired schema URL(s) to push. For example: `file://schema.hcl`.
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### schema_test

This command test schema on a database.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `config` | string |  | 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](https://atlasgo.io/atlas-schema/projects).
 |
| `dev_url` | string |  | The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev.
Read more about [dev-databases](https://atlasgo.io/concepts/dev-database).
 |
| `env` | string |  | The environment to use from the Atlas configuration file. For example, `dev`.
 |
| `run` | string |  | Filter tests to run by regexp. For example, `^test_.*` will only run tests that start with `test_`. Default is to run all tests.
 |
| `url` | string |  | The desired schema URL(s) to test. For Example: `file://schema.hcl`
 |
| `vars` | string |  | Stringify JSON object containing variables to be used inside the Atlas configuration file. For example: '{"var1": "value1", "var2": "value2"}'
 |
| `working_directory` | string | . | The working directory to run from. Defaults to project root.
 |

### setup

This command will install the Atlas CLI and authenticate to Atlas Cloud if a cloud token is provided. This command require curl to be installed on the machine.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cloud_token_env` | env_var_name | ATLAS_TOKEN | Environment variable containing the Atlas Cloud token.
If provided, the command will authenticate to Atlas Cloud.
(e.g. `ATLAS_TOKEN`)
 |
| `version` | string | latest | Which version of Atlas to install, in the format of "v0.14.1" |

## Executors

### default

This executor is the default executor for the Atlas orb.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Configure the executor resource class |
| `tag` | string | current | Pick a specific cimg/base image variant: https://hub.docker.com/r/cimg/base/tags
 |

## Examples

### example

This example workflow demonstrates how to use the Atlas orb to push a migrations directory of PostgreSQL database to the Atlas Cloud.


```yaml
version: '2.1'
orbs:
  atlas-orb: ariga/atlas-orb@0.0.6
jobs:
  push-dir:
    docker:
      - image: cimg/base:current
      - environment:
          POSTGRES_DB: postgres
          POSTGRES_PASSWORD: pass
          POSTGRES_USER: postgres
        image: cimg/postgres:16.2
    steps:
      - checkout
      - atlas-orb/setup:
          cloud_token_env: ATLAS_TOKEN
          version: latest
      - atlas-orb/migrate_lint:
          dev_url: postgres://postgres:pass@localhost:5432/postgres?sslmode=disable
          dir_name: my-cool-project
          github_repo_env: GITHUB_REPOSITORY
          github_token_env: GITHUB_TOKEN
      - atlas-orb/migrate_push:
          dev_url: postgres://postgres:pass@localhost:5432/postgres?sslmode=disable
          dir_name: my-cool-project
workflows:
  postgres-example:
    jobs:
      - push-dir:
          context: the-context-has-ATLAS_TOKEN
```