Query rules

rules() checks every query before it's sent and reports what looks wrong. It runs before every other plugin, pre ones included and whatever the use() order, so it sees the query you wrote, before the tenant or soft-delete plugins add their filters.

import { recommended, rules } from "better-supabase/plugins/rules";

export const betterSupabase = defineSupabase(schema).use(
  rules({ rules: recommended() }),
);

A warn violation goes to console.warn and the query runs. An error violation fails the call with invalid_request, and nothing is sent.

PresetsCopy Anchor Link

Spread a preset to change single rules:

rules({
  rules: {
    ...recommended(),
    maxLimit: ["error", 200],
    noUnboundedFindMany: "off",
  },
});

RulesCopy Anchor Link

noUnboundedFindMany skips aggregate(), and maxLimit doesn't count the extra row paginate() reads to know whether there is a next page. requireTenantContext reads the same claim paths as the tenant() plugin, so a tenant in app_metadata counts. requireMaxAffected is only in strict(); add it to another preset with requireMaxAffected: ["error", 500].

noSensitiveSelect looks at the columns actually selected by reads, includes too. A select that leaves the column out passes; to read it on purpose:

await db.contacts.findMany({
  select: ["id", "email"],
  limit: 50,
  sensitive: true,
});

Writes don't trip the rule: without a select, create, update and upsert return every column except the sensitive ones. Name the column in select, or pass sensitive: true, to get it back.

The repository already refuses deleteMany without where on its own, so noDeleteManyWithoutWhere only catches deletes built by other plugins. The lint rule of the same name catches the call in your editor.

storagePathColumns only compares against bucket templates with a literal part besides / ({organizationId}/{customerId}/logo/{version}.webp, not {userId}/{file}), so a website_url holding example.com/about isn't mistaken for an object.

ReportingCopy Anchor Link

rules({
  rules: recommended(),
  report: (violation) => logger.warn(violation),
});

A violation has rule, level, table, operation and message. Errors still fail the call after report runs.

Skipping pluginsCopy Anchor Link

db.$withoutPlugins() returns the same connection with no plugins at all: no rules, tenant scoping, soft-delete filters or executor wrappers. Use it for migrations and admin scripts, never for user requests. Pass { keep: ['otel'] } to keep tracing (or any plugin by name); a name that isn't installed throws, so a typo can't drop a plugin silently.