How does Atlas ensure a SQL rename doesn't break my database schema?

Atlas integrates with your existing `Flyway migrations` toolchain. After performing a rename, Atlas uses its `bash` tool to run `flyway migrate -validate`, ensuring that your schema remains consistent and that no migration scripts are broken by the symbol change. This validation step is crucial for maintaining database integrity.

Can Atlas rename a SQL function that's used in a complex view or stored procedure?

Yes, Atlas leverages the `lsp` tool, which understands the Abstract Syntax Tree (AST) of SQL code. This allows it to accurately identify all semantic usages of a SQL function, even within complex views, stored procedures, or triggers defined in files like `src/views/complex_view.sql` or `src/procs/my_procedure.sql`, ensuring a complete and correct rename.

What if the old SQL symbol name appears in comments or documentation?

Atlas addresses this by combining `lsp`'s semantic search with a `grep` pass. After `lsp` finds all code references, Atlas runs `grep` for the old symbol name. This catches instances in comments within `.sql` files, external documentation, or even `pgTAP` test descriptions, ensuring a truly comprehensive rename.

How does Atlas prevent accidental changes when renaming a common SQL keyword?

Atlas's `lsp` tool relies on the language server's semantic understanding, which distinguishes between a symbol's declaration/usage and a common keyword. Furthermore, the `edit` tool's `replaceAll` operation requires unambiguous matches per file, and Atlas surfaces a unified diff for every proposed change, allowing you to approve or reject specific edits to files like `db/functions/my_function.sql`.

Does Atlas support rolling back a SQL rename if something goes wrong?

Yes, Atlas snapshots file changes as git patches, allowing edits to be diffed and rolled back. Additionally, Atlas can read git branches, status, and diffs, and can stage and create commits on your behalf, providing robust version control integration for any SQL refactoring operation.

How does Atlas ensure the renamed SQL code adheres to my team's style guide?

Atlas integrates with your existing SQL toolchain. After a rename, Atlas can use its `bash` tool to run `sqlfluff format` across the affected `.sql` files. This ensures that all refactored code automatically conforms to your team's defined formatting rules, maintaining consistency throughout the codebase.

Can Atlas rename a SQL constant or variable used in `pgTAP` tests?

Absolutely. Atlas's `lsp` tool will identify semantic references to SQL constants or variables within your `pgTAP` test files, such as `test/my_constant_tests.sql`. Additionally, `grep` will catch any non-semantic mentions. The `edit` tool then applies the changes, and running `pgTAP` tests afterward verifies the refactor's success.

Rename a SQL Symbol Across Your Repo with Atlas in 2026

Atlas, the terminal-native AI coding agent, enables SQL developers in 2026 to rename a function, class, or constant across an entire repository, ensuring accuracy by leveraging the `lsp` tool for precise references, `grep` for broader matches, and `edit` for safe mechanical changes, all verified with `pgTAP` tests and `Flyway migrations`.

How Atlas finds all SQL symbol references for renaming

In 2026, Atlas uses its `lsp` tool to find all authoritative references for a SQL symbol, such as a function named `calculate_order_total`, by leveraging the language server's understanding of the Abstract Syntax Tree (AST) declarations. This method ensures that only true usages are identified, avoiding the pitfalls of simple text matching.

When renaming a SQL function like `old_customer_id_generator` to `new_customer_identifier_sequence`, Atlas first employs its `lsp` tool. This tool connects to the Model Context Protocol servers, exposing their capabilities to the agent. For SQL, this means Atlas can query the language server to perform a `findReferences` operation on the specified symbol. Unlike a naive text search, the `lsp` tool understands the semantic structure of SQL code, indexing declarations using tree-sitter. This allows it to accurately distinguish between a function call, a variable name, or a comment containing the same string, providing a precise list of all locations where `old_customer_id_generator` is actually used within your `.sql` files, including complex queries and stored procedures. This initial, highly accurate reference set is crucial for preventing unintended changes and ensuring the integrity of your `Flyway migrations` and application logic.

