Check whether a database column is still referenced in your codebase before you delete it.
You want to remove a column from a long-running system. The column looks unused, but you're not sure. A full-text search returns hits inside comments, test fixtures, and migration history — noise that makes it hard to tell whether the column is actually read or written in live code.
colref scans your codebase with an AST parser, skips comments and string literals, and tells you where the column is referenced. If it finds nothing, you have a concrete starting point for the deletion decision. The final call is yours.
If you are working on a Django or Python project, the easiest way to install colref is via pip or pipx. No Go installation required.
pipx install colrefOr with pip:
pip install colref| OS | x86_64 (Intel/AMD) | arm64 |
|---|---|---|
| macOS | ✓ | ✓ (Apple Silicon) |
| Linux | ✓ | ✓ |
| Windows | ✓ | — |
If you are working on a Rails or Ruby project, install via gem. No Go installation required.
gem install colrefbrew install shinagawa-web/tap/colrefIf you prefer to tap first:
brew tap shinagawa-web/tap
brew install colrefcurl -fsSL https://raw.githubusercontent.com/shinagawa-web/colref/main/install.sh | shPre-built binaries are available on the releases page.
For full installation options, see Getting started.
colref check --orm <orm> --model <Model> --field <field> [path]
path is the project root to scan (default: current directory).
| Flag | Description |
|---|---|
--orm |
ORM type: django, rails (required) |
--model |
Model name to look up (required) |
--field |
Field name to search for (required) |
--format |
Output format: text (default), json |
Example:
$ colref check --orm django --model Page --field seo_title
Scanning 932 files...
References found for Page.seo_title
wagtail/admin/tests/pages/test_create_page.py:1867 page.seo_title
wagtail/admin/tests/pages/test_create_page.py:1892 page.seo_title
Use --format json to emit a structured result you can pipe into other tools. In this mode stdout is pure JSON (no Scanning... preamble), so it is safe to pipe:
$ colref check --orm django --model Page --field seo_title --format json
{
"model": "Page",
"field": "seo_title",
"orm": "django",
"files_scanned": 932,
"reference_count": 2,
"references": [
{ "file": "wagtail/admin/tests/pages/test_create_page.py", "line": 1867, "text": "page.seo_title" },
{ "file": "wagtail/admin/tests/pages/test_create_page.py", "line": 1892, "text": "page.seo_title" }
]
}
When nothing is found, reference_count is 0 and references is an empty array [].
For ORM-specific behavior and more examples, see Django and Rails.
colref uses static AST analysis and cannot detect every reference pattern. References where the field name is constructed at runtime (e.g. getattr(obj, field_name)) are out of scope by design.
If colref reports no references, treat it as "none found by the scanner" — not as a guarantee the column is unused.
For the full per-pattern breakdown, see Detection patterns and Limitations.
See issue #74.
MIT