docs: add a 0.8.0 release post and update README.md (#390)

jumski · jumski · commit 73802376fff4 · 2025-11-19T08:24:40.000Z
diff --git a/.changeset/modernize-dependencies-0-8-0.md b/.changeset/modernize-dependencies-0-8-0.md
@@ -0,0 +1,21 @@
+---
+'@pgflow/core': minor
+'@pgflow/client': minor
+'@pgflow/edge-worker': minor
+'@pgflow/website': minor
+---
+
+BREAKING CHANGE: pgflow 0.8.0 requires pgmq 1.5.0+, PostgreSQL 17, and Supabase CLI 2.34.3+
+
+This version modernizes infrastructure dependencies and will NOT work with pgmq 1.4.x or earlier. The migration includes a compatibility check that aborts with a clear error message if requirements are not met.
+
+**Requirements:**
+- pgmq 1.5.0 or higher (previously supported 1.4.x)
+- PostgreSQL 17 (from 15)
+- Supabase CLI 2.34.3 or higher (includes pgmq 1.5.0+)
+
+**For Supabase users:** Upgrade your Supabase CLI to 2.34.3+ which includes pgmq 1.5.0 by default.
+
+**For self-hosted users:** Upgrade pgmq to 1.5.0+ and PostgreSQL to 17 before upgrading pgflow.
+
+**If you cannot upgrade immediately:** Stay on pgflow 0.7.x until your infrastructure is ready. The migration safety check ensures you cannot accidentally upgrade to an incompatible version.
diff --git a/.changeset/pgmq-version-bump.md b/.changeset/pgmq-version-bump.md
diff --git a/.changeset/upgrade-postgres-seventeen-supabase.md b/.changeset/upgrade-postgres-seventeen-supabase.md
diff --git a/pkgs/cli/README.md b/pkgs/cli/README.md
@@ -15,7 +15,7 @@ This package provides essential tools for setting up, managing, and deploying pg
 
 ## Prerequisites
 
-- Supabase CLI v2.0.2 or higher
+- Supabase CLI v2.34.3 or higher
 - Deno v1.45.x or higher (for flow compilation)
 - Local Supabase project initialized
 
diff --git a/pkgs/core/README.md b/pkgs/core/README.md
@@ -47,6 +47,17 @@ This package focuses on:
 
 The actual execution of workflow tasks is handled by the [Edge Worker](../edge-worker/README.md), which calls back to the SQL Core to acknowledge task completion or failure.
 
+## Requirements
+
+> [!IMPORTANT]
+> **pgmq Version Requirement** (since v0.8.0)
+>
+> pgflow v0.8.0 and later requires **pgmq 1.5.0 or higher**. This version of pgflow will NOT work with pgmq 1.4.x or earlier.
+>
+> - **Supabase Cloud**: Recent versions include pgmq 1.5.0+ by default
+> - **Self-hosted**: You must upgrade pgmq to version 1.5.0+ before upgrading pgflow
+> - **Version Check**: Run `SELECT extversion FROM pg_extension WHERE extname = 'pgmq';` to verify your pgmq version
+
 ## Key Features
 
 - **Declarative Workflows**: Define flows and steps via SQL tables
diff --git a/pkgs/core/project.json b/pkgs/core/project.json
@@ -50,6 +50,7 @@
       "options": {
         "cwd": "{projectRoot}",
         "commands": [
+          "../../scripts/supabase-start-locked.sh .",
           "mkdir -p .nx-inputs",
           "scripts/atlas-verify-schemas-synced > .nx-inputs/verify-schemas-synced.txt 2>&1 || (cat .nx-inputs/verify-schemas-synced.txt && exit 1)"
         ],
diff --git a/pkgs/core/supabase/migrations/20251104080523_pgflow_upgrade_pgmq_1_5_1.sql b/pkgs/core/supabase/migrations/20251104080523_pgflow_upgrade_pgmq_1_5_1.sql
@@ -1,5 +1,5 @@
 -- Migration tested 2025-11-02:
--- Successfully verified that this migration fails on pgmq 1.4.4 (Supabase CLI 2.0.2)
+-- Successfully verified that this migration fails on pgmq 1.4.4 (Supabase CLI < 2.34.3)
 -- with clear error message guiding users to upgrade pgmq to 1.5.0+
 --
 -- Compatibility check: Ensure pgmq.message_record has headers column (pgmq 1.5.0+)
diff --git a/pkgs/core/supabase/migrations/atlas.sum b/pkgs/core/supabase/migrations/atlas.sum
@@ -1,4 +1,4 @@
-h1:SeEHqz8uDIqu6Px6f1IajB3NfXOYmetcSxFbp9PiYXY=
+h1:GRevz5BG7qrdQxFbQ0XO9f21I5qaYocLc08bN3gVG50=
 20250429164909_pgflow_initial.sql h1:I3n/tQIg5Q5nLg7RDoU3BzqHvFVjmumQxVNbXTPG15s=
 20250517072017_pgflow_fix_poll_for_tasks_to_use_separate_statement_for_polling.sql h1:wTuXuwMxVniCr3ONCpodpVWJcHktoQZIbqMZ3sUHKMY=
 20250609105135_pgflow_add_start_tasks_and_started_status.sql h1:ggGanW4Wyt8Kv6TWjnZ00/qVb3sm+/eFVDjGfT8qyPg=
@@ -10,4 +10,4 @@ h1:SeEHqz8uDIqu6Px6f1IajB3NfXOYmetcSxFbp9PiYXY=
 20250719205006_pgflow_worker_deprecation.sql h1:pL5cR1/Oag993yWN6sUpE/U3LmVSzAlnoRXJRBtErU8=
 20251006073122_pgflow_add_map_step_type.sql h1:D/skgKpaVg5TM8bPovo9FUutQfg35/AzkxEcasYwytY=
 20251103222045_pgflow_fix_broadcast_order_and_timestamp_handling.sql h1:K/XnZpOmxfelsaNoJbR5HxhBrs/oW4aYja222h5cps4=
-20251104080523_pgflow_upgrade_pgmq_1_5_1.sql h1:xnbHNJkMGWoaIL5RH617CCjM9nX1Yde8TimHpHhk7fM=
+20251104080523_pgflow_upgrade_pgmq_1_5_1.sql h1:t+Hu/rqP8b23S+JAjJ86Y8UlOTCfA+085/8RxD7gydA=
diff --git a/pkgs/website/src/assets/cover-images/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.png b/pkgs/website/src/assets/cover-images/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.png
diff --git a/pkgs/website/src/content/docs/get-started/installation.mdx b/pkgs/website/src/content/docs/get-started/installation.mdx
@@ -13,7 +13,7 @@ import { FileTree } from '@astrojs/starlight/components';
 Let's set up pgflow in your Supabase project. This setup needs to be done only once per project.
 
 <Aside type="caution" title="Prerequisites">
-- Supabase CLI version **2.0.2** or higher (check with `supabase -v`)
+- Supabase CLI version **2.34.3** or higher (check with `supabase -v`)
 - A local Supabase project set up
 - [Deno version **1.45.2 or higher**](https://github.com/denoland/deno/releases/tag/v1.45.2) (2.x also supported) - required for flow compilation
 
diff --git a/pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx b/pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx
@@ -0,0 +1,112 @@
+---
+draft: false
+title: 'pgflow 0.8.0: Modernizing Dependencies - pgmq 1.5.0 and PostgreSQL 17'
+description: 'Breaking changes requiring pgmq 1.5.0 or higher and PostgreSQL 17, with built-in migration safety checks'
+date: 2025-11-18
+authors:
+  - jumski
+tags:
+  - release
+  - breaking-change
+  - migration
+featured: true
+cover:
+  alt: 'Cyberpunk hacker upgrading database dependencies on a glitchy terminal screen'
+  image: '../../../assets/cover-images/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.png'
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+pgflow 0.8.0 requires pgmq 1.5.0 or higher and PostgreSQL 17. This release removes the pgmq compatibility layer and prepares the foundation for upcoming flow auto-compilation features.
+
+<Aside type="caution" title="Breaking Change">
+  This version will NOT work with pgmq 1.4.x or earlier. The migration includes a compatibility check that will abort with a clear error message if pgmq 1.5.0 is not detected.
+</Aside>
+
+## What's Changing
+
+pgflow 0.8.0 introduces breaking dependency changes:
+
+1. **pgmq version**: Now requires 1.5.0 or higher (previously supported 1.4.x)
+2. **PostgreSQL version**: Upgrades to PostgreSQL 17 (from 15)
+3. **Supabase CLI**: Requires version 2.34.3 or higher (includes pgmq 1.5.0+)
+
+The migration will fail safely if these requirements are not met - no partial upgrades or corrupted state.
+
+## Background
+
+This release skips backward compatibility entirely - pgflow 0.8.0 requires pgmq 1.5.0 from the start. Maintaining compatibility layers for older versions would accumulate technical debt that becomes harder to remove as the project matures.
+
+Additionally, upcoming features like flow auto-compilation depend on infrastructure available only in newer Supabase versions (automatic edge function respawning in local development). Moving to pgmq 1.5.0 and PostgreSQL 17 unblocks these improvements.
+
+## Before You Upgrade
+
+### Check Your pgmq Version
+
+Run this query to verify your current pgmq version:
+
+```sql
+SELECT extversion FROM pg_extension WHERE extname = 'pgmq';
+```
+
+You need version 1.5.0 or higher to upgrade to pgflow 0.8.0.
+
+### Compatibility Check Built-In
+
+The migration includes a pre-check that inspects the pgmq schema before making any changes. If pgmq 1.5.0 is not detected, the migration aborts with this error:
+
+```
+ERROR: INCOMPATIBLE PGMQ VERSION DETECTED
+
+This migration requires pgmq 1.5.0 or higher.
+The pgmq.message_record type is missing the "headers" column,
+which indicates you are running pgmq < 1.5.0.
+
+Action required:
+  - Supabase: Ensure you are running a recent version that includes pgmq 1.5.0+
+  - Self-hosted: Upgrade pgmq to version 1.5.0 or higher before running this migration
+
+Migration aborted to prevent runtime failures.
+```
+
+This safety check prevents partial migrations and data corruption.
+
+## Migration Guide
+
+### Supabase Cloud Users
+
+Supabase CLI version 2.34.3 or higher includes pgmq 1.5.0 by default. To upgrade:
+
+1. Update your Supabase CLI if needed:
+   ```bash
+   supabase -v  # Check current version
+   npm install -g supabase  # Update if below 2.34.3
+   ```
+2. Verify your pgmq version using the SQL query above
+3. If you have pgmq 1.5.0+, run your migrations normally:
+   ```bash
+   supabase db push
+   ```
+4. If you have pgmq 1.4.x, wait for your Supabase instance to upgrade before updating pgflow
+
+### Self-Hosted Users
+
+You must upgrade pgmq to 1.5.0+ before upgrading pgflow:
+
+1. Check your current pgmq version
+2. Upgrade pgmq to 1.5.0 or higher following the [pgmq upgrade guide](https://github.com/tembo-io/pgmq)
+3. Upgrade PostgreSQL to version 17 if not already running it
+4. Run your pgflow migrations:
+   ```bash
+   supabase db push
+   ```
+
+## What If I Can't Upgrade?
+
+If you cannot upgrade to pgmq 1.5.0 immediately, stay on pgflow 0.7.x. The migration safety check ensures you cannot accidentally upgrade to an incompatible version.
+
+Your existing pgflow 0.7.x installation will continue working until you are ready to upgrade your infrastructure.
+
+---
+
+For questions or issues with the upgrade, visit the [pgflow Discord](https://www.pgflow.dev/discord/) or [open a GitHub issue](https://github.com/pgflow-dev/pgflow/issues).
diff --git a/pkgs/website/src/content/docs/reference/manual-installation.mdx b/pkgs/website/src/content/docs/reference/manual-installation.mdx
@@ -15,7 +15,7 @@ This guide explains how to manually set up pgflow and Edge Worker without using
 - When you want to understand what happens behind the scenes
 
 <Aside type="caution" title="Prerequisites">
-- Supabase CLI version **2.0.2** or higher (check with `supabase -v`)
+- Supabase CLI version **2.34.3** or higher (check with `supabase -v`)
 - A local Supabase project set up
 - Basic understanding of Supabase configuration
 </Aside>
diff --git a/pkgs/website/src/styles/global.css b/pkgs/website/src/styles/global.css
@@ -7,6 +7,12 @@ body {
 
 /* Dark mode colors. */
 :root {
+  /* Content width override - default is ~45rem */
+  --sl-content-width: 55rem;
+
+  /* Sidebar width - default is ~18rem */
+  --sl-sidebar-width: 16rem;
+
   --sl-color-accent-low: #002b26;
   --sl-color-accent: #007b6e;
   --sl-color-accent-high: #a3d4cb;
