Postgres Hints

Plain-English hints for common Postgres SQL errors. 100% local.

Postgres Hints underlines likely mistakes in .sql files as you type and explains each one in plain English. It never connects to a database. It reads the CREATE TABLE statements in your workspace to learn your tables and columns.

The 5 errors it catches

1. Table doesn't exist (42P01 relation does not exist)

SELECT id FROM userz;

Table 'userz' not found. Check spelling, schema qualification (schema.table), or case sensitivity. Postgres folds unquoted names to lowercase — 'Users' and users are different.

2. Column doesn't exist (42703 column does not exist)

SELECT id, emial FROM users;

Column 'emial' not found. Check the column name, table alias, or case. Postgres folds unquoted names to lowercase.

3. Syntax error (syntax error at or near "x")

SELECT id, email, FROM users;

Syntax error near 'FROM'. Common causes: missing comma, unbalanced parentheses, or a reserved word used as an identifier. Check the line above.

Also catches unbalanced parentheses, unclosed quotes, and missing commas between selected columns.

4. Alias never defined (missing FROM-clause entry for table "x")

SELECT u.email FROM users;

Table alias 'u' is referenced but never defined. Add 'u' to your FROM or JOIN clause.

5. Comparing incompatible types (42883 operator does not exist)

SELECT id FROM users WHERE email = 5;

Cannot compare text and integer. Add an explicit cast: column::type or use the correct literal type. Example: WHERE email = 'a@b.com' (not email = 5) if email is text.

This fires when a text, uuid, date, timestamp or boolean column is compared with a bare number, or when two columns of incompatible types are compared. Quoted values never trigger it, because Postgres converts them to the column's type: id = '5' and created_at > '2024-01-01' are fine.

How it learns your schema

Postgres Hints reads CREATE TABLE statements from the .sql files in your workspace (skipping node_modules), plus any in the file you're editing, even before you save. It updates when .sql files are created, changed, or deleted.

• Unquoted names are folded to lowercase; quoted names ("Users") keep their case, as in Postgres.
• IF NOT EXISTS and schema-qualified names (public.users) are understood.

If no CREATE TABLE is found, checks 1, 2 and 5 are off. Checks 3 (syntax) and 4 (undefined alias) still run, because they don't need a schema.

What it does NOT do

• It is not a full SQL parser. It uses pattern checks, so it can miss errors and occasionally flag valid SQL.
• It never connects to a database, so it only knows the tables defined in your .sql files.
• ALTER TABLE and views aren't read. A column added with ALTER TABLE ... ADD COLUMN will show as "not found".
• Schemas aren't kept separate: public.users and other.users are both treated as users.
• An implicit column alias without AS (SELECT count(*) total) can trigger the syntax hint. Write count(*) AS total instead.
• It only catches these 5 errors.

Setting

Privacy

100% local. No database connection, no network calls, no telemetry, no account. Free.

Feedback

Found a wrong or missing hint? Open an issue: https://github.com/bzucker4/postgres-hints/issues

License

MIT