How does Atlas handle renaming a dbt macro definition and its calls?

Atlas uses its `lsp` tool to semantically identify the macro definition and all its invocations across your dbt project. It then applies the rename using the `edit` tool, ensuring all `{{ old_macro_name(...) }}` calls are updated to `{{ new_macro_name(...) }}`.

Can Atlas rename a column referenced in a `schema.yml` test?

Yes, Atlas's `grep` tool will identify the column name within `schema.yml` descriptions and tests (e.g., `not_null`, `unique`). The `edit` tool will then update these references, ensuring your dbt schema tests remain valid after the rename.

What if a dbt model name is changed? Will `ref()` calls update?

Absolutely. When a dbt model name changes, Atlas's `lsp` tool will find all `ref('old_model_name')` calls throughout your project. The `edit` tool will then update these to `ref('new_model_name')`, maintaining the integrity of your dbt DAG.

How does Atlas prevent accidental renames in dbt comments or strings?

Atlas uses a two-pronged approach: `lsp` for semantic code references and `grep` for text. The `edit` tool's `replaceAll` operation is designed to be unambiguous per file, and Atlas presents all changes as diffs for your approval, allowing you to catch and reject any unintended modifications before they are written to your dbt files.

Does Atlas run `dbt build` during the rename process?

Atlas can run `dbt build` against your development target, but only behind a permission prompt. It will never run against a production target without explicit, permission-gated instructions, ensuring safety for your dbt environment.

Can Atlas rename a variable used in `dbt_project.yml`?

Yes, Atlas's `grep` tool will identify the variable name within `dbt_project.yml` or other configuration files. The `edit` tool can then update these occurrences, ensuring consistency across your dbt project's configuration.

How does Atlas ensure dbt code style is maintained after a rename?

After performing the renaming operations, Atlas uses its `bash` tool to automatically run `sqlfmt` on all modified SQL files. This ensures that your dbt models and macros adhere to your project's defined SQL formatting standards, maintaining code consistency.

Rename a symbol across the repo in dbt with Atlas in 2026

To rename a function, class, or constant everywhere it is used in a dbt project, including references that `grep` alone would miss or wrongly match, Atlas leverages its `lsp` tool to find authoritative references, `grep` for non-code occurrences, and `edit` for safe, mechanical replacements. This process ensures that `ref()` calls, macro definitions, and `schema.yml` configurations are updated correctly, followed by validation with `dbt test` and `sqlfmt` to maintain code quality and integrity.

How Atlas identifies all dbt symbol references for renaming

In 2026, renaming a dbt symbol like a macro or a column requires more than simple text search. Atlas uses its `lsp` tool to query the language server for true reference sets, ensuring that all `ref()` and `source()` calls, as well as macro definitions, are accurately identified.

Atlas begins the symbol renaming workflow by invoking its `lsp` tool's `findReferences` operation. This is crucial for dbt projects because it leverages the language server's deep understanding of the code's structure, including the complex interdependencies created by `ref()` and `source()` calls between models, and the usage of custom macros. Unlike a naive text search, `lsp` accurately identifies all programmatic usages of a symbol, distinguishing between a variable name and a comment, or a macro call versus a string literal. This initial step provides an authoritative list of where the symbol is actually used within the dbt project's logical graph, preventing missed updates in critical areas like `models/` directories or `macros/` files.

Catching non-code dbt references with Atlas's grep tool

After identifying programmatic references, Atlas employs its `grep` tool to find occurrences of the old symbol name in non-code contexts. This includes descriptions in `schema.yml` files, comments within SQL models, or configurations in `dbt_project.yml`, ensuring a 360-degree rename coverage in 2026.

While the `lsp` tool handles code-level references, many dbt projects contain the symbol name in documentation, comments, or configuration files that the language server might not index for semantic references. Atlas addresses this by running its `grep` tool for the old symbol name. This step is vital for catching occurrences in `schema.yml` files (e.g., column descriptions, model descriptions), SQL comments within `models/*.sql` files, or even in `dbt_project.yml` where a symbol might be part of a variable or a custom configuration. This hybrid approach of `lsp` and `grep` ensures that the rename is truly comprehensive, leaving no trace of the old symbol behind in any part of the dbt codebase.

