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

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).

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

JSON output

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.

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