Skip to main content

Monitor Database Schema Changes with GitLab CI/CD

Connectivity requirements

In order to function, Atlas must be able to establish a connection to your database. This means you need to ensure that your database is accessible from the GitLab CI/CD runners.

The following guide will quickly walk you through how to get started with Atlas Schema Monitoring in under 5 minutes using GitLab CI/CD and Atlas Cloud with the ariga monitor-schema CI Component. Set up continuous schema monitoring, configure secrets, and view schema changes in the Atlas UI.

1. Set up a database user​

To use schema monitoring, you need to create a database user with the appropriate privileges. Then use this user in the database connection URL that you will provide to the GitLab CI/CD pipeline.

To enable Atlas monitoring for your PostgreSQL database, you need to create a dedicated monitoring user with read-only permissions. This user will allow Atlas to connect and inspect your database schema without any write access.

For databases with password authentication:

-- Create a monitoring account
CREATE USER atlas_monitor WITH PASSWORD 'strong_password';

-- Grant read access to specific schema for current and future tables
GRANT SELECT ON ALL TABLES IN SCHEMA <schema_name> TO atlas_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema_name> GRANT SELECT ON TABLES TO atlas_monitor;

For AWS RDS databases using IAM authentication:

If you're using AWS RDS with IAM database authentication, create a user without a password. The username must match the resource specified in your IAM policy.

-- Create a monitoring account. User name is the same as a resource in the IAM policy for IAM database access
CREATE USER atlas_monitor;

-- Allow connect to the database via IAM authentication
GRANT rds_iam TO atlas_monitor;

-- Grant read access to specific schema for current and future tables
GRANT SELECT ON ALL TABLES IN SCHEMA <schema_name> TO atlas_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema_name> GRANT SELECT ON TABLES TO atlas_monitor;

To configure IAM authentication in your Atlas configuration, refer to the IAM authentication guide.

2. Create bot token in Atlas Cloud​

Head over to your Atlas Cloud account and click on the top level ☰ > Monitoring navigation entry. Choose the CI Pipeline card, Choose the GitLab tab, and click on the Generate button. Copy the token.

Screenshot of the Atlas Cloud UI showing how to generate a bot token for GitLab CI/CD integration.

Follow to your GitLab repository and go to Settings -> CI/CD and add a new variable called ATLAS_CLOUD_TOKEN with the value of the token you just copied.

3. Create a new GitLab CI/CD Pipeline for schema monitoring​

Save the workflow file below as .gitlab-ci.yml in your repository.

Make sure that DB_URL is stored as a CI/CD variable with the value of your database url or replace $DB_URL with your database url.

Replace the slug with the name you want to give to your database. The slug is used to uniquely identify the database in Atlas Cloud, even when the database URL changes.

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
info

If your database URL is defined inside atlas.hcl file, you can use the config instead of url in the inputs. For more information, see the GitLab CI/CD documentation.

      stage: monitor-schema
      atlas-cloud-token: $ATLAS_CLOUD_TOKEN
-     url: $DB_URL
+     config: "file://atlas.hcl"
+     env: "dev"

Enable statistics collection​

To collect and monitor database statistics (such as table sizes, row counts, and index usage) along with your schema, add the collect-stats input and set it to true:

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
      collect-stats: "true"

When enabled, Atlas will collect statistics about your database schema during each monitoring run. These statistics are displayed in the Atlas Cloud UI alongside your schema information, helping you track database growth and performance metrics over time.

Then commit and push the changes to your repository.

4. Set schedule pipeline​

Once committed, go to the Build tab in your repository, Go to the Pipeline Schedules tab and click on New Schedule.

After Setting up the schedule, the pipeline will run at the scheduled time. You can also run the pipeline manually by clicking on the Run pipeline button.

Screenshot of the GitLab UI showing how to create a new scheduled pipeline.

After the pipeline runs, it should show you a link to the Atlas Cloud where you can view the schema of your database.

Screenshot of a successful GitLab CI/CD pipeline run log, showing the output and a link to the Atlas Cloud report.

5. View the schema in the Atlas UI​

Click on the link provided in the logs to view the schema in the Atlas UI.

Screenshot of the Atlas Cloud UI showing the visualized schema for a monitored database instance.

Next steps​