Index Usability Verdict

You added the index. The query is still slow. `pg_stat_user_indexes` -- or `sys.dm_db_index_usage_stats`, or MySQL's `sys.schema_unused_indexes` -- says the index HAS NEVER BEEN USED.

The obvious read is "the index didn't help", so someone drops it, or adds a second one beside it, or gives up and adds a cache. ALL THREE MISS THE ACTUAL BUG: the index was never ELIGIBLE for this predicate in the first place. The query is correct. The index exists. The two structurally cannot meet, for one of a short and well documented set of reasons -- and none of them throw an error or show up in a lint pass. The plan quietly picks a scan instead of a seek, forever, and nothing about that is loud.

THIS IS A TRUTH TABLE OVER THAT GAP. You hand it the column's type and collation, the index's definition, and the shape of one predicate -- facts you already have from `information_schema`, `pg_index`, `SHOW CREATE TABLE` or `sys.indexes`, or from simply reading the query -- and it tells you whether they can meet, and if not, which documented reason applies.

The reasons are things like a function applied to the indexed column, a collation mismatch between column and index, an implicit type coercion on one side of the comparison, a leading-column gap in a composite index, and a LIKE pattern that is not left-anchored. Each is ordinary code that reviews cleanly.

IT REFUSES rather than guesses when a fact it needs is absent, naming the fact -- because the assumption that saves time is "the types probably match", and a silent coercion is the most common cause.

VERIFIED: 165 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function normalizeText(input: string): string;
  export function expressionsMatch(a: string, b: string): boolean;
  export function tryParseSimpleInequality(rawText: string): SimpleInequality | undefined;
  export function simpleInequalityImplies( indexPredicate: string, queryClause: string, ): boolean;
  export function evaluateIndexUsability(input: IndexUsabilityInput): IndexUsabilityResult;

  export type Dialect = "postgres" | "mysql" | "sqlserver";
  export type IndexMethod = "btree" | "hash" | "gin" | "gist" | "other";
  export type Verdict = "USABLE" | "NOT_USABLE" | "NOT_DETERMINABLE";