README
¶
colref
Check whether a database column is still referenced in your codebase before you delete it.
Why
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.
Installation
pip / pipx (Python users)
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 colref
Or with pip:
pip install colref
| OS | x86_64 (Intel/AMD) | arm64 |
|---|---|---|
| macOS | ✓ | ✓ (Apple Silicon) |
| Linux | ✓ | ✓ |
| Windows | ✓ | — |
gem (Ruby users)
If you are working on a Rails or Ruby project, install via gem. No Go installation required.
gem install colref
Homebrew (macOS and Linux)
brew install shinagawa-web/tap/colref
If you prefer to tap first:
brew tap shinagawa-web/tap
brew install colref
One-line installer (Linux and macOS)
curl -fsSL https://raw.githubusercontent.com/shinagawa-web/colref/main/install.sh | sh
Manual download
Pre-built binaries are available on the releases page.
For full installation options, see Getting started.
Usage
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) |
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
For ORM-specific behavior and more examples, see Django and Rails.
Limitations
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.
Roadmap
See issue #74.
License
MIT
Directories