How does Atlas ensure it finds all SQL calls to a deprecated function?

Atlas employs a dual-pronged approach to find all SQL calls to a deprecated function. It uses the `lsp` tool's `findReferences` operation, which leverages AST declarations from tree-sitter to semantically identify explicit calls within `.sql` files and `Flyway migrations`. This is fused with a `grep` search for the deprecated symbol's name, which catches dynamic SQL constructions or string-based usages that might not be visible to the language server, ensuring comprehensive enumeration.

Can Atlas handle SQL files that have changed since the initial scan?

Yes, Atlas is designed to handle drifted SQL files. When `atlas apply_patch` attempts to migrate a callsite, it uses a context-anchored patch. This means it verifies that the `old_lines` and their surrounding context, as expected by the patch, are still present in the target `.sql` file. If the file has changed and the expected context is not found, `apply_patch` will explicitly fail with `Failed to find expected lines` rather than guessing, preventing incorrect modifications to your `Flyway migrations` or other SQL assets.

How does Atlas integrate with existing SQL testing frameworks like pgTAP?

Atlas integrates direct with existing SQL testing frameworks like `pgTAP` through its `bash` tool. After each individual file modification during a migration, Atlas can execute specific `pgTAP` test commands, such as `pg_prove tests/my_function_test.sql`. This allows for immediate validation of the SQL changes. Only when these `pgTAP` tests pass successfully is the corresponding `todowrite` entry marked as complete, ensuring that every step of the migration maintains the functional correctness of your SQL codebase.

What safety measures does Atlas have before writing changes to SQL files?

Atlas implements several safety measures before writing changes to SQL files. All Atlas tool calls are permission-gated, requiring explicit approval. It drafts a read-only plan of action, allowing you to review the entire migration strategy. Crucially, for every proposed file edit, Atlas computes and surfaces a unified diff for your approval, letting you inspect every line change before it's written to disk. Atlas also snapshots file changes as `git` patches, providing a rollback mechanism.

Does Atlas support SQL schema migrations managed by tools like Flyway?

Yes, Atlas fully supports SQL schema migrations managed by tools like `Flyway migrations`. Atlas is designed to run in a repository containing your `.sql` files and migration history. It can read your schema and migration files, understanding the context of your database. When migrating a deprecated API, Atlas will identify callsites within `Flyway migrations` scripts (e.g., `migrations/V1_0_0__initial_schema.sql`) and apply changes with the same precision and safety as it would to any other `.sql` file, ensuring your migration history remains consistent.

Can Atlas help with the final cleanup and commit of the SQL migration?

Absolutely. After all callsites of the deprecated SQL API are migrated and validated, Atlas assists with the final cleanup. It performs a conclusive `grep` search to confirm zero remaining usages of the deprecated symbol. Once confirmed, Atlas can help delete the old implementation file. Furthermore, Atlas reads `git` branches, status, and diffs, and can stage and create commits on your behalf, allowing you to finalize the entire migration with a clean, atomic `git` commit that fully removes the deprecated API from your SQL codebase.

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

Atlas, the terminal-native AI coding agent, empowers SQL developers in 2026 to systematically migrate an entire codebase off a deprecated function or module onto its replacement, without missing a single caller. By leveraging tools like `lsp` for comprehensive callsite enumeration, `todowrite` for tracking progress, and `apply_patch` for precise, context-anchored modifications, Atlas ensures a complete and verified transition, integrating directly with your existing `pgTAP` tests and `Flyway migrations` setup.

How Atlas enumerates all SQL callsites for a deprecated function?

In 2026, Atlas ensures a complete migration of deprecated SQL functions by first enumerating every callsite, a critical step that prevents missed usages. This process combines the precision of language server protocol (LSP) references with a robust keyword search, guaranteeing that both explicit and dynamic SQL usages are identified across your `.sql` files and `Flyway migrations`.

Atlas begins the migration of a deprecated SQL API by comprehensively identifying all its callsite references. The `lsp` tool's `findReferences` operation is the primary mechanism, leveraging Atlas's AST-based indexing, built with tree-sitter, to pinpoint every explicit invocation of the deprecated symbol within your SQL codebase. For instance, if you are deprecating a function like `public.old_calculate_tax(numeric)`, Atlas will use `atlas lsp findReferences --symbol "public.old_calculate_tax"` to locate all views, stored procedures, or other functions that call it, even across files like `sql/views/tax_summary.sql` or `functions/reporting_procs.sql`. To catch more elusive or dynamic usages, such as those constructed via string concatenation in `DO` blocks or within `Flyway migrations` scripts like `migrations/V1_2_3__update_tax_logic.sql`, Atlas cross-checks the `lsp` results with a `grep` search for the deprecated symbol's name. This hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, ensures that no callsite, whether directly referenced or dynamically generated, is overlooked, providing a complete enumeration before any changes are proposed.

How Atlas safely migrates each SQL callsite with precise patches?

