Skip to main content

Agent Quickstart

Follow this guide to get started with Atlas Schema Monitoring in under 5 minutes using the Atlas agent.

Prerequisites:

  • An Atlas Cloud account
  • Docker installation

This is what this guide will walk you through:

  1. Spin up a local database with docker
  2. Install the Atlas agent locally
  3. Connect Atlas to the database using the Agent
  4. View the schema in the Atlas UI
  5. Make a change to the schema and see it reflected in the Atlas UI

1. Spin up a local database​

Create a docker network and a database container attached to this network. This is required for the Atlas agent docker to see the database.

After the database is up, create the database schema.

docker network create atlas-agent-network
docker run --network atlas-agent-network -e MYSQL_ROOT_PASSWORD=pass -e MYSQL_DATABASE=dev -p 3306:3306 -d --name dev mysql:8
docker exec -i dev mysql -uroot -ppass dev -e "
  CREATE TABLE users(id int NOT NULL, name varchar(100) NULL, PRIMARY KEY(id));
  CREATE TABLE blog_posts(id int NOT NULL, title varchar(100) NULL, body text NULL, author_id int NULL, PRIMARY KEY(id), CONSTRAINT author_fk FOREIGN KEY(author_id) REFERENCES users(id));"

2. Install Atlas agent​

Head over to your Atlas Cloud account and click on the top level Monitoring navigation entry. chose a name for your agent and click on Create Agent. Copy the token.

Run the following command on your local machine to start the agent (replace <your-token> with the token shown to you in the modal). Notice the PASS environment variable containing the password for the dev db we set up earlier (pass).

docker run -e PASS=pass -e ATLAS_CLOUD_TOKEN="<your-token>" -e ATLAS_AUTO_UPDATE=false --network atlas-agent-network -d arigaio/atlas-agent

Once you see the success message, click on Add Monitored Database.

3. Connect Atlas to your database​

Assign your database instance a name, dev in this case. Select driver (MYSQL) and agent (there should only be the one you just created), and as address use dev:3306, username is root. Atlas does not store any credentials, the agent just needs to know how to obtain them. In our case the password is given to the agent as the environment variable PASS. Once you have filled out all fields, click on Check Connection. It should go green, and you can save the changes.

4. View the schema​

Click on the newly created instance. You will see an empty state screen, click on Create Scope, give it a name (e.g. all), click Add Scope and wait for the agent to inspect the database and report back its database schema. Once that happened, you can view the schema ERD, docs and in the Changelog tab you can see the changes done to your schema over time.

5. Make a change​

To simulate a change to the database schema, let's create a new table.

docker exec dev mysql -h127.0.0.1 -P3306 -uroot -ppass dev -e "create table some_table (some_column int)"

Hit the Refresh button and observe the ERD and schema docs reflect the changes. The Changelog will contain a new entry with detailed information about the change.

Next steps​