Extension interfaces

Every integration point is a small interface. The built-in behavior is one implementation of it, and yours can replace or sit next to it. Each interface has a conformance kit.

ExecutorCopy Anchor Link

Runs IR operations and returns a Result. It never throws for database errors, returns aborted when the signal is aborted, and keys rows by the selection's aliases (the configured casing).

import type { Executor } from "better-supabase";

export function kyselyExecutor(db: Kysely<Database>): Executor {
  return {
    name: "kysely",
    async execute(op, { signal, errorMappers }) {
      // compile op, run it, map errors with mapDbError(raw, errorMappers)
    },
  };
}

const db = betterSupabase.connect(kyselyExecutor(kysely), { claims });

batch(ops, context) is optional. db.$many hands it every operation that is ready at once and expects one Result per operation, in order. postgresExecutor runs them in one transaction. If one fails, it runs each operation on its own so the others still succeed. Without batch, $many runs the operations in parallel through execute. testExecutor checks batch when an executor has it.

rpc(name, args, context) is optional too. context.get is set for stable functions such as read sets. Send those as GET, so read replicas can serve them. context.function carries the function's generated metadata (its arguments, return type and whether it returns a set) when the schema has it; postgresExecutor reads it to shape the result like PostgREST.

functionSources: true says the executor honors SelectOp.source: read from that set-returning function, with its named arguments, instead of the table. db.$search needs it. testExecutor checks that a missing source function fails rather than falling back to the table.

betterSupabase.connect(client, { executor }) runs the queries through executor while db.$client stays the given client. The server uses this to wrap two PostgREST executors for read replicas.

CompilerCopy Anchor Link

Compiler<TTarget> turns an operation into what a backend runs: postgrestCompiler.compile(op) returns the PostgREST plan and sqlCompiler.compile(op) (from better-supabase/postgres) returns parameterized SQL. Build a new executor on top of either, or write your own compiler for another query builder.

CacheAdapterCopy Anchor Link

Invalidates cached reads after mutations. betterSupabase.cache(adapter) calls it with the table key, the primary keys of the changed rows and the tenant, and returns a function that detaches it.

import type { CacheAdapter } from "better-supabase";

const redis: CacheAdapter = {
  name: "redis",
  invalidate: ({ table, ids, tenant }) =>
    redisClient.del([
      `${tenant}:${table}`,
      ...ids.map((id) => `${tenant}:${table}:${id}`),
    ]),
};

betterSupabase.cache(redis);

createNext attaches nextCache() for you, and invalidateOnMutation(betterSupabase, client) attaches queryCache(client). Adapter errors are logged, never returned from the mutation.

EventSinkCopy Anchor Link

Receives CloudEvents batches. See CloudEvents for toCloudEvents and forwardMutations.

QueueBackendCopy Anchor Link

Stores and leases jobs for createJobs. It has apiVersion: 1, sends and reads messages, completes, fails and extends them by attempt (a stale attempt must get false or null), and optionally claims due schedules for the drain route, replays dead letters (replay), and reports queue health (stats, listDead, retryDead). A message read past its max_attempts should be archived as dead instead of returned. Set leases: false when extend can't work, so workers skip the heartbeat.

SupportSessionStoreCopy Anchor Link

Records support sessions. It has apiVersion: 1 and four methods: start(input) ends the admin's previous session and returns the new one, get(sessionId, adminId) returns a running session only to its admin, end(sessionId, endedBy) returns true once and false after, and list(filter) returns sessions newest first. claims(targetUserId) is optional and returns the claims the target would get. start should refuse an admin without permission with an error whose code is 42501.

NotificationChannelCopy Anchor Link

Sends one notification delivery on a channel other than in-app. It has apiVersion: 1, a name that matches the delivery's channel and send(message), which gets the recipient's id and email, the notification and its rendered text. Return { provider, providerMessageId } to store the provider's id, { status: 'skipped' } when there is nothing to send, and throw to retry later.

WebhookSignerCopy Anchor Link

Adds the signature headers to an outgoing webhook. It has apiVersion: 1, a name and sign({ id, body, timestamp, secrets }), which returns the headers. secrets lists every live secret, newest first; sign with each so receivers keep verifying while a secret rotates. The same input must give the same headers.

WebhookTransportCopy Anchor Link

Sends one signed webhook request. It has apiVersion: 1, a name and send({ url, headers, body, signal }), which returns { status, body } for any HTTP response. Throw WebhookPolicyError for a request that must never be retried, such as a blocked URL; any other error retries.

WebhookSecretStoreCopy Anchor Link

Where destination signing secrets live. It has apiVersion: 1, secrets(endpointId), which returns the live secrets newest first, and an optional rotate(endpointId, { overlap, secret }) that returns the new secret and keeps the previous ones live for overlap.