Migrating each SQL callsite requires precision to avoid introducing errors, a task Atlas handles with its `apply_patch` tool in 2026. Atlas creates a `todowrite` entry for every identified callsite, ensuring visible progress, and then applies context-anchored patches that fail safely rather than misapplying to drifted SQL files, protecting your `Flyway migrations` and `.sql` assets.

Once all callsites of a deprecated SQL function are enumerated, Atlas systematically migrates each one with a focus on safety and traceability. For every identified callsite, Atlas creates a distinct entry using the `todowrite` tool, such as `atlas todowrite add "Migrate call to old_function in sql/reports/daily_sales.sql"`. This ensures that partial progress is visible and no callsite is silently skipped. The actual migration of each callsite is performed by the `apply_patch` tool. Atlas generates a context-anchored patch for each modification, which includes not only the `old_lines` to be replaced but also surrounding context lines. When `atlas apply_patch` attempts to modify a file like `sql/views/customer_data.sql`, it first verifies that the expected `old_lines` and their context are present. If the file has drifted or been modified by another process, `apply_patch` will throw a `Failed to find expected lines` error, preventing a misapplication of the patch. This robust mechanism ensures that changes are only applied when the exact expected state is found, providing a high degree of safety for your critical SQL codebase, including schema definitions and `Flyway migrations` scripts.

How Atlas validates SQL changes with pgTAP after each migration?

Validating SQL changes immediately after each modification is crucial for maintaining code integrity, a process Atlas automates in 2026 by integrating with `pgTAP`. After migrating a callsite in a `.sql` file, Atlas uses its `bash` tool to execute the relevant `pgTAP` tests, ensuring that the replacement API functions correctly and does not introduce regressions into your database logic.

After Atlas applies a patch to migrate a SQL callsite, it immediately validates the change by running the affected tests. This is achieved through the `bash` tool, which allows Atlas to execute arbitrary shell commands, including your `pgTAP` test suite. For example, if a change is made to `sql/functions/new_api.sql` that affects `sql/views/user_profiles.sql`, Atlas will execute a command like `atlas bash --command "pg_prove tests/user_profiles_test.sql"`. This ensures that the newly introduced API or the refactored callsite behaves as expected and does not break existing functionality. Only once the `pgTAP` tests pass successfully for the modified file is the corresponding `todowrite` entry marked as completed. This iterative test-and-verify approach, performed after each individual file modification, significantly reduces the risk of introducing bugs and provides immediate feedback on the correctness of the migration, ensuring the stability of your SQL codebase and `Flyway migrations`.

How Atlas ensures a complete SQL API migration and final cleanup?

Ensuring a complete migration of a deprecated SQL API is the final, critical step, which Atlas facilitates in 2026 by confirming zero remaining usages and automating cleanup. After all callsites are migrated and validated, Atlas performs a final `grep` search across the entire codebase to confirm the deprecated symbol is entirely removed, then assists in deleting the old implementation.

The migration workflow concludes with a rigorous verification to ensure that the deprecated SQL API has been entirely removed from the codebase. After all `todowrite` entries are marked complete and all `pgTAP` tests have passed, Atlas performs a final, comprehensive `grep` search for the deprecated symbol's name across all `.sql` files, `Flyway migrations`, and any other relevant database scripts. This final `grep` acts as a safeguard, catching any obscure or dynamically generated references that might have been missed during the initial enumeration or subsequent migration steps. The goal is to confirm zero remaining hits for the deprecated symbol. Once this confirmation is made, Atlas can then assist in deleting the old implementation file, such as `functions/deprecated_function.sql`, or removing the deprecated code block from a larger file. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, allowing for a clean, atomic commit that fully removes the deprecated API and its associated code, leaving your SQL codebase in a clean, modernized state.

What are Atlas's safety and review mechanisms for SQL refactoring?

Atlas incorporates multiple safety and review mechanisms to protect your SQL codebase during refactoring tasks in 2026, ensuring changes are intentional and verified. Every Atlas tool call is permission-gated, plans are drafted in a read-only agent, and all file edits are presented as unified diffs for explicit approval, providing robust control over your `Flyway migrations` and `.sql` files.

Atlas is designed with several layers of safety and review to give SQL developers confidence when performing complex refactoring tasks like API migrations. Firstly, every tool call made by Atlas, whether it's `lsp`, `grep`, `todowrite`, `apply_patch`, or `bash`, is permission-gated against allow, ask, and deny rules, ensuring that no action is taken without explicit or pre-approved consent. Secondly, Atlas drafts a comprehensive plan in a read-only plan agent, presenting the entire sequence of proposed actions before switching to a build agent that can make modifications. This allows developers to review the strategy for migrating SQL files like `sql/procedures/process_order.sql` or `migrations/V2_0_0__refactor_api.sql` before execution. Thirdly, for every file edit, Atlas computes a unified diff and surfaces it for approval. This visual representation of changes, similar to a `git diff`, allows developers to meticulously inspect every line modification before Atlas writes to disk. Furthermore, Atlas snapshots file changes as git patches, enabling easy diffing and rolling back of edits if necessary. Atlas also connects to Model Context Protocol servers and exposes their tools to the agent, enhancing its understanding and interaction with the SQL environment, all while keeping code off third-party servers by building its code index with local Ollama embeddings.

