postgresql/consistent-fk-not-valid

Why this matters

Adding a foreign key normally validates every existing row under an `ACCESS EXCLUSIVE` lock that blocks writers. The safe pattern is to `ADD ... NOT VALID` (metadata-only) and then `VALIDATE CONSTRAINT` in a separate migration; `VALIDATE` only takes a `SHARE UPDATE EXCLUSIVE` lock. Some projects prefer the inverse — fail loudly at constraint-add time — and can flip this rule with the `style` option.

Examples

ALTER TABLE orders
  ADD CONSTRAINT orders_customer_fk FOREIGN KEY (customer_id) REFERENCES customers (id);

ALTER TABLE orders
  ADD CONSTRAINT orders_customer_fk FOREIGN KEY (customer_id) REFERENCES customers (id) NOT VALID;

ALTER TABLE orders VALIDATE CONSTRAINT orders_customer_fk;

Configure it

// eslint.config.js
import postgresql from "eslint-plugin-postgresql";

export default [
  {
    files: ["**/*.sql"],
    languageOptions: {
      parser: postgresql.configs.recommended.languageOptions.parser,
    },
    plugins: { postgresql },
    rules: {
      "postgresql/consistent-fk-not-valid": [
        "warn",
        {
          style: "always",
        },
      ],
    },
  },
];

Options

style "always" | "never" default: "always"

`always` (default) requires `NOT VALID` on `ADD CONSTRAINT ... FOREIGN KEY`. `never` forbids it — useful for projects that want the constraint to immediately reject existing violations rather than waiting on a follow-up `VALIDATE CONSTRAINT`.