Atlas schema CLI for coding agents

When a coding agent changes a database, it needs to inspect the schema, the structure of the database’s tables and columns, and check proposed changes before anyone applies them. Atlas is Ariga’s tool for working with database schemas: it reads a database or schema definition, plans migrations, and provides commands to check and apply them. A migration is a set of database changes, such as adding a table or altering a column.

Atlas is unrelated to MongoDB Atlas. An agent can use Atlas’s atlas command-line interface (CLI) to inspect a local database, then prepare and check migration files. The example below only reads the database. Generating migration files and changing a database are separate steps.

What Atlas does

Atlas treats a database schema as code. You can describe the desired schema in SQL, HCL, or ORM models. Atlas compares that description with the current database and plans the changes needed to make them match. Its CLI reference documents commands to inspect schemas, generate migrations, lint and test, and apply migrations.

For a coding agent, this supports a concrete task: inspect a local development database and report which tables and columns it contains before changing application code. If the agent later edits a schema definition, atlas migrate diff generates migration files, and atlas migrate lint checks those files. atlas migrate apply runs migrations against a database, so treat it as a separate, database-changing action. Atlas’s AI agent guide describes this workflow.

Install and inspect a local database

Install Atlas with the command shown in its official CLI documentation:

curl -sSf https://atlasgo.sh | sh

The installer downloads Atlas, so installation requires network access. A local inspection does not require an Atlas account. Atlas uses the URL to connect to the database. A URL for a local SQLite database keeps the inspection on your computer, while a URL for a remote database makes Atlas connect over the network. Put database credentials in the connection configuration or a secret store, not in an agent prompt.

To inspect an existing SQLite database, replace the placeholder with its path:

atlas schema inspect --url "sqlite://PATH_TO_LOCAL_DB"

For example, use sqlite://./dev.db if the database file is dev.db in the current directory. The command reads the database schema and prints it in Atlas’s default schema format, HCL. Atlas also documents a --format option that uses a template to customize the output. Consult the CLI reference before asking an agent to parse customized output.

The schema inspect command only reports the schema; it does not apply migrations. Atlas’s CLI reference explains the command syntax and output options. These examples are based on the documentation and have not been run for this article.

Ask an agent to inspect before editing

A focused prompt gives the agent a bounded task and a clear output:

Run atlas schema inspect against the local SQLite database at ./dev.db. Report the tables and columns you find. Do not edit schema files or run migrations.

The agent can run the command in the repository and summarize Atlas’s output. If the database file is missing or the path is wrong, the command will fail to connect; the agent should report that result rather than infer a schema.

Atlas also offers agent-specific instructions and skills, including setup guidance for several coding agents, in its AI tools documentation. Those integrations are optional for the CLI inspection shown here.

Keep migration generation separate from applying changes

For a schema change, the agent can edit the project’s schema source and run atlas migrate diff to generate migration files. The agent should review the generated files and run atlas migrate lint before anyone applies them. Editing and generating these files changes the local repository, but does not change the target database.

Apply migrations as a separate deployment step. Atlas documents atlas migrate apply for this step. Its deployment guidance advises stopping the deployment if a migration fails and preventing two migration runs from happening at the same time. Atlas also checks that the migration directory matches atlas.sum and that the migration history matches the database. If either check fails, migrate apply aborts.

For an agent task, specify whether it may generate or edit migration files. Require human approval before it runs a command that applies them to a shared or production database.