How does Atlas run specific `pgTAP` tests in SQL?

Atlas uses its `bash` tool to execute `pgTAP` with the `--filter` flag, allowing you to specify a single test function or file, like `pg_prove --filter 'my_schema.specific_test' src/test/sql/my_tests.sql`.

Can Atlas navigate complex SQL stored procedures and functions?

Yes, Atlas's `lsp` tool indexes your SQL code by AST declarations, enabling it to `goToDefinition` and `findReferences` across `Flyway migrations` and other `.sql` files, providing a deep understanding of your codebase.

How does Atlas ensure my SQL code changes are safe?

Atlas operates with permission-gated tool calls and presents a unified diff for every proposed SQL edit, requiring your explicit approval before writing any changes to disk, ensuring full developer control.

Does Atlas support my existing SQL toolchain like `sqlfluff`?

Absolutely. Atlas works within your existing environment, allowing you to invoke tools like `sqlfluff format` via its `bash` tool to maintain code style and `Flyway migrations` for schema management during fixes.

Can Atlas help debug SQL performance issues?

While focused on functional test failures, Atlas can assist by allowing you to insert `EXPLAIN ANALYZE` statements via `edit` and run queries with `bash` to analyze execution plans and identify performance bottlenecks.

What kind of SQL files does Atlas index?

Atlas indexes all your `.sql` files, including `Flyway migrations` scripts, `pgTAP` test files, stored procedures, functions, and view definitions, building a comprehensive understanding of your entire SQL codebase.

How does Atlas handle large SQL codebases?

Atlas builds its code index with local Ollama embeddings, efficiently searching code with hybrid semantic and keyword retrieval. This approach makes it effective for large SQL repositories without sending code to third-party servers, ensuring privacy and performance.

Debug a single failing test in SQL with Atlas in 2026

Atlas helps SQL developers in 2026 debug a single failing test by running `pgTAP` tests in isolation, analyzing the call graph with its `lsp` tool, and proposing fixes to your production code, not the assertion. It integrates directly with your `Flyway migrations` and other SQL files, providing a terminal-native experience for rapid iteration and code correction.

How Atlas isolates a failing pgTAP test in SQL

Atlas isolates a single failing `pgTAP` test in SQL by leveraging the `bash` tool to execute the test runner with specific filters, ensuring only the relevant test runs. This approach, familiar to any SQL developer in 2026, minimizes output noise and focuses debugging efforts on the exact problem, often reducing execution time by over 90% compared to running the full suite.

To efficiently debug a specific issue, Atlas first runs just the failing `pgTAP` test. It achieves this by using its `bash` tool to invoke the `pg_prove` command with the `--filter` flag. For instance, Atlas might execute `pg_prove --filter 'my_schema.my_failing_test_function' src/test/sql/my_module_tests.sql`. This command targets a single test, drastically reducing the output volume and execution time, making it easier to pinpoint the exact failure. Atlas then uses its `read` tool to capture and analyze the assertion failure message and stack trace, providing the initial context for the debugging process. This method mirrors how a SQL developer would manually isolate a test, ensuring a familiar and effective debugging environment.

Walking the SQL call graph with Atlas's LSP tool

After isolating a failing `pgTAP` test, Atlas uses its `lsp` tool to walk the SQL call graph, understanding the relationships between functions, views, and tables. This capability, powered by AST declarations and local Ollama embeddings, allows Atlas to precisely trace the execution path from the test assertion back to the production code, a critical step for debugging complex SQL logic in 2026.

Once a failing `pgTAP` test is identified, Atlas employs its `lsp` tool to understand the underlying SQL code. Atlas indexes your SQL codebase by AST declarations using tree-sitter, not blind line windows, and can build this index with local Ollama embeddings, keeping your code off third-party servers. This deep understanding allows Atlas to use `goToDefinition` to jump from a failing assertion in `src/test/sql/order_tests.sql` directly to the relevant function definition in `functions/calculate_order_total.sql`. Similarly, `findReferences` helps Atlas identify all places where a specific function or table is used, enabling it to trace the full call path and understand dependencies within your `Flyway migrations` scripts and other `.sql` files, such as `V1__create_tables.sql` or `R__update_views.sql`.

Forming and checking hypotheses in SQL with Atlas

Atlas forms and checks hypotheses in SQL by using the `edit` tool to insert temporary logging or by re-running `pgTAP` tests with verbose flags via `bash`. This iterative process, common for SQL developers in 2026, allows Atlas to quickly validate assumptions about data states or function behavior, often requiring fewer than 5 cycles to pinpoint the root cause of a failure.

To validate a hypothesis about why a SQL test is failing, Atlas can temporarily modify the production code. Using the `edit` tool, Atlas can insert `RAISE NOTICE` or `RAISE DEBUG` statements into a suspected function, for example, adding `RAISE NOTICE 'Value of x: %', x;` within `my_schema.my_problematic_function.sql`. After inserting the logging, Atlas re-runs the isolated `pgTAP` test using `bash` to observe the new output. Alternatively, Atlas can re-run `pg_prove` with verbose flags, such as `pg_prove --verbose src/test/sql/my_tests.sql`, to get more detailed information from the test runner itself. This iterative process of modifying, running, and reading output allows Atlas to quickly narrow down the problem, much like a developer would manually debug a stored procedure.

Fixing SQL code with Atlas's edit and apply_patch tools

Once the root cause is identified, Atlas fixes the production SQL code using its `edit` tool for small, focused changes or `apply_patch` for more extensive modifications spanning multiple hunks. This ensures that fixes to `Flyway migrations` or stored procedures are precise and maintainable, reflecting best practices for SQL development in 2026 and beyond.