Step by step

01Run Atlas in your SQL repository, ensuring it can read your `.sql` files, schema, and `Flyway migrations` history.
02Enumerate all callsites of the deprecated SQL symbol (e.g., `public.old_function`) using `atlas lsp findReferences --symbol "public.old_function"` and cross-check with `atlas grep "old_function"` for dynamic usages.
03Create a `todowrite` entry for each identified callsite, such as `atlas todowrite add "Migrate call in sql/views/my_report.sql"`, to track progress.
04For each `todowrite` entry, use `atlas apply_patch` to migrate the callsite in the target `.sql` file (e.g., `sql/views/my_report.sql`), reviewing the unified diff for approval.
05After each file modification, run the affected `pgTAP` tests using `atlas bash --command "pg_prove tests/my_report_test.sql"` to validate the change.
06Mark the `todowrite` entry as complete only after the `pgTAP` tests pass successfully for that file.
07Once all callsites are migrated, perform a final `atlas grep "old_function"` across the entire codebase to confirm zero remaining usages of the deprecated SQL symbol.
08Delete the old SQL implementation file (e.g., `functions/old_function.sql`) and use Atlas to stage and commit the changes, creating a clean `git` commit.

Frequently asked questions

How does Atlas ensure it finds all SQL calls to a deprecated function?: Atlas employs a dual-pronged approach to find all SQL calls to a deprecated function. It uses the `lsp` tool's `findReferences` operation, which leverages AST declarations from tree-sitter to semantically identify explicit calls within `.sql` files and `Flyway migrations`. This is fused with a `grep` search for the deprecated symbol's name, which catches dynamic SQL constructions or string-based usages that might not be visible to the language server, ensuring comprehensive enumeration.
Can Atlas handle SQL files that have changed since the initial scan?: Yes, Atlas is designed to handle drifted SQL files. When `atlas apply_patch` attempts to migrate a callsite, it uses a context-anchored patch. This means it verifies that the `old_lines` and their surrounding context, as expected by the patch, are still present in the target `.sql` file. If the file has changed and the expected context is not found, `apply_patch` will explicitly fail with `Failed to find expected lines` rather than guessing, preventing incorrect modifications to your `Flyway migrations` or other SQL assets.
How does Atlas integrate with existing SQL testing frameworks like pgTAP?: Atlas integrates direct with existing SQL testing frameworks like `pgTAP` through its `bash` tool. After each individual file modification during a migration, Atlas can execute specific `pgTAP` test commands, such as `pg_prove tests/my_function_test.sql`. This allows for immediate validation of the SQL changes. Only when these `pgTAP` tests pass successfully is the corresponding `todowrite` entry marked as complete, ensuring that every step of the migration maintains the functional correctness of your SQL codebase.
What safety measures does Atlas have before writing changes to SQL files?: Atlas implements several safety measures before writing changes to SQL files. All Atlas tool calls are permission-gated, requiring explicit approval. It drafts a read-only plan of action, allowing you to review the entire migration strategy. Crucially, for every proposed file edit, Atlas computes and surfaces a unified diff for your approval, letting you inspect every line change before it's written to disk. Atlas also snapshots file changes as `git` patches, providing a rollback mechanism.
Does Atlas support SQL schema migrations managed by tools like Flyway?: Yes, Atlas fully supports SQL schema migrations managed by tools like `Flyway migrations`. Atlas is designed to run in a repository containing your `.sql` files and migration history. It can read your schema and migration files, understanding the context of your database. When migrating a deprecated API, Atlas will identify callsites within `Flyway migrations` scripts (e.g., `migrations/V1_0_0__initial_schema.sql`) and apply changes with the same precision and safety as it would to any other `.sql` file, ensuring your migration history remains consistent.
Can Atlas help with the final cleanup and commit of the SQL migration?: Absolutely. After all callsites of the deprecated SQL API are migrated and validated, Atlas assists with the final cleanup. It performs a conclusive `grep` search to confirm zero remaining usages of the deprecated symbol. Once confirmed, Atlas can help delete the old implementation file. Furthermore, Atlas reads `git` branches, status, and diffs, and can stage and create commits on your behalf, allowing you to finalize the entire migration with a clean, atomic `git` commit that fully removes the deprecated API from your SQL codebase.

Try Atlas in your terminal

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

Install Atlas

Related guides

Migrate a Deprecated API Across Every Callsite with Atlas (2026 Workflow)

How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.

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.

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.

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.

Debug a single failing test in SQL with Atlas in 2026

Debug a single failing SQL test with Atlas in 2026. Use Atlas to pinpoint issues in pgTAP tests, navigate your SQL codebase, and fix production code efficiently. Get precise diffs and approvals.

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.

Onboard to an Unfamiliar SQL Codebase with Atlas in 2026

Rapidly build a mental model of any SQL repository in 2026 using Atlas. Leverage semantic search, explore Flyway migrations, and understand pgTAP tests without reading every file.

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.

Browse this resource hub