Safe and precise mechanical renaming in dbt with Atlas edit

Atlas performs the mechanical renaming using its `edit` tool, which applies `replaceAll` for unambiguous matches across dbt files. For instance, if renaming a column `old_id` to `new_id` in 15 SQL models, Atlas ensures each replacement is precise and prevents unintended changes by refusing ambiguous single replacements.

The core mechanical renaming is executed by Atlas's `edit` tool. For widespread, unambiguous changes, `edit` uses `replaceAll` to update all identified occurrences of the old symbol name with the new one. This is particularly powerful in dbt, where a single column name might appear in dozens of `select` statements, `where` clauses, or `group by` expressions across multiple `models/*.sql` files. A key safety feature of Atlas's `edit` tool is its strictness: it refuses ambiguous single replacements. If `edit` finds multiple matches for `oldString` in a file but is instructed to make a single change, it will throw an error unless explicit context is provided or `replaceAll` is opted into. This prevents silent corruption of dbt SQL files, ensuring that a rename operation does not inadvertently alter unrelated text that happens to contain the old symbol's substring.

Validating dbt renames with dbt test and sqlfmt

After the renaming operations, Atlas uses its `bash` tool to execute `dbt test` and `sqlfmt`, ensuring the dbt project remains functional and adheres to coding standards. This critical validation step confirms that the 2026 refactor has not introduced any regressions or formatting issues.

Once Atlas has completed the mechanical renames, it moves to a crucial validation phase using its `bash` tool. First, it runs `dbt test` to execute all defined schema tests and data tests across the dbt project. This immediately flags any broken references, incorrect column names, or data integrity issues that might have resulted from the rename. For example, if a `not_null` or `unique` test on a renamed column was missed, `dbt test` would fail. Second, Atlas runs `sqlfmt` to automatically reformat all modified SQL files. This ensures that despite the changes, the codebase maintains consistent styling, which is vital for collaboration and readability in dbt projects. Finally, Atlas performs one more `grep` for the old name to definitively prove zero remaining hits, providing a robust verification of the entire renaming process.

Atlas's safety and review mechanisms for dbt refactoring

Atlas incorporates multiple safety mechanisms for dbt refactoring, including a read-only plan agent and unified diffs for every file edit. Before any changes are written, Atlas presents a comprehensive diff for approval, ensuring that a dbt developer in 2026 has full control over the modifications.

Atlas prioritizes safety and developer control throughout the renaming process. Before making any modifications, Atlas drafts a plan in a read-only plan agent and asks for approval. This allows the dbt developer to review the proposed steps without any risk of accidental changes. Every file edit Atlas proposes is accompanied by a computed unified diff, which is surfaced for explicit approval. This granular control means that a developer can see exactly what changes will be applied to `models/*.sql`, `schema.yml`, or `dbt_project.yml` files. Furthermore, Atlas connects to Model Context Protocol servers and exposes their tools, and it snapshots file changes as git patches, allowing edits to be easily diffed and rolled back if necessary. This multi-layered review process ensures that even complex refactoring operations in dbt are performed with confidence and transparency.

Step by step

01Run `atlas` in your dbt project directory containing `dbt_project.yml` and `models/`.
02Ask Atlas to rename your dbt symbol (e.g., 'Rename the macro `old_macro_name` to `new_macro_name` across the repo').
03Atlas will use its `lsp` tool to find all programmatic references (e.g., `ref()` calls, macro invocations) and its `grep` tool to find non-code occurrences (e.g., `schema.yml` descriptions).
04Review Atlas's proposed plan in the read-only agent, then approve to proceed with the `edit` tool's `replaceAll` operations.
05Approve the unified diffs presented by Atlas for each file change, ensuring accuracy in `models/*.sql` and `schema.yml` files.
06Atlas will use its `bash` tool to run `dbt test` to validate the refactor and `sqlfmt` to reformat affected SQL files.
07Atlas will perform a final `grep` for the old symbol name to confirm zero remaining hits, then present the results.

