Skip to content

Add a lint warning for comparisons with NULL (#129) - #137

Merged
laaielichter merged 2 commits into
laaielichter:mainfrom
amritkang165:feat/null-comparison-lint
Nov 15, 2026
Merged

laaielichter merged 2 commits into
laaielichter:mainfrom
amritkang165:feat/null-comparison-lint

Conversation

@amritkang165

Copy link
Copy Markdown
Contributor

What and why

gulliver lint currently misses comparisons such as amount = NULL and amount != NULL. These evaluate to NULL rather than true, so they can silently prevent rows from matching.

This adds GV020 null-comparison as a warning for =, <> and != when either operand is a literal NULL. It also catches comparisons inside joins, CASE expressions and subqueries, while leaving IS NULL, IS NOT NULL, NULL-safe comparisons and IN (1, NULL) alone. The warning suggests the appropriate NULL predicates without applying an autofix, since replacing the comparison can change the result.

The rule is included in gulliver rules, the README, agent docs, skill table and changelog. It uses the existing file-location, inline-ignore and severity configuration support. GV019 is reserved by #125, so this uses GV020 as requested in the issue.

Fixes #129

How it was tested

On macOS arm64 with Python 3.14.7:

  • Added 47 regression cases covering both operand orders, four SQL dialects, nested comparisons, valid alternatives, rule metadata, no autofix, file positions, inline ignores and configuration.
  • Before the fix, the new tests reported 38 failures and nine passing negative cases. With the fix, python -m pytest -q tests/test_lint.py tests/test_lint_report.py passes all 183 tests.
  • python -m pytest -q — 918 passed, 10 skipped. No live PostgreSQL test database was configured.
  • ruff check . — passes.
  • README / AGENTS.md updated if behaviour changed.

Also checked the CLI directly: amount = NULL reports GV020, while amount IS NULL stays clean. Linux and Windows validation is left to the repository's CI matrix.

@laaielichter laaielichter left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Welcome to Gulliver, @amritkang165, and thank you for #137. This is a careful first PR: the rule is small and readable, the 47 tests cover both operand orders, four dialects, nested comparisons, the negative cases, file positions, inline ignores and [lint] config, and the PR text is honest about what was and was not run. You commented on #129 at 13:17, before opening the PR, nobody else had claimed it, so it is yours and I have assigned it to you.

Two small things need fixing before it can merge (one is a real bug in a supported dialect), plus a few suggestions.

What I checked. I merged 7bc19dc onto current main (c48adf8; it is a fast-forward, no conflicts) in a scratch worktree with a fresh venv:

  • ruff check .: all checks passed
  • pytest -q: 918 passed, 10 skipped (the skips need a live Postgres)
  • gulliver rules --format markdown against the README table: identical, so the README row is correct and GV019 is correctly left free for #125
  • gulliver rules lists GV020 null-comparison (warn); rule_docs() has it with autofix none; fix leaves it alone
  • File mode (gulliver lint q.sql) reports q.sql:3:7 for a three-line query, and skips an UPDATE ... SET amount = NULL in the same file (it is not a read), so no false positive there
  • I also ran 24 realistic queries through lint(): = NULL, <> NULL, != NULL, NULL = x, in JOIN ... ON, CASE WHEN, a NOT IN subquery, a GROUP BY query and x IS NULL OR x = NULL (one finding, correct) all warn; IS NULL, IS NOT NULL, IS NOT DISTINCT FROM NULL, status = 'NULL' (string literal), IN (1, NULL), MySQL <=> NULL, Snowflake EQUAL_NULL(x, NULL), COALESCE/NULLIF, x = CAST(NULL AS INT) and a CTE column that happens to be NULL do not. I found no false positives.

Please fix

  1. In BigQuery the message loses the column. gulliver lint --dialect bigquery "SELECT event_id FROM events WHERE amount = NULL LIMIT 5" prints NULL is never true: a comparison with NULL gives NULL. (and the same for NULL = amount and for u.deleted_at = NULL in a join). The cause is comparison.sql(dialect=dialect): sqlglot's BigQuery generator writes x = NULL as just NULL. The other three dialects print amount = NULL is never true.... The test only asserts "never true" in finding.message, which is why it passes. One way to fix it: build the text from the two operands, for example f"{comparison.this.sql(dialect=dialect)} {op} {comparison.expression.sql(dialect=dialect)}", and tighten the test to assert that amount is in the message for every dialect. This also lets you print the operator the user wrote: amount != NULL currently shows as amount <> NULL (that part is only cosmetic, see 4).
  2. A before/after SQL example in the docs. The rule table and the changelog line are there, but a reader who sees GV020 has nowhere to read why = NULL returns nothing. docs/features/lint-ci.md has a ## GV015 fan-trap (new rule) section: please add a short ## GV020 null-comparison section in the same style, with the before and after from #129 (WHERE amount = NULL returns no rows; WHERE amount IS NULL finds the rows without an amount), when IS NOT DISTINCT FROM is the right choice, and the -- gulliver: ignore GV020 line.

Suggestions, not blocking

  1. The CHANGELOG line sits at the very top of ### Added, which is where several other open PRs also add theirs (#65, #105 and #100/#101 already conflict with main there). Putting it at the end of the ### Added list, just above ### Thanks, avoids a "keep both lines" merge for whoever lands second.
  2. NULL = NULL and x = (NULL) are flagged, which is right. A one-line test for != that checks the message uses the operator the user wrote would be nice once 1 is done.
  3. CASE x WHEN NULL THEN ... (simple CASE) has the same problem but is a different AST node and is not flagged. That is fine for this issue; if you like, mention it in the PR as a possible follow-up.

CI: the ci and codeql runs for this commit are action_required. That is GitHub holding a first-time contributor's first run until the maintainer approves it, so no check has run on GitHub yet; the results above are from my own run. You do not need to do anything for that.

Once 1 and 2 are pushed I will look again, and I expect it to be ready then.

For a next one, if you enjoyed working with sqlglot: #128 (SQL syntax errors show sqlglot's internal Token repr, and the next_step talks about statement types instead of the syntax error) is a free good first issue; comment on it to get it assigned.

If Gulliver is useful to you, a ⭐ helps other people find it.


Generated by Claude Code

@amritkang165

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed review. The warning now renders the two operands separately, so BigQuery keeps the column name and operand order. The tests now check the complete message across all four dialects, with additional cases for qualified columns in joins.

I also added the GV020 section with before/after SQL, NULL-safe equality guidance and an ignore example, and moved the changelog entry to the end of Added.

The optional operator-spelling change is left out for now: SQLGlot represents both != and <> as the same NEQ node, so the message still uses <>. Simple CASE with WHEN NULL remains a possible follow-up.

Validation: 930 tests passed, 10 skipped because no live PostgreSQL test database is configured; Ruff passes.

@laaielichter laaielichter left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

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

Thank you @amritkang165, both points are fixed and this is ready to merge.

What I checked. I merged 35ce18f onto current main (c48adf8, no conflicts) in a scratch worktree with a fresh venv:

  • ruff check .: all checks passed
  • pytest -q: 930 passed, 10 skipped (the skips need a live Postgres)
  • gulliver rules --format markdown against the README table: identical

The two requested fixes

  1. BigQuery message. amount = NULL, NULL = amount, u.deleted_at = NULL in a join and amount != NULL now print their operands in all four dialects (duckdb, postgres, bigquery, snowflake), for example amount = NULL is never true: a comparison with NULL gives NULL. The tests now assert the exact message for every dialect, plus a separate join-operand test, so the old loss of the column cannot come back unnoticed. Building the text from the two operands was a good fix.
  2. Docs. docs/features/lint-ci.md has a ## GV020 null-comparison section with the before and after (= NULL returns no rows, IS NULL finds them), when IS NOT DISTINCT FROM is the right choice, the no-autofix reason and the -- gulliver: ignore GV020 line. I also ran that ignore example through file lint: the GV020 finding is suppressed.

You also moved the CHANGELOG line to the end of ### Added, which keeps the merge simple, and llms.txt and the skill table mention the rule.

Two tiny notes, neither blocks the merge: != is printed as <> (the test pins that, so it is a deliberate choice), and simple CASE x WHEN NULL is still not flagged. That would make a nice follow-up if you ever want one.

CI: the ci and codeql runs for 35ce18f are action_required. That is GitHub holding a first-time contributor's run until the maintainer approves it, so nothing has run on GitHub yet; the results above are from my own run. You do not need to do anything.

Thanks again for a careful first contribution. I will list you under Thanks in the CHANGELOG when it lands.


Generated by Claude Code

@laaielichter
laaielichter merged commit df9bcc4 into laaielichter:main Nov 15, 2026
14 checks passed

Copy link
Copy Markdown
Owner

Merged. Thank you @amritkang165! The new GV020 null-comparison rule catches = NULL and <> NULL in joins, CASE expressions and subqueries while leaving IS NULL and IN (1, NULL) alone, and the before/after SQL in the docs plus the clear note on why there is no autofix make it easy to adopt. Thanks too for the careful follow-up after review.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Lint rule: col = NULL and col <> NULL are never true, so the query scans the table and returns nothing

2 participants