Exploring Database Schemas with Atlas
Atlas is most commonly used for managing and applying schema changes to databases, but it can also be used for something else: exploring and understanding database schemas.
With inspection, Atlas connects to your database, analyzes its structure from the metadata tables, and creates a graph data structure that maps all the entities and relations within the database. Atlas can then take this graph and represent it in various formats for users to consume. In this post, I will present two such forms of representation: Entity Relationship Diagrams (ERDs) and JSON documents.
Schemas as ERDs
One of the most useful ways to represent a database schema is using an Entity Relationship Diagram (ERD). This allows developers to see the schema in a visual and intuitive way, making it easy to understand the relationships between different elements of the database. When using ERDs, because the data is presented in a graph format, you can easily navigate through the schema and see how different entities are connected. This can be especially useful when working with complex or large databases, as it allows you to quickly identify patterns and connections that might not be immediately obvious when looking at the raw data.
To automatically generate an ERD from your database, you can use the Explore feature of Atlas Cloud. To visualize a schema using the Explore feature, you need to provide your database schema in one of two ways:
-
Provide a connection string to your database. This will allow Atlas Cloud to connect to your database and automatically generate a schema from the metadata tables. Note: this method only works for databases that are publicly accessible via the internet.
-
Provide the schema as an Atlas HCL file. If you have an existing Atlas project, you can use the
atlas schema inspectcommand to generate the HCL file from your database.After installing Atlas, you can run the following command to generate the HCL representation of your database schema:
# MySQL
atlas schema inspect -u mysql://root:pass@localhost:3306/db_name
# PostgreSQL
atlas schema inspect postgres://postgres:pass@localhost:5432/db_name?sslmode=disable
Schemas as JSON documents
In addition to producing ERDs, Atlas can also produce a JSON document that represents the database schema.
One of the key benefits of representing the database schema as a JSON document is that it allows you to use standard
tools like jq to analyze the schema programmatically. jq is a popular command-line tool for working with JSON data,
and it can be especially useful for exploring and manipulating the schema data generated by Atlas.
With jq, you can easily extract specific information from the schema, such as the names of all the tables in the database or the foreign key relationships between different entities. This makes it easy to write scripts or programs that can automatically analyze the schema and identify potential issues or opportunities for optimization.
To get the JSON representation of your database schema, you can use the atlas schema inspect command with a
custom logging format:
atlas schema inspect -u '<url>' --format '{{ json . }}'
This will output the schema as a JSON document:
{
"schemas": [
{
"name": "test",
"tables": [
{
"name": "blog_posts",
"columns": [
{
"name": "id",
"type": "int"
},
{
"name": "title",
"type": "varchar(100)",
"null": true
},
// .. Truncated for brevity ..
]
}
]
}
Once your schema is represented as a JSON document, you can use jq to analyze it. For example, to get a list of all
the tables that contain a foreign key, run:
atlas schema inspect -u '<url>' --format '{{ json . }}' | jq '.schemas[].tables[] | select(.foreign_keys | length > 0) | .name'
This will output:
"blog_posts"
Wrapping up
In this blog post, we demonstrated how Atlas can be used as a schema inspection and visualization tool, in
addition to its more commonly known use as a schema migration tool. We showed how to use the Explore feature to
create an ERD from your database schema, and how to use the atlas schema inspect command to generate a JSON
document that can be analyzed using jq and other tools.
Have questions? Feedback? Feel free to reach out on our Discord server.
