fix: Add configurable shutdown grace period for graceful server termination

[avallete]

Summary

Refactors the server shutdown logic to use a configurable grace period before force-exiting, allowing in-flight work to complete within a timeout window. This improves reliability in containerized environments where the container runtime may SIGKILL the process after its own grace period.

Key Changes

• New environment variable: PG_META_SHUTDOWN_GRACE_PERIOD_SECS (default: 10 seconds) controls how long the server waits for in-flight work before force-exiting
• Simplified shutdown handler: Removed complex close listener management and mutual app/adminApp hook dependencies that could cause deadlocks
• Improved error handling: Changed to use .catch() for graceful error handling during shutdown instead of throwing, ensuring all cleanup steps attempt to run
• Better logging: Changed signal received log from error level to info level (more appropriate for normal shutdown signals)
• Updated documentation: Added the new environment variable to CLAUDE.md

Implementation Details

• The closeWithGrace call now passes a delay option set to SHUTDOWN_GRACE_PERIOD_MS
• Removed the closeListeners variable and associated hook uninstall logic that was managing listener lifecycle
• Removed circular dependencies between app.onClose and adminApp.onClose hooks that could prevent proper shutdown
• All cleanup operations (closing app, adminApp, destroying format pool) now use .catch() to log errors without throwing, ensuring subsequent cleanup steps execute
• The grace period default (10s) matches Docker's default container stop grace period, with the expectation that this value should be set lower than the container runtime's grace period for the force-exit to actually execute

https://claude.ai/code/session_01Gj9ospbnecaS2ccYt2MayL

[github-actions]

🚀 Canary Deployment Status

✅ Canary image deployed successfully!

🐳 Docker Image: supabase/postgres-meta:canary-pr-1103-ed09961448b2c30498c9b6d98de4e3e88252fd84
📝 Commit: ed09961448b2c30498c9b6d98de4e3e88252fd84

You can test this canary deployment by pulling the image:

docker pull supabase/postgres-meta:canary-pr-1103-ed09961448b2c30498c9b6d98de4e3e88252fd84

You can also set the version in a supabase local project by running:

echo "supabase/postgres-meta:canary-pr-1103-ed09961448b2c30498c9b6d98de4e3e88252fd84" > supabase/.temp/pgmeta-version

Or use it in your docker-compose.yml:

services:
  postgres-meta:
    image: supabase/postgres-meta:canary-pr-1103-ed09961448b2c30498c9b6d98de4e3e88252fd84
    # ... other configuration

The canary image is available on:

• 🐳 Docker Hub
• 📦 GitHub Container Registry
• ☁️ AWS ECR Public

false

---

_{Last updated: 2026-08-14T13:31:48Z}