Frequently asked questions

How does Atlas handle renaming a dbt macro definition and its calls?: Atlas uses its `lsp` tool to semantically identify the macro definition and all its invocations across your dbt project. It then applies the rename using the `edit` tool, ensuring all `{{ old_macro_name(...) }}` calls are updated to `{{ new_macro_name(...) }}`.
Can Atlas rename a column referenced in a `schema.yml` test?: Yes, Atlas's `grep` tool will identify the column name within `schema.yml` descriptions and tests (e.g., `not_null`, `unique`). The `edit` tool will then update these references, ensuring your dbt schema tests remain valid after the rename.
What if a dbt model name is changed? Will `ref()` calls update?: Absolutely. When a dbt model name changes, Atlas's `lsp` tool will find all `ref('old_model_name')` calls throughout your project. The `edit` tool will then update these to `ref('new_model_name')`, maintaining the integrity of your dbt DAG.
How does Atlas prevent accidental renames in dbt comments or strings?: Atlas uses a two-pronged approach: `lsp` for semantic code references and `grep` for text. The `edit` tool's `replaceAll` operation is designed to be unambiguous per file, and Atlas presents all changes as diffs for your approval, allowing you to catch and reject any unintended modifications before they are written to your dbt files.
Does Atlas run `dbt build` during the rename process?: Atlas can run `dbt build` against your development target, but only behind a permission prompt. It will never run against a production target without explicit, permission-gated instructions, ensuring safety for your dbt environment.
Can Atlas rename a variable used in `dbt_project.yml`?: Yes, Atlas's `grep` tool will identify the variable name within `dbt_project.yml` or other configuration files. The `edit` tool can then update these occurrences, ensuring consistency across your dbt project's configuration.
How does Atlas ensure dbt code style is maintained after a rename?: After performing the renaming operations, Atlas uses its `bash` tool to automatically run `sqlfmt` on all modified SQL files. This ensures that your dbt models and macros adhere to your project's defined SQL formatting standards, maintaining code consistency.

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 dbt: Terminal-Native AI Coding in 2026

Atlas is a terminal-native AI coding agent for dbt. Read the ref() DAG, convert a table model to incremental, run dbt build against dev, and add tests in 2026.

Locate where a behavior is implemented in dbt with Atlas in 2026

Discover how Atlas helps dbt developers in 2026 pinpoint exact file and symbol locations for specific behaviors, leveraging semantic search, grep, and LSP tools across your dbt project.

Audit a dbt Repository with Parallel Subagents in Atlas in 2026

Sweep your dbt project for issues without context window limits. Atlas uses parallel subagents to audit `dbt_project.yml` and `schema.yml` files, leveraging `dbt test` and `sqlfmt` for comprehensive review.

Onboard to an Unfamiliar dbt Codebase with Atlas in 2026

Atlas helps dbt developers in 2026 quickly build a mental model of new repositories. Leverage semantic search, `ref()` analysis, `dbt test`, and `sqlfmt` to understand complex dbt projects without reading every file.

Document a dbt Module with a README in 2026 using Atlas

Atlas helps dbt developers in 2026 generate accurate READMEs for modules by reading live code, ensuring documentation reflects current behavior. It leverages dbt's own toolchain, including dbt test for verification and

Research a Third-Party API Before Integrating it in dbt with Atlas in 2026

Learn how dbt developers use Atlas in 2026 to research external APIs, fetch documentation, and integrate new data sources with confidence, ensuring proper `ref()` calls and schema tests.

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

Streamline dbt project maintenance in 2026. Atlas automates GitHub issue and pull request triage, integrating with `dbt test`, `sqlfmt`, and `dbt deps (packages.yml)` for safe, trusted, and efficient dbt development

Browse this resource hub