supaworker-js

Supaworker is a job queue for Supabase projects.

License

MIT

Usage

Supaworker is a job queue that is backed by your Supabase database. Jobs are enqueued as rows in a "supaworker"."jobs" table where background workers can dequeue and process them.

A worker does the following:

1. Dequeues jobs that match the worker's queue
2. Processes jobs until there are none left
3. Listens for new jobs using Supabase's Realtime feature

Timeouts, delayed retries, and scale are left to the developer.

Supaworker is not designed to be used with Edge Functions, but instead with dedicated worker processes -- usually docker containers. This allows the developer to control the environment, runtime, dependencies, and scaling.

Setup

The first integration step is to add the Supaworker schema to your Supabase project.

supabase migration new setup_supaworker
Copy

Carefully review and add the following SQL from here.

Run the migration:

supabase migration up --local
Copy

Update your supabase/config.toml to include the supaworker schema:

[api]
schemas = ["public", "supaworker"]
Copy

Sync the schema to your Supabase project:

supabase db lint
supabase test db
supabase db push
Copy

Add supaworker-js to your project:

npm install --save supaworker-js
Copy

Examples

Node.js

Create a new project

mkdir my-worker && cd my-worker
npm init -y
npm install --save supaworker-js
touch index.js
Copy

Edit package.json to use ESM modules:

{
  "type": "module"
}
Copy

Basic javascript example:

import { createSupaworker } from 'supaworker-js';

const clientOptions = {
  supabase_url: process.env.SUPABASE_URL ?? '',
  supabase_service_role_key: process.env.SUPABASE_SERVICE_ROLE_KEY ?? '',
};

const workerOptions = {
  queue: 'example',
};

const { enqueue, worker } = createSupaworker(clientOptions, workerOptions, async (job) => {
  console.log(job.payload.message);
});

await enqueue([
  {
    queue: 'example',
    payload: {
      message: 'Hello, World!',
    },
  },
]);

process.on('SIGINT', async () => {
  await worker.stop();
  process.exit();
});

await worker.start();
await worker.stop();
Copy

Run the worker:

SUPABASE_URL="" \
SUPABASE_SERVICE_ROLE_KEY="" \
node index.js
Copy

Bun

Create a new project

mkdir my-worker && cd my-worker
bun init
bun add supaworker-js
Copy

Basic typescript example:

import {
  createSupaworker,
  type SupaworkerClientOptions,
  type SupaworkerOptions,
} from 'supaworker-js';

const clientOptions: SupaworkerClientOptions = {
  supabase_url: import.meta.env.SUPABASE_URL ?? '',
  supabase_service_role_key: import.meta.env.SUPABASE_SERVICE_ROLE_KEY ?? '',
};

const workerOptions: SupaworkerOptions = {
  queue: 'example',
};

const { enqueue, worker } = createSupaworker<{ message: string }>(
  clientOptions,
  workerOptions,
  async (job) => {
    console.log(job.payload!.message);
  },
);

await enqueue([
  {
    queue: 'example',
    payload: {
      message: 'Hello, World!',
    },
  },
]);

process.on('SIGINT', async () => {
  await worker.stop();
  process.exit();
});

await worker.start();
await worker.stop();
Copy

Run the worker:

SUPABASE_URL="" \
SUPABASE_SERVICE_ROLE_KEY="" \
bun run index.ts
Copy