feat: add environment variable to disable auto-respawn of Edge Workers

Implement a simple check in SupabasePlatformAdapter to prevent spawning new edge functions
during shutdown when EDGE_WORKER_DISABLE_AUTO_RESPAWN is set to true.
Include documentation explaining how to disable auto-respawn via environment variables and
outline use cases.
Also, add a new test file to verify the environment variable behavior.
This minimal change provides temporary control over worker respawning with minimal code
modifications and documentation updates.

Author: jumski

pkgs/edge-worker/src/platform/SupabasePlatformAdapter.ts

@@ -24,6 +24,7 @@ interface SupabaseEnv extends Record<string, string | undefined> {
   EDGE_WORKER_DB_URL: string;
   SB_EXECUTION_ID: string;
   EDGE_WORKER_LOG_LEVEL?: string;
+  EDGE_WORKER_DISABLE_AUTO_RESPAWN?: string;
 }
 
 /**
@@ -176,10 +177,21 @@ export class SupabasePlatformAdapter implements PlatformAdapter<SupabaseResource
     globalThis.onbeforeunload = async () => {
       this.logger.debug('Shutting down...');
 
-      if (this.worker) {
-        await this.spawnNewEdgeFunction();
+      // Early return if no worker to respawn
+      if (!this.worker) {
+        await this.stopWorker();
+        return;
+      }
+
+      // Check if auto-respawn is disabled
+      if (this.validatedEnv.EDGE_WORKER_DISABLE_AUTO_RESPAWN === 'true') {
+        this.logger.debug('Auto-respawn disabled via EDGE_WORKER_DISABLE_AUTO_RESPAWN');
+        await this.stopWorker();
+        return;
       }
 
+      // Default behavior: spawn new function before stopping
+      await this.spawnNewEdgeFunction();
       await this.stopWorker();
     };
   }

pkgs/website/src/content/docs/deploy/supabase/keep-workers-running.mdx

@@ -19,6 +19,10 @@ Set up a pg_cron safety net that checks worker status and only starts new worker
 
 Edge Workers normally auto-respawn by sending their own HTTP requests. In rare cases during high load, workers may fail to respawn if they hit execution time limits before sending restart requests. Basic safety nets can cause Supabase's Edge Runtime to spawn multiple workers simultaneously, leading to unpredictable costs.
 
+<Aside type="tip">
+You can [disable auto-respawn](/how-to/disable-worker-auto-respawn/) if you want full control over worker lifecycle through pg_cron.
+</Aside>
+
 ## Smart Safety Net Solution
 
 This approach checks existing worker counts before spawning new ones:

pkgs/website/src/content/docs/how-to/disable-worker-auto-respawn.mdx

@@ -0,0 +1,65 @@
+---
+title: Disable Worker Auto-Respawn
+description: How to disable automatic worker respawning in Supabase Edge Functions
+sidebar:
+  order: 116
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+<Aside type="caution" title="Temporary Feature">
+This is a temporary solution using environment variables. In future versions, this may be replaced with a proper configuration option.
+</Aside>
+
+By default, pgflow Edge Workers automatically spawn a new instance when shutting down to ensure continuous processing. You can disable this behavior if you're using external orchestration like pg_cron.
+
+## Disabling Auto-Respawn
+
+### For Local Development
+
+Add to your `supabase/functions/.env` file:
+
+```diff
+# supabase/functions/.env
+EDGE_WORKER_DB_URL=postgres://...
+EDGE_WORKER_LOG_LEVEL=info
++EDGE_WORKER_DISABLE_AUTO_RESPAWN=true
+```
+
+### For Production (Supabase Dashboard)
+
+1. Go to your project's Edge Functions settings
+2. Find your worker function
+3. Add the environment variable:
+   - Key: `EDGE_WORKER_DISABLE_AUTO_RESPAWN`
+   - Value: `true`
+
+## When to Use This
+
+Disable auto-respawn when:
+
+- You're using pg_cron to schedule worker restarts
+- You want manual control over worker lifecycle
+- You're debugging shutdown behavior
+- You need to prevent duplicate workers
+
+## Example with pg_cron
+
+If you're using pg_cron to restart workers periodically:
+
+```sql
+-- Schedule worker restart every hour
+SELECT cron.schedule(
+  'restart-edge-worker',
+  '0 * * * *',  -- Every hour
+  $$
+  -- Your restart logic here
+  $$
+);
+```
+
+With auto-respawn disabled, only pg_cron controls when new workers start.
+
+<Aside type="note">
+Without auto-respawn, ensure you have another mechanism (like pg_cron) to restart workers, otherwise processing will stop when the worker shuts down.
+</Aside>