How does Atlas understand my SQL schema and migrations?

Atlas reads your `.sql` files, including `Flyway migrations` and schema definitions, and builds an index using AST declarations. This allows it to understand the structure, relationships, and history within your database code, providing context-aware assistance.

Can Atlas help me find specific SQL functions or stored procedures?

Yes, use `codebase_search` with a plain-language query like "find the `authenticate_user` function" or "show me the `get_order_details` stored procedure." Atlas will return ranked snippets from relevant `.sql` files, guiding you directly to the code.

How does Atlas ensure it doesn't accidentally modify my SQL database or files?

Atlas operates with strict permission gating. Its `explore` subagent is read-only by default, and any proposed changes, such as new `Flyway migrations` or query optimizations, are presented as a unified diff for your explicit approval before writing to disk.

Does Atlas support `pgTAP` for testing SQL code?

Yes, Atlas recognizes `pgTAP` test files and can help you understand their structure, identify relevant tests for specific database objects, or even draft new test cases by analyzing existing `pgTAP` patterns within your codebase.

Can Atlas help me understand the history of my `Flyway migrations`?

Absolutely. Atlas can `glob` your `db/migrations/` directory to show the sequence of `Flyway migrations` and `read` individual migration files to explain their purpose and the changes they introduced to your schema over time.

How does Atlas handle SQL formatting with `sqlfluff`?

While Atlas doesn't directly run `sqlfluff format`, it understands the structure of well-formatted SQL. When drafting new SQL or refactoring, Atlas can adhere to common SQL style conventions, and you can then apply `sqlfluff format` as part of your existing CI/CD pipeline for final consistency.

What if I need to search for specific SQL keywords like `CREATE TABLE` or `ALTER INDEX`?

For keyword-specific searches, you can delegate to the `explore` subagent using the `task` tool with `grep`. For example, `task explore grep "CREATE TABLE"` will quickly find all table creation statements across your `.sql` files, including `Flyway migrations`.

Onboard to an Unfamiliar SQL Codebase with Atlas in 2026

Atlas helps SQL developers in 2026 quickly build a working mental model of unfamiliar codebases by leveraging semantic search, exploring `Flyway migrations`, and understanding `pgTAP` tests without reading every file. It starts from meaning, not filenames, to guide you through the repository's structure and logic, integrating directly with your SQL toolchain.

How does Atlas help SQL developers understand new codebases?

Atlas helps SQL developers in 2026 understand new codebases by starting from meaning, not filenames, using its `codebase_search` tool. This tool queries a semantic index built from your `.sql` files, including `Flyway migrations` and `pgTAP` tests, to quickly surface relevant information.

Atlas builds a comprehensive code index using AST declarations from your SQL files, rather than relying on blind line windows. This allows it to understand the structure of your schema, stored procedures, functions, and `Flyway migrations`. When you ask `codebase_search` a plain-language question, such as "how are requests authenticated in the `auth` schema?", Atlas queries this semantic index. It returns ranked snippets with file paths, like `db/migrations/V1.2__add_auth_tables.sql` or `functions/auth_user.sql`, directly pointing you to the most relevant SQL code. This approach ensures that you focus on the core logic and data flow, bypassing the need to manually sift through dozens of `.sql` files or configuration directories. Atlas can also build this index with local Ollama embeddings, ensuring your proprietary SQL code remains off third-party servers.

What Atlas tools are used for SQL codebase exploration?

For SQL codebase exploration, Atlas leverages a suite of 5 core tools: `codebase_search`, `glob`, `read`, `lsp`, and `task`. These tools work together to help you build a mental model of the repository in 2026, from high-level structure to specific function definitions.

The `codebase_search` tool is your entry point, allowing you to ask questions like "how are `pgTAP` tests structured for the `users` table?" to find relevant test files such as `tests/users_test.sql`. Once you have an initial understanding, `glob` helps you map the directory shape, for instance, by running `glob 'db/migrations/*.sql'` to see the sequence of `Flyway migrations` or `glob 'schemas/*.sql'` to understand schema organization. The `read` tool then pulls only the files that actually matter, letting you inspect `V1.0__initial_schema.sql` or `functions/calculate_total.sql`. For deeper dives, the `lsp` tool's `goToDefinition` operation allows you to follow references within SQL, jumping from a stored procedure call to its definition in another file. For wide sweeps, the `task` tool delegates to the `explore` subagent, which can `grep` for all `CREATE FUNCTION` statements across the entire codebase or `websearch` for best practices related to `pgTAP` testing. Finally, `todowrite` helps you record open questions or insights, ensuring your learning persists across sessions.

How does Atlas ensure safety when exploring a SQL repository?

Atlas ensures safety when exploring a SQL repository in 2026 through a multi-layered permission system and explicit user approval. Every Atlas tool call is permission-gated, and any proposed changes to your `.sql` files or `Flyway migrations` are presented as a unified diff for review.

