From 0.4 to 0.5

0.5 renames the SQL kit's tables and columns to one standard, makes the tenant checks fail closed and moves the kit's rows out of the schema diff. Most of it is a migration the CLI writes. The steps below follow the order to run them in. Modules that are new in 0.5 (access, organizations, profiles, outbox, webhooks-out, notifications, support and sessions) need no upgrade.

Upgrade the kit filesCopy Anchor Link

Update the package, then let the CLI write the forward steps and the new module files:

better-supabase sql upgrade
better-supabase sql sync
better-supabase sql data

sql upgrade writes <timestamp>_better_supabase_kit_upgrade.sql into the migrations folder next to config.toml. Create the schema migration after it (for example supabase db diff -f kit_0_5), so the renames run before the new definitions. sql data is new: it writes the kit's rows and role settings, which a schema diff can't capture, into a migration stamped after the newest one. See Upgrading modules.

The forward steps rename these objects:

better_supabase.audit_log stays as a read-only view with the old column names until 0.6. A renamed column has no wrapper, so update your own policies, views and functions that name org_id or at. Doctor reports them (BS309), also when the column appears unqualified next to its table.

audit(), purge_audit_log(), schedule_job() and purge_job_archive() gain parameters with defaults, and the forward steps drop the old overloads. Existing calls keep working; a grant or revoke that names the old argument list needs the new one.

The active tenantCopy Anchor Link

current_tenant_id() used to return the tenant_id claim as is. It now returns a tenant only while the caller is a member of it, and takes it from the source in kits.access.activeTenant, which defaults to 'resolver': the tenant the server resolved for the request (ServerOptions.tenant), then the claim. Apps that only write the claim keep working. To read only the claim, set it explicitly:

export default defineConfig({
  kits: { access: { activeTenant: "claim" } },
});

See The active tenant.

EntitlementsCopy Anchor Link

The entitlements module no longer assumes organizations.stripe_customer_id. With the managed organizations module it reads better_supabase.organizations.stripe_customer_id. Otherwise sql add stops until you name the column:

export default defineConfig({
  entitlements: { customer: "organizations.stripe_customer_id" },
});

Rate limits and other kit rowsCopy Anchor Link

rate-limit now sets pgrst.db_pre_request for the authenticator role in the migration sql data writes, when no other pre-request function is set. Doctor warns (BS313) when the live database doesn't call check_request(). Schedule the new purge_rate_limits() next to the other purges (see Retention).

Behavior that changedCopy Anchor Link

• idempotency scopes keys to the caller, so two users can no longer replay each other's responses.
• track_realtime refuses a table without the tenant column. List tables that have no tenant in realtime.global.
• jsonb-schemas adds each check not valid and validates it in a second statement, so checking existing rows doesn't block writes to the table.
• The rate limit and request_ip() use the right-most forwarded hop.
• jobs archives a message whose worker died on its last attempt, and dead letters get their own retention and replay_dead_job().

CloudEventsCopy Anchor Link

toCloudEvents and kitCloudEvent no longer set the actorid context attribute, which kept a user id in headers that brokers log. The actor is in data.actorId instead:

const actor = event.data.actorId; // was event.actorid

New doctor checksCopy Anchor Link

BS312 reports a kit schema exposed through the Data API, BS313 rate limits not wired to PostgREST, and BS314 a migration-only kit option. See doctor.