postgresql/require-fk-include-columns

Why this matters

Useful in multi-tenant schemas where every FK must carry the tenant key (e.g. `tenant_id`) so a child row cannot point at a parent row in a different tenant. The rule covers inline column-level FKs (`col integer REFERENCES other(id)`), table-level FKs inside `CREATE TABLE`, and `ALTER TABLE ADD CONSTRAINT ... FOREIGN KEY`. The `columns` option is required and lists the column names that every FK must include. `excludeTablePattern` and `excludeReferencedTablePattern` are regex strings for opting tables out — typically the tenant table itself (`tenants`) and global lookup tables.

Examples

CREATE TABLE orders (
  tenant_id bigint NOT NULL,
  id        bigserial PRIMARY KEY,
  user_id   bigint REFERENCES users (id)
);

ALTER TABLE orders
  ADD CONSTRAINT orders_user_fk
  FOREIGN KEY (user_id) REFERENCES users (id);

CREATE TABLE orders (
  tenant_id bigint NOT NULL,
  id        bigint NOT NULL,
  user_id   bigint NOT NULL,
  PRIMARY KEY (tenant_id, id),
  FOREIGN KEY (tenant_id, user_id) REFERENCES users (tenant_id, id)
);

ALTER TABLE orders
  ADD CONSTRAINT orders_user_fk
  FOREIGN KEY (tenant_id, user_id) REFERENCES users (tenant_id, id);

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/require-fk-include-columns": [
        "warn",
        {
          columns: [],
          excludeTablePattern: "",
          excludeReferencedTablePattern: "",
        },
      ],
    },
  },
];

Options

columns string[]

Required. Column names that every foreign-key constraint must include in its referencing column list.

excludeTablePattern string (regex)

Skip the check for any table whose name matches this pattern. Useful for audit / log tables that intentionally fan in across tenants.

excludeReferencedTablePattern string (regex)

Skip the check for any FK whose referenced (`REFERENCES`) table matches this pattern. Typically used to exclude the tenant table itself and global lookup tables that are shared across tenants.