Skip to content

docs: Add analysis of model capitalization rename issue (#1708) #1726

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: Add analysis of model capitalization rename issue (#1708) #1726

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions CAPITALIZATION_FIX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Model Capitalization Issue - Analysis and Workaround

## Issue Description
When a dbt model file is renamed with only capitalization changes (e.g., `myModel.sql` → `MyModel.sql`), the dbt Power User extension may fail to run/compile the model because:

1. The extension correctly uses the new filename from the file system
2. However, dbt's manifest.json still contains the old model name with the old capitalization
3. dbt uses the manifest to find models, not the file system directly

## Root Cause
This is a limitation in how dbt handles model renames:
- dbt doesn't automatically detect file renames that only change capitalization
- The manifest.json needs to be rebuilt for dbt to recognize the new name
- The extension uses `basename(filepath, ".sql")` to extract model names, which gives the current filename, not the name in the manifest

## Current Workaround
When encountering this issue, users should:

1. Run `dbt parse` or `dbt compile` from the command line to rebuild the manifest
2. Or use the "dbt Power User: Rebuild Models" command in VS Code
3. The extension will then use the updated manifest with the correct model name

## Why a Code Fix is Complex
A proper fix would require:
1. The extension to maintain a mapping between file paths and manifest model names
2. Case-insensitive lookups when model names don't match exactly
3. Automatic manifest rebuilds when case-only renames are detected
4. Handling of models in subdirectories where the model name may include namespace prefixes

## Recommendation
For now, document this as a known limitation and educate users about the need to rebuild the manifest after renaming files with case-only changes.
Comment on lines +1 to +31
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Place documentation under documentation/docs/ per repo conventions

Project guidelines (see long-term learning) require every Markdown doc to live in an appropriate sub-directory of documentation/docs/.
Please move this file (or create an alias/index entry) so that the docs site can pick it up and avoid orphaned content.

🤖 Prompt for AI Agents 
In CAPITALIZATION_FIX.md lines 1 to 31, the documentation about the model
capitalization issue should be relocated under the documentation/docs/ directory
to comply with project conventions. Move the entire Markdown file or create an
alias/index entry within documentation/docs/ so that the documentation site can
properly include it and prevent orphaned content.

Loading