Safety is paramount when interacting with database code. Atlas implements a robust permission-gating system, allowing you to configure `allow`, `ask`, or `deny` rules for every tool call before it runs. When exploring, Atlas first drafts a plan in a read-only plan agent, asking for your approval before switching to a build agent that could potentially modify files. The `explore` subagent, specifically designed for wide sweeps, operates with a `deny-by-default` permission set, only allowing safe operations like `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This means it cannot inadvertently alter your `Flyway migrations` or `pgTAP` test files. Furthermore, any file edit Atlas proposes, such as drafting a new migration file like `V1.3__add_index_to_users.sql` or refactoring a query in `reports.sql`, is computed as a unified diff and surfaced for your explicit approval before it is written to disk. Atlas also snapshots file changes as git patches, so edits can be easily diffed and rolled back if needed, providing an additional layer of security for your SQL codebase.

How does Atlas integrate with the SQL development workflow?

Atlas integrates direct into the SQL development workflow in 2026 by understanding your existing toolchain, including `pgTAP` for testing and `Flyway migrations` for schema management. It reads your schema, migration history, and query files to provide context-aware assistance.

Atlas is designed to be a terminal-native AI coding agent that complements your existing SQL development practices. When you run Atlas in a repository containing your `Flyway migrations` or `.sql` files, it automatically reads your schema definitions, migration history, and query files. This deep understanding allows Atlas to assist with tasks specific to SQL, such as optimizing a complex query in `analytics.sql` or drafting a new `Flyway migration` like `V1.4__add_audit_log.sql`. For testing, Atlas recognizes and understands `pgTAP` test files, enabling it to help you navigate existing tests or suggest new ones based on your code changes. While Atlas doesn't directly run `sqlfluff format`, it understands the conventions of well-formatted SQL and can generate code that adheres to common style guides. After Atlas drafts a change, it presents a unified diff for your review, allowing you to approve or refine the proposed SQL before applying it, ensuring that the output aligns with your team's standards and passes your `pgTAP` tests.

Step by step

01Ask `codebase_search` a plain-language question about SQL concepts, for example, "how are requests authenticated in the `auth` schema?" to find relevant `.sql` files.
02Run `glob` on top-level directories such as `db/migrations/`, `schemas/`, or `tests/` to understand the `Flyway migrations` layout and `pgTAP` test structure.
03Read the two or three `.sql` files `codebase_search` ranked highest, then use the `lsp` tool's `goToDefinition` operation to follow references to stored procedures or views.
04Delegate wide sweeps to the `explore` subagent using the `task` tool, for example, to `grep` for all `CREATE TABLE` statements across `V*.sql` migration files.
05Record what you learned as a `todowrite` list, noting open questions about specific SQL functions or `pgTAP` test patterns for future investigation.

Frequently asked questions

How does Atlas understand my SQL schema and migrations?: Atlas reads your `.sql` files, including `Flyway migrations` and schema definitions, and builds an index using AST declarations. This allows it to understand the structure, relationships, and history within your database code, providing context-aware assistance.
Can Atlas help me find specific SQL functions or stored procedures?: Yes, use `codebase_search` with a plain-language query like "find the `authenticate_user` function" or "show me the `get_order_details` stored procedure." Atlas will return ranked snippets from relevant `.sql` files, guiding you directly to the code.
How does Atlas ensure it doesn't accidentally modify my SQL database or files?: Atlas operates with strict permission gating. Its `explore` subagent is read-only by default, and any proposed changes, such as new `Flyway migrations` or query optimizations, are presented as a unified diff for your explicit approval before writing to disk.
Does Atlas support `pgTAP` for testing SQL code?: Yes, Atlas recognizes `pgTAP` test files and can help you understand their structure, identify relevant tests for specific database objects, or even draft new test cases by analyzing existing `pgTAP` patterns within your codebase.
Can Atlas help me understand the history of my `Flyway migrations`?: Absolutely. Atlas can `glob` your `db/migrations/` directory to show the sequence of `Flyway migrations` and `read` individual migration files to explain their purpose and the changes they introduced to your schema over time.
How does Atlas handle SQL formatting with `sqlfluff`?: While Atlas doesn't directly run `sqlfluff format`, it understands the structure of well-formatted SQL. When drafting new SQL or refactoring, Atlas can adhere to common SQL style conventions, and you can then apply `sqlfluff format` as part of your existing CI/CD pipeline for final consistency.
What if I need to search for specific SQL keywords like `CREATE TABLE` or `ALTER INDEX`?: For keyword-specific searches, you can delegate to the `explore` subagent using the `task` tool with `grep`. For example, `task explore grep "CREATE TABLE"` will quickly find all table creation statements across your `.sql` files, including `Flyway migrations`.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Onboard to an Unfamiliar Codebase with Atlas in 2026

How to onboard to an unfamiliar codebase with Atlas in 2026: use codebase_search, glob, read, lsp, task, and todowrite to build a mental model fast.

Atlas for SQL in 2026

Atlas is a terminal-native AI coding agent for SQL in 2026. Run it in a repo with your migrations or .sql files, optimize a query, and review the diff before applying.

Migrate a Deprecated API Across Every Callsite in SQL with Atlas in 2026

In 2026, Atlas helps SQL developers migrate deprecated functions or modules across an entire codebase, ensuring no callsite is missed and changes are validated with pgTAP and Flyway migrations.

Self-review your working diff before committing in SQL with Atlas in 2026

Catch your own mistakes in uncommitted SQL diffs before they reach review or CI. Atlas helps SQL developers in 2026 self-review changes, run pgTAP tests, and format with sqlfluff.

Diagnose a Hanging or Long-Running SQL Command with Atlas in 2026

In 2026, use Atlas to quickly diagnose if your SQL scripts, `Flyway migrations`, or `pgTAP` tests are genuinely slow or silently blocked on input, getting you unstuck fast.

Audit a SQL Repo with Parallel Subagents in 2026 using Atlas

In 2026, SQL developers use Atlas to audit entire repositories for specific problems, leveraging parallel subagents to sweep code without context window limits. Integrate with pgTAP, Flyway migrations, and sqlfluff

Add a Regression Test for a SQL Bug Fix with Atlas in 2026

Lock in SQL bug fixes with Atlas in 2026. Learn to add a regression test that fails before the fix and passes after, using pgTAP and Flyway migrations.

Rename a SQL Symbol Across Your Repo with Atlas in 2026

In 2026, Atlas helps SQL developers rename functions, classes, or constants across their entire codebase, integrating with pgTAP, Flyway, and sqlfluff for verified refactoring.

Browse this resource hub