Catching SQL symbol mentions outside the type system with grep

After identifying precise SQL symbol references, Atlas runs `grep` to catch occurrences of the old name in places the language server might miss, such as comments, documentation, or configuration files like `flyway.conf`. This crucial second step ensures a comprehensive rename, covering all 2026 code and related assets.

While the `lsp` tool provides an authoritative list of code references for a SQL symbol like `legacy_audit_log_table`, many mentions exist outside the formal type system. Atlas addresses this by running `grep` for the old name. This step is vital for finding occurrences in SQL comments within `src/procedures/legacy_audit_log.sql`, documentation strings, or even in `pgTAP` test files like `test/legacy_audit_log_tests.sql` where the old name might appear in a test description. Furthermore, configuration files, such as `flyway.conf` or application-specific settings that reference SQL entities, are also scanned. The `grep` tool ensures that every instance of `legacy_audit_log_table` is considered for renaming, preventing lingering references that could cause confusion or errors after the primary code refactor. This hybrid approach, fusing semantic and keyword retrieval, provides a practical option for renaming.

Applying mechanical SQL renames with Atlas's edit tool

Atlas applies mechanical renames to SQL files using its `edit` tool, specifically employing `replaceAll` for unambiguous matches identified by both `lsp` and `grep`. This process ensures that a function like `old_data_processor` is consistently updated to `new_data_handler` across all relevant `.sql` files, with safety checks in place for 2026.

Once Atlas has compiled a comprehensive list of locations for a SQL symbol, such as `old_report_generator_function`, it uses the `edit` tool to perform the mechanical replacements. For instances where the match is unambiguous per file, Atlas utilizes `replaceAll` to update the old name to `new_report_builder_function`. The `edit` tool is designed with safety in mind: it refuses ambiguous single replacements. If `edit` finds multiple matches for `old_report_generator_function` in a file but is only instructed to change one, it will throw an error like 'Found multiple matches for oldString' unless explicit context is provided or `replaceAll` is opted into. This prevents silent corruption of your SQL code. Atlas computes a unified diff for every file edit, surfacing it for approval before writing, allowing developers to review changes to files like `db/migrations/V3__add_report_function.sql` or `src/views/monthly_reports.sql` before they are committed. This granular control ensures that every change is intentional and correct.

Verifying SQL refactoring with pgTAP, Flyway, and sqlfluff

After renaming a SQL symbol, Atlas uses the `bash` tool to compile and test the codebase, running `pgTAP` tests and validating `Flyway migrations` to confirm the refactor's success. This critical verification step, standard in 2026 SQL development, ensures no regressions were introduced by the changes.

The final and most critical step in renaming a SQL symbol with Atlas is verification. After all `edit` operations are complete, Atlas uses its `bash` tool to execute the standard SQL toolchain commands. This includes running your `pgTAP` tests with a command like `psql -d my_database -f test/all_tests.sql`, which will immediately flag any broken references or logical errors introduced by the rename. Atlas also validates `Flyway migrations` to ensure schema integrity, potentially by running `flyway migrate -validate`. Furthermore, `sqlfluff format` can be run to ensure code style consistency across the refactored files. Finally, Atlas performs one more `grep` for the old symbol name across the entire repository to definitively prove zero remaining hits. This comprehensive testing and verification process, combined with Atlas's ability to read git branches, status, and diffs, and stage/create commits, provides a high degree of confidence in the refactoring outcome, allowing developers to roll back edits if necessary via git patches.

Step by step

