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

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

@@ -20,6 +20,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;
 }
 
 /**
@@ -172,10 +173,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/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>

pkgs/website/src/content/docs/how-to/keep-workers-up.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:

plan.md

@@ -0,0 +1,140 @@
+# Feature Plan: Disable Worker Auto-Respawning (Minimal MVP)
+
+## Overview
+
+Add a simple environment variable to disable the automatic respawning of Edge Workers when they shut down. This is a minimal, temporary solution that can be improved later based on user feedback.
+
+## Implementation (Super Simple)
+
+### 1. Code Change
+
+**File:** `pkgs/edge-worker/src/platform/SupabasePlatformAdapter.ts`
+
+In the `setupShutdownHandler()` method, check for env var:
+
+```typescript
+private setupShutdownHandler(): void {
+  globalThis.onbeforeunload = async () => {
+    this.logger.debug('Shutting down...');
+
+    // Check if auto-respawn is disabled via env var
+    const disableAutoRespawn = this.validatedEnv.EDGE_WORKER_DISABLE_AUTO_RESPAWN === 'true';
+
+    if (this.worker && !disableAutoRespawn) {
+      await this.spawnNewEdgeFunction();
+    } else if (this.worker && disableAutoRespawn) {
+      this.logger.debug('Auto-respawn disabled via EDGE_WORKER_DISABLE_AUTO_RESPAWN');
+    }
+
+    await this.stopWorker();
+  };
+}
+```
+
+That's it for the code change! One if statement.
+
+### 2. Documentation
+
+**Create File:** `pkgs/website/src/content/docs/how-to/disable-worker-auto-respawn.mdx`
+
+```markdown
+---
+title: Disable Worker Auto-Respawn
+description: How to disable automatic worker respawning in Supabase Edge Functions
+sidebar:
+  order: 100
+---
+
+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
+
+Set the following environment variable in your Edge Function:
+
+```bash
+EDGE_WORKER_DISABLE_AUTO_RESPAWN=true
+```
+
+### In 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`
+
+### In .env.local
+
+For local development:
+
+```bash
+EDGE_WORKER_DISABLE_AUTO_RESPAWN=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>
+```
+
+### 3. Testing (Optional - Only if Easy)
+
+If testing is straightforward, create a simple test:
+
+**File:** `pkgs/edge-worker/tests/unit/autoRespawn.test.ts`
+
+```typescript
+describe('Auto-respawn environment variable', () => {
+  it('should respect EDGE_WORKER_DISABLE_AUTO_RESPAWN env var', () => {
+    // Mock env var
+    // Verify spawnNewEdgeFunction is not called
+  });
+});
+```
+
+## Implementation Checklist
+
+- [ ] Add env var check to SupabasePlatformAdapter.ts (~5 lines)
+- [ ] Create how-to documentation page
+- [ ] (Optional) Add simple test if easy
+
+## Total Effort: ~30 minutes
+
+This minimal approach:
+- Solves the immediate need
+- Requires minimal code changes (5-10 lines)
+- Easy to remove/replace later
+- No API changes
+- No breaking changes
+- Clear documentation about temporary nature