Skip to content

Commit b057eb7

Browse files
jumskijumski
committed
docs: add a 0.8.0 release post and update README.md
1 parent 20fcd48 commit b057eb7

File tree

3 files changed

+119
-0
lines changed

3 files changed

+119
-0
lines changed

‎pkgs/core/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,17 @@ This package focuses on:
4747

4848
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.
4949

50+
## Requirements
51+
52+
> [!IMPORTANT]
53+
> **pgmq Version Requirement** (since v0.8.0)
54+
>
55+
> 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.
56+
>
57+
> - **Supabase Cloud**: Recent versions include pgmq 1.5.0+ by default
58+
> - **Self-hosted**: You must upgrade pgmq to version 1.5.0+ before upgrading pgflow
59+
> - **Version Check**: Run `SELECT extversion FROM pg_extension WHERE extname = 'pgmq';` to verify your pgmq version
60+
5061
## Key Features
5162

5263
- **Declarative Workflows**: Define flows and steps via SQL tables

‎pkgs/website/src/assets/cover-images/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.png‎

1.7 MB
Loading

‎pkgs/website/src/content/docs/news/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.mdx‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
draft: false
3+
title: 'pgflow 0.8.0: Modernizing Dependencies - pgmq 1.5.0 and PostgreSQL 17'
4+
description: 'Breaking changes requiring pgmq 1.5.0 or higher and PostgreSQL 17, with built-in migration safety checks'
5+
date: 2024-11-18
6+
authors:
7+
- jumski
8+
tags:
9+
- release
10+
- breaking-change
11+
- migration
12+
featured: true
13+
cover:
14+
alt: 'Cyberpunk hacker upgrading database dependencies on a glitchy terminal screen'
15+
image: '../../../assets/cover-images/pgflow-0-8-0-modernizing-dependencies-pgmq-1-5-0-and-postgresql-17.png'
16+
---
17+
18+
import { Aside } from "@astrojs/starlight/components";
19+
20+
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.
21+
22+
<Aside type="caution" title="Breaking Change">
23+
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.
24+
</Aside>
25+
26+
## What's Changing
27+
28+
pgflow 0.8.0 introduces two breaking dependency changes:
29+
30+
1. **pgmq version**: Now requires 1.5.0 or higher (previously supported 1.4.x)
31+
2. **PostgreSQL version**: Upgrades to PostgreSQL 17 (from 15)
32+
33+
The migration will fail safely if these requirements are not met - no partial upgrades or corrupted state.
34+
35+
## Why Now
36+
37+
This release removes the pgmq compatibility layer that allowed pgflow to work with both pgmq 1.4.x and 1.5.x. Maintaining this compatibility added complexity and prevented adoption of newer features.
38+
39+
Additionally, recent Supabase versions include automatic edge function respawning in local development. This capability is required for the upcoming flow auto-compilation feature, which will eliminate the need for manual migration generation.
40+
41+
Pre-1.0 is the right time for these changes - breaking now with a small user base prevents technical debt accumulation.
42+
43+
## Before You Upgrade
44+
45+
### Check Your pgmq Version
46+
47+
Run this query to verify your current pgmq version:
48+
49+
```sql
50+
SELECT extversion FROM pg_extension WHERE extname = 'pgmq';
51+
```
52+
53+
You need version 1.5.0 or higher to upgrade to pgflow 0.8.0.
54+
55+
### Compatibility Check Built-In
56+
57+
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:
58+
59+
```
60+
ERROR: INCOMPATIBLE PGMQ VERSION DETECTED
61+
62+
This migration requires pgmq 1.5.0 or higher.
63+
The pgmq.message_record type is missing the "headers" column,
64+
which indicates you are running pgmq < 1.5.0.
65+
66+
Action required:
67+
- Supabase: Ensure you are running a recent version that includes pgmq 1.5.0+
68+
- Self-hosted: Upgrade pgmq to version 1.5.0 or higher before running this migration
69+
70+
Migration aborted to prevent runtime failures.
71+
```
72+
73+
This safety check prevents partial migrations and data corruption.
74+
75+
## Migration Guide
76+
77+
### Supabase Cloud Users
78+
79+
Recent Supabase versions include pgmq 1.5.0 by default. To upgrade:
80+
81+
1. Verify your pgmq version using the SQL query above
82+
2. If you have pgmq 1.5.0+, run your migrations normally:
83+
```bash
84+
supabase db push
85+
```
86+
3. If you have pgmq 1.4.x, wait for your Supabase instance to upgrade before updating pgflow
87+
88+
### Self-Hosted Users
89+
90+
You must upgrade pgmq to 1.5.0+ before upgrading pgflow:
91+
92+
1. Check your current pgmq version
93+
2. Upgrade pgmq to 1.5.0 or higher following the [pgmq upgrade guide](https://github.com/tembo-io/pgmq)
94+
3. Upgrade PostgreSQL to version 17 if not already running it
95+
4. Run your pgflow migrations:
96+
```bash
97+
supabase db push
98+
```
99+
100+
## What If I Can't Upgrade?
101+
102+
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.
103+
104+
Your existing pgflow 0.7.x installation will continue working until you are ready to upgrade your infrastructure.
105+
106+
---
107+
108+
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).

0 commit comments

Comments
 (0)