StreamStoreCopy Anchor Link

Durable, resumable output. It has apiVersion: 1, open, append(id, fromIdx, chunks) that skips indexes already stored and reports a cancel, read(id, fromIdx) that waits for new chunks until the stream closes, status, close, cancel and purge. See Durable streams.

CredentialProviderCopy Anchor Link

Turns a credential_ref into a token. It has apiVersion: 1, a name, capabilities(ref), getToken(ref, { subject, scopes }) and revoke(ref, { subject }), and optionally startAuthorization, completeAuthorization and verifyInbound. See Credentials.

AuthorizationProviderCopy Anchor Link

Hands the SQL modules, the Storage and Realtime policies and doctor to another authorization system. It has apiVersion: 1 and is plain data in better-supabase.config.ts: its scopes, the scope tenants are, and SQL templates such as idsWith and isPlatform that answer permission checks. Authorization providers describes every field. testAuthorizationProvider from better-supabase/testing is its conformance block.

The optional fields each turn on one integration:

AuthorizerCopy Anchor Link

The runtime decision point for the permission of resources, actions, route guards and MCP tools. It has apiVersion: 1, a name, key(ref) and evaluate(request), plus optional forOperation and the batch evaluations. Requests follow the AuthZEN subject, action, resource and context model, and anything but a granted outcome refuses. defineAuthorizer from better-supabase/server builds one and sets apiVersion. Authorizers describes the contract, and testAuthorizer from better-supabase/testing is its conformance block.

DocumentFormatCopy Anchor Link

Renders the version-neutral API model that defineApi builds into one document version. The OpenAPI versions are built in; Document formats shows how to write another, and testDocumentFormat from better-supabase/testing is its conformance block.

EmbedderCopy Anchor Link

Turns texts into vectors for the knowledge and memory blocks. It has a model name and embed(values, { signal }), which returns one vector per value, all of one length. testEmbedder from better-supabase/testing is its conformance block.

AiTaskRunnerCopy Anchor Link

The function createAiTasks calls for each due run, with the task, the claimed run and an AbortSignal. It resolves with nothing or with the chatId the run wrote to, and throws when the signal aborts. testAiTaskRunner is its conformance block.

GraphCompilerCopy Anchor Link

Turns a builder graph into your engine's form when a version is published. It returns a JSON value, the same one for the same graph, and leaves the graph unchanged. testGraphCompiler is its conformance block.

BuilderStarterCopy Anchor Link

Starts a published version on your engine and returns the engine's run id. A repeated idempotencyKey returns the same run. testBuilderStarter is its conformance block.

EveDocumentBackendCopy Anchor Link

eve's document store for fileMemory(). read returns the content and version or null, and write throws when expectedVersion is stale. testEveDocumentBackend is its conformance block.

BlockTransportMiddlewareCopy Anchor Link

Runs around every call a block transport makes, for every block built on it. It has apiVersion: 1, a name, and call(request, next), where request holds the schema, fn and args of the call. Pass a changed request to next to rewrite it, and reject with the error next rejected with, so the block still maps it to a DbError. testBlockTransportMiddleware from better-supabase/testing is its conformance kit, and Extending blocks shows it in use.

import {
  defineTransportMiddleware,
  wrapTransport,
} from "better-supabase/blocks";

const timed = defineTransportMiddleware({
  name: "timing",
  async call(request, next) {
    const started = performance.now();
    try {
      return await next(request);
    } finally {
      metrics.record(request.fn, performance.now() - started);
    }
  },
});

const transport = wrapTransport(rpcTransport(supabase), timed);

Versions of the block injectablesCopy Anchor Link

These five carry an optional apiVersion. Omitting it means 1; the blocks refuse any other value when they are built. The built-in embedders and supabaseDocumentBackend set it, and the conformance blocks require it, so a release built for API 1 says so. A function sets it with Object.assign(fn, { apiVersion: 1 }).

AuthResolverCopy Anchor Link

Resolves credentials the built-in Bearer and cookie resolution doesn't know: API keys, third-party tokens, signed links. Return undefined when the request has none of your credentials, and { kind: 'invalid', error } when it has bad ones, so the request fails with 401 instead of running as anonymous.

GeneratorCopy Anchor Link

Adds files at codegen time. Return paths relative to the project root; output must be deterministic so gen --check works.

LoggerCopy Anchor Link

Where better-supabase reports errors it swallows on purpose: event handlers, afterMutation hooks, sinks and cache adapters that throw. Pass a structured logger (pino, consola) or silentLogger in tests.

export const betterSupabase = defineSupabase(schema, { logger: pino() });