Skip to main content

Automate Database CI/CD with GitLab Pipelines

GitLab CI is an automation tool integrated into GitLab that helps streamline code testing, building, and deployment through configurable pipelines. Using a .gitlab-ci.yml file, developers define jobs and stages that GitLab executes automatically, enabling consistent integration and delivery workflows.

Atlas provides CI/CD components for easy integration in any project. Click here to see the full list of components in the CI/CD catalog.

Check out this guide for full examples of the versioned and declarative flows using the GitLab components.

info

To use the components in a self-hosted instance, you must mirror the component project.

migrate-push​

Pushes a migration directory to the cloud.

Usage​

services:
    - mysql:latest

variables:
    MYSQL_DATABASE: dev
    MYSQL_ROOT_PASSWORD: pass

stages:
    - push

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-push@~latest
    inputs:
      stage: push
      branches:
        - main
      dir: "file://migrations"
      dir-name: "my-project"
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • working-directory - (Optional) Atlas working directory, default is project root
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) 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 lint. For example: file://migrations. Read more about Atlas URLs here: https://atlasgo.io/concepts/url.
  • dir-name - (Optional) The name (slug) of the project in Atlas Cloud.
  • tag - (Optional) The tag to apply to the pushed migration directory. By default the current git commit hash is used.
  • latest - (Optional) If true, push also the "latest" tag.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.

migrate-lint​

Use this component to lint new migration files in any merge request.

Usage​

services:
    - mysql:latest

variables:
    MYSQL_DATABASE: dev
    MYSQL_ROOT_PASSWORD: pass

stages:
    - lint

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-lint@~latest
    inputs:
      stage: lint
      dir: "file://migrations"
      dir-name: "my-project"
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root.
  • stage - (Optional) The CI stage to run the job in.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about here.
  • dir - (Optional) The URL of the migration directory to lint. For example: file://migrations. Read more about Atlas URLs here: https://atlasgo.io/concepts/url.
  • dir-name: The name (slug) of the project in Atlas Cloud.
  • atlas-cloud-token- (Optional) A token for Atlas Cloud.
  • atlas-version: The version of Atlas to install.
  • gitlab-token- (Optional) A GitLab access token for posting merge request comments.

migrate-apply​

Use this component to deploy migration files to your database directly from your CI runner. You can either deploy a local directory (i.e from your git repository) or a directory stored in Atlas Cloud.

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 running this component from a runner that has network access to your database.

Usage​

Deploy a directory from the git repository​

stages:
    - apply

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-apply@~latest
    inputs:
      stage: apply
      branches:
        - main
      dir: "file://migrations"
      url: $DATABASE_URL

Deploy a directory from the cloud​

stages:
    - apply

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-apply@~latest
    inputs:
      stage: apply
      branches:
        - main
      dir: "atlas://my-project"
      url: $DATABASE_URL
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • url - (Optional) The URL of the target database to apply changes to. 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.
  • dry-run - (Optional) If true, print SQL without executing it.
  • revisions-schema - (Optional) The name of the schema containing the revisions table.
  • atlas-cloud-token - (Optional) A token for Atlas Cloud.
  • atlas-version - Install a specific Atlas version.

migrate-diff​

Use this component to automatically generate versioned migrations whenever the schema is changed, and commit them to the migration directory.

Usage​

stages:
    - diff

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/migrate-diff@~latest
    inputs:
      stage: migrate-diff
      dir: "file://migrations"
      to: "file://schema.hcl"
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN
      gitlab-token: $GITLAB_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • dir - (Optional) The URL of the migration directory to apply. For example: atlas://dir-name for cloud based directories or file://migrations for local ones.
  • to - (Optional) The URL of the desired schema state to transition to. For example: file://schema.hcl.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about here.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • remote - (Optional) The remote to push changes to. Defaults to origin.
  • gitlab-token - A Gitlab access token to push changes to the remote.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.

schema-plan​

Creates a plan for a declarative schema change. Read more about pre-planning schema changes here.

To enable Atlas comments on merge requests, you need create an access token with appropriate role and permissions, set it as a CI/CD variable and pass it to the component in the "gitlab-token" input. See the usage example below:

Usage​

services:
    - mysql:latest

variables:
    MYSQL_DATABASE: dev
    MYSQL_ROOT_PASSWORD: pass

stages:
    - plan

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-plan@~latest
    inputs:
      stage: plan
      env: dev
      dev-url: "mysql://root:pass@mysql:3306/dev"
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN
      gitlab-token: $GITLAB_TOKEN

Inputs​

  • stage - (Optional) The CI stage to run the job in.
  • working-directory - (Optional) Atlas working directory, default is project root
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) 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 lint. For example: file://migrations. Read more about Atlas URLs here: https://atlasgo.io/concepts/url.
  • dir-name - (Optional) The name (slug) of the project in Atlas Cloud.
  • tag - (Optional) The tag to apply to the pushed migration directory. By default the current git commit hash is used.
  • latest - (Optional) If true, push also the "latest" tag.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.
  • gitlab-token- (Optional) A GitLab access token for posting merge request comments.

