Monitor your database schema with Bitbucket Pipelines
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 Bitbucket Pipelines runners.
The following guide will quickly walk you through how to get started with Atlas Schema Monitoring in under 5 minutes using the
ariga monitor-schema
Pipleine.
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 Bitbucket Pipeline.
- PostgreSQL
- MySQL
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.
To enable Atlas monitoring for your MySQL database, create a dedicated monitoring user with the minimum required permissions. This user only needs read access to inspect your database schema.
For databases with password authentication:
-- Create monitoring account (replace host as needed)
CREATE USER 'atlas_monitor'@'%' IDENTIFIED BY 'strong_password';
-- Grant read access
GRANT SHOW DATABASES ON *.* TO 'atlas_monitor'@'%';
GRANT SHOW VIEW ON *.* TO 'atlas_monitor'@'%';
GRANT SELECT ON *.* TO 'atlas_monitor'@'%';
GRANT TRIGGER ON *.* TO 'atlas_monitor'@'%';
For AWS RDS databases using IAM authentication:
If you're using AWS RDS with IAM database authentication, create a user that uses the AWS authentication plugin instead of a password.
-- Create monitoring account (replace host as needed)
CREATE USER 'atlas_monitor'@'%' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
-- Grant read access
GRANT SHOW DATABASES ON *.* TO 'atlas_monitor'@'%';
GRANT SHOW VIEW ON *.* TO 'atlas_monitor'@'%';
GRANT SELECT ON *.* TO 'atlas_monitor'@'%';
GRANT TRIGGER ON *.* 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 Bitbucket tab, and click on the Generate button. Copy the token.

Follow to your Bitbucket repository and go to Repository settings -> Pipelines -> Repository variables and add a new variable called ATLAS_CLOUD_TOKEN
3. Create a new Bitbucket Pipeline for schema monitoring
Save the workflow file below as bitbucket-pipelines.yml
in your repository.
Make sure that DB_URL
is stored as a Repository variable
with the value of your database url
or replace $DB_URL
with your database url.
Replace the ATLAS_INPUT_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.
image: atlassian/default-image:3
pipelines:
custom:
monitor-schema:
- step:
name: "Monitor your database schema"
script:
- name: "Monitor schema"
pipe: docker://arigaio/atlas-action:v1
variables:
ATLAS_ACTION: "monitor/schema"
ATLAS_INPUT_CLOUD_TOKEN: ${ATLAS_CLOUD_TOKEN}
ATLAS_INPUT_URL: ${DB_URL}
ATLAS_INPUT_SLUG: "bitbucket_monitoring" # optional
- source .atlas-action/outputs.sh
If your database URL is defined inside atlas.hcl
file, you can use the ATLAS_INPUT_CONFIG
instead of ATLAS_INPUT_URL
.
For more information, see the Bitbucket Pipes documentation.
variables:
ATLAS_ACTION: "monitor/schema"
ATLAS_INPUT_CLOUD_TOKEN: ${ATLAS_CLOUD_TOKEN}
- ATLAS_INPUT_URL: ${DB_URL}
+ ATLAS_INPUT_CONFIG: "file://atlas.hcl"
+ ATLAS_INPUT_ENV: "dev"
Then commit and push the changes to your repository.
4. Set schedule pipeline
Once committed, go to the Pipelines tab in your repository, Click on Schedules and click on New schedule.
Select the monitor-schema
pipeline you just created and set the schedule to run at your desired frequency.
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.
After the pipeline runs, it should show you a link to the Atlas Cloud where you can view the schema of your database.
5. View the schema in the Atlas UI
Click on the link provided in the logs to view the schema in the Atlas UI.