01Initialize Atlas in your SQL repository by running `atlas` and allowing it to read your schema, migration history, and query files.
02Use Atlas's `lsp` tool to find all authoritative references for the SQL symbol (e.g., a function `old_sql_function`) you intend to rename, leveraging the language server's AST understanding.
03Run Atlas's `grep` tool for `old_sql_function` to identify occurrences in comments, documentation, `pgTAP` test files (e.g., `test/function_tests.sql`), or `flyway.conf`.
04Apply mechanical renames using Atlas's `edit` tool with `replaceAll` for `old_sql_function` to `new_sql_function` across all identified `.sql` files, reviewing the unified diff for each change.
05Execute your `pgTAP` tests via Atlas's `bash` tool (e.g., `bash -c 'psql -d my_db -f test/all_tests.sql'`) to verify the refactor has not introduced regressions.
06Validate `Flyway migrations` using Atlas's `bash` tool (e.g., `bash -c 'flyway migrate -validate'`) to ensure schema consistency after the rename.
07Run `sqlfluff format` via Atlas's `bash` tool to maintain code style across the refactored SQL files.
08Perform a final `grep` for `old_sql_function` using Atlas's `grep` tool to confirm no lingering references remain in the codebase.

Frequently asked questions

How does Atlas ensure a SQL rename doesn't break my database schema?: Atlas integrates with your existing `Flyway migrations` toolchain. After performing a rename, Atlas uses its `bash` tool to run `flyway migrate -validate`, ensuring that your schema remains consistent and that no migration scripts are broken by the symbol change. This validation step is crucial for maintaining database integrity.
Can Atlas rename a SQL function that's used in a complex view or stored procedure?: Yes, Atlas leverages the `lsp` tool, which understands the Abstract Syntax Tree (AST) of SQL code. This allows it to accurately identify all semantic usages of a SQL function, even within complex views, stored procedures, or triggers defined in files like `src/views/complex_view.sql` or `src/procs/my_procedure.sql`, ensuring a complete and correct rename.
What if the old SQL symbol name appears in comments or documentation?: Atlas addresses this by combining `lsp`'s semantic search with a `grep` pass. After `lsp` finds all code references, Atlas runs `grep` for the old symbol name. This catches instances in comments within `.sql` files, external documentation, or even `pgTAP` test descriptions, ensuring a truly comprehensive rename.
How does Atlas prevent accidental changes when renaming a common SQL keyword?: Atlas's `lsp` tool relies on the language server's semantic understanding, which distinguishes between a symbol's declaration/usage and a common keyword. Furthermore, the `edit` tool's `replaceAll` operation requires unambiguous matches per file, and Atlas surfaces a unified diff for every proposed change, allowing you to approve or reject specific edits to files like `db/functions/my_function.sql`.
Does Atlas support rolling back a SQL rename if something goes wrong?: Yes, Atlas snapshots file changes as git patches, allowing edits to be diffed and rolled back. Additionally, Atlas can read git branches, status, and diffs, and can stage and create commits on your behalf, providing robust version control integration for any SQL refactoring operation.
How does Atlas ensure the renamed SQL code adheres to my team's style guide?: Atlas integrates with your existing SQL toolchain. After a rename, Atlas can use its `bash` tool to run `sqlfluff format` across the affected `.sql` files. This ensures that all refactored code automatically conforms to your team's defined formatting rules, maintaining consistency throughout the codebase.
Can Atlas rename a SQL constant or variable used in `pgTAP` tests?: Absolutely. Atlas's `lsp` tool will identify semantic references to SQL constants or variables within your `pgTAP` test files, such as `test/my_constant_tests.sql`. Additionally, `grep` will catch any non-semantic mentions. The `edit` tool then applies the changes, and running `pgTAP` tests afterward verifies the refactor's success.

Try Atlas in your terminal

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

Install Atlas

Related guides

Rename a Symbol Across the Repo with Atlas in 2026

How to rename a symbol across a repo with Atlas in 2026: findReferences gets the true reference set, grep catches strings and docs, and edit refuses ambiguous matches.

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.

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.

Review a Pull Request in SQL with Atlas in 2026

In 2026, SQL developers use Atlas to review pull requests, catching subtle bugs beyond line-by-line diffs. Atlas integrates with pgTAP and Flyway migrations for comprehensive SQL code review.

Automate GitHub Issue and Pull Request Triage in SQL with Atlas in 2026

Streamline GitHub issue and pull request triage for your SQL projects using Atlas. Automate responses, refactor queries, and manage Flyway migrations safely with a terminal-native AI agent.

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

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

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