schema-plan-approve​

Approves a pending plan in Atlas Cloud for a specific change (i.e. the diff between the current and desired states). Run this job on the main branch of your project to automatically approve plans that were generated by the schema-plan job in previous merge requests.

If more than one pending plan is found for a given change, the job will exit with a non-zero code. In this case you will need to Choose the prefered plan and delete the others, before re-runnig the job.

Usage​

stages:
    - push

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-plan-approve@~latest
    inputs:
        stage: push
        branches:
            - main
        env: gitlab
        atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev urls here: https://atlasgo.io/concepts/dev-database.
  • schema-name - (Optional) The name (slug) of the schema repository in Atlas Registry. Read more in Atlas website: Atlas Registry.
  • from - (Optional) URL(s) of the current schema state.
  • to - (Optional) URL(s) of the desired schema state.
  • plan - (Optional) The URL of the plan to be approved. For example, atlas://<schema>/plans/<id>. If not provided, Atlas will search the registry for a plan corresponding to the given schema transition and approve it (typically, this plan is created during the PR stage). If multiple plans are found, an error will be thrown.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.

schema-push​

Pushes a declarative schema to the cloud.

Usage​

stages:
    - push

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-push@~latest
    inputs:
      stage: push
      branches:
        - main
      env: dev
      latest: true
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev urls here: https://atlasgo.io/concepts/dev-database.
  • schema-name - (Optional) The name (slug) of the schema repository in Atlas Registry. Read more in Atlas website: Atlas Registry.
  • url - (Optional) Desired schema URL(s) to push. For example: file://schema.hcl.
  • schema - (Optional) List of database schema(s). For example: public.
  • description - (Optional) The description of the schema.
  • latest - (Optional) If true, push also to the "latest" tag.
  • atlas-cloud-token - A token for Atlas Cloud.
  • atlas-version - (Optional) a specific Atlas version.

schema-apply​

Use this component to apply a schema to your database directly from your CI runner. You can either deploy a local state (i.e from your git repository) or a schema stored in Atlas Cloud.

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 running this component from a runner that has network access to your database.

Usage​

stages:
    - apply

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/schema-apply@~latest
    inputs:
      stage: apply
      branches:
        - main
      env: dev
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN # Needed only for deploying a schema from Atlas Cloud.

Inputs​

  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • branches - The branches to run this jobs on.
  • env - (Optional) The environment to use from the Atlas configuration file. For example, dev.
  • config - (Optional) The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects.
  • vars - (Optional) A JSON object containing variables to be used in the Atlas configuration file. For example, {"var1": "value1", "var2": "value2"}.
  • dev-url - (Optional) The URL of the dev-database to use for analysis. For example: mysql://root:pass@localhost:3306/dev. Read more about dev urls here: https://atlasgo.io/concepts/dev-database.
  • schema-name - (Optional) The name (slug) of the schema repository in Atlas Registry. Read more in Atlas website: Atlas Registry.
  • to - (Optional) URL(s) of the desired schema state.
  • url - (Optional) The URL of the target database to apply changes to. For example: mysql://root:pass@localhost:3306/prod.
  • schema - (Optional) List of database schema(s). For example: public.
  • dry-run - (Optional) If true, print SQL without executing it.
  • auto-approve - (Optional) If true, automatically approve and apply changes.
  • plan - (Optional) The plan to apply. For example, atlas://<schema>/plans/<id>.
  • atlas-cloud-token - (Optional) A token for Atlas Cloud.
  • atlas-version - (Optional) Install a specific Atlas version.

monitor-schema​

Monitor changes of the database schema and track them in Atlas Cloud. Read more about schema monitoring here.

info

Atlas needs network access to your database to monitor schema changes, so make sure your database is either publicly accessible or that you have otherwise running this component from a runner that has network access to your database.

Usage​

stages:
  - monitor-schema

include:
  - component: $CI_SERVER_FQDN/arigaio/atlas/monitor-schema@~latest
    inputs:
      stage: monitor-schema
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN
      url: $DB_URL
      slug: gitlab-monitor

To run on a schedule, go to the Build tab in your repository, Go to the Pipeline Schedules tab and click on New Schedule.

Inputs​

  • atlas-cloud-token - A token for Atlas Cloud for reporting changes.
  • working-directory - (Optional) Atlas working directory, default is project root
  • stage - (Optional) The CI stage to run the job in.
  • url - URL of the database to Monitor (mutually exclusive with config and env).
  • config - The path to the Atlas configuration file. See: https://atlasgo.io/atlas-schema/projects (mutually exclusive with url).
  • env - 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 schema(s). For example: public.
  • exclude - (Optional) List of exclude patterns from inspection.