After pinpointing the exact issue, Atlas proceeds to fix the production SQL code. For minor adjustments, such as correcting a single line in a function definition or updating a column name in a view, Atlas uses its `edit` tool. For example, it might modify `functions/get_customer_details.sql` directly. If the fix involves changes across several parts of a file or multiple files, Atlas utilizes `apply_patch`. This tool allows Atlas to generate and apply a unified diff, ensuring that complex changes to `Flyway migrations` scripts like `V4__refactor_inventory.sql` or `R__update_reports.sql` are applied atomically and consistently. Throughout this process, Atlas can also invoke `sqlfluff format` via `bash` to ensure that all code changes adhere to the project's defined SQL style guidelines.

Reviewing and approving SQL code changes with Atlas

Atlas ensures every SQL code change is reviewed and approved by the developer, presenting a unified diff for every file edit before writing to disk. This permission-gated workflow, a core feature since Atlas's inception, prevents unintended modifications to critical `Flyway migrations` or `pgTAP` test files, providing a robust safety net for SQL development in 2026.

Atlas prioritizes developer control and safety. Before any proposed SQL code changes are written to your file system, Atlas computes a unified diff for every file edit and surfaces it for your approval. This allows you to review exactly what Atlas intends to change in files like `src/main/resources/db/migration/V5__add_audit_triggers.sql` or `functions/calculate_tax.sql`. Every Atlas tool call is permission-gated against allow, ask, and deny rules, ensuring that no action is taken without your explicit consent. Atlas drafts a plan in a read-only plan agent and asks for your approval before switching to a build agent to execute the changes. Furthermore, Atlas reads `git` branches, status, and diffs, and can stage and create commits on your behalf, integrating direct into your existing SQL development workflow and providing a clear audit trail for all modifications.

Step by step

01Run Atlas in your SQL repository, ensuring it has indexed your `Flyway migrations` and `.sql` files for comprehensive code understanding.
02Use `atlas bash` to execute the failing `pgTAP` test in isolation, for example: `pg_prove --filter 'my_schema.my_failing_test' src/test/sql/my_tests.sql`.
03With the test output, use `atlas lsp goToDefinition` on the failing assertion or relevant function to trace the call path through your SQL code, such as `functions/calculate_total.sql`.
04Form a hypothesis and use `atlas edit` to insert temporary `RAISE NOTICE` logging into the suspected SQL function, then re-run the isolated test with `atlas bash`.
05Once the issue is identified, use `atlas edit` to fix the production SQL code in files like `src/main/resources/db/migration/V3__update_pricing.sql`, ensuring `sqlfluff format` standards are met.
06Review the proposed changes in the unified diff presented by Atlas and approve them before writing to disk.
07Re-run the single `pgTAP` test with `atlas bash` to confirm the fix, then run the full `pgTAP` test suite to ensure no regressions.
08Use `atlas edit` to remove any temporary logging added, and approve the final changes, then `atlas git commit` to finalize your work.

Frequently asked questions

How does Atlas run specific `pgTAP` tests in SQL?: Atlas uses its `bash` tool to execute `pgTAP` with the `--filter` flag, allowing you to specify a single test function or file, like `pg_prove --filter 'my_schema.specific_test' src/test/sql/my_tests.sql`.
Can Atlas navigate complex SQL stored procedures and functions?: Yes, Atlas's `lsp` tool indexes your SQL code by AST declarations, enabling it to `goToDefinition` and `findReferences` across `Flyway migrations` and other `.sql` files, providing a deep understanding of your codebase.
How does Atlas ensure my SQL code changes are safe?: Atlas operates with permission-gated tool calls and presents a unified diff for every proposed SQL edit, requiring your explicit approval before writing any changes to disk, ensuring full developer control.
Does Atlas support my existing SQL toolchain like `sqlfluff`?: Absolutely. Atlas works within your existing environment, allowing you to invoke tools like `sqlfluff format` via its `bash` tool to maintain code style and `Flyway migrations` for schema management during fixes.
Can Atlas help debug SQL performance issues?: While focused on functional test failures, Atlas can assist by allowing you to insert `EXPLAIN ANALYZE` statements via `edit` and run queries with `bash` to analyze execution plans and identify performance bottlenecks.
What kind of SQL files does Atlas index?: Atlas indexes all your `.sql` files, including `Flyway migrations` scripts, `pgTAP` test files, stored procedures, functions, and view definitions, building a comprehensive understanding of your entire SQL codebase.
How does Atlas handle large SQL codebases?: Atlas builds its code index with local Ollama embeddings, efficiently searching code with hybrid semantic and keyword retrieval. This approach makes it effective for large SQL repositories without sending code to third-party servers, ensuring privacy and performance.

Try Atlas in your terminal

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

Install Atlas

Related guides

Debug a Single Failing Test with Atlas in 2026

How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.

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.

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.

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.

Run Atlas Headless in CI for SQL in 2026

Automate SQL development workflows in CI with Atlas. Learn how to run Atlas headless, integrate with pgTAP and Flyway migrations, and get machine-readable output for your SQL pipelines.

Locate Where a Behavior is Implemented in SQL with Atlas in 2026

In 2026, Atlas helps SQL developers quickly locate the exact file and symbol responsible for a behavior across Flyway migrations and .sql files, using semantic search and LSP.

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.

Document a SQL Module with a README using Atlas in 2026

In 2026, Atlas helps SQL developers generate accurate READMEs for modules by analyzing live code, not outdated specs. It leverages pgTAP, Flyway migrations, and sqlfluff format to ensure documentation reflects the

Browse this resource hub