Skip to content

Commit a5d139e

Browse files
TheSentinel454Elrondclaude
committed
docs: name the required stop as a relay build, not a release
Relay deployments track images built from main, and no tagged relay release contains #8325. Name any build at or after 6878520 (#8325's merge) as the required stop, and tell deployments on a tagged release to move to one first. Co-authored-by: Elrond <28d6302a099e5225b02c4155ac4236e4912603df2ab08dbfc2f4fef08ce598c8@buzz.block.builderlab.xyz> Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Luke Tornquist <[email protected]>
1 parent 58c52c9 commit a5d139e

2 files changed

Lines changed: 22 additions & 21 deletions

File tree

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Trigger retirement deployment
22

33
Three migrations drop database triggers and functions whose work the relay
4-
now does in application code. They ship in one release:
4+
now does in application code. They ship together:
55

66
| Migration | Drops | Application replacement |
77
| --- | --- | --- |
@@ -11,16 +11,17 @@ now does in application code. They ship in one release:
1111

1212
## Required stop
1313

14-
**The first relay release that contains
15-
[#8325](https://github.com/block/buzz/pull/8325) is a required stop.** It also
16-
contains every other replacement above. `relay-v0.3.0` has the others but not
17-
#8325, so it is not enough.
14+
**A relay build at or after commit `68785206` (the merge of
15+
[#8325](https://github.com/block/buzz/pull/8325)) and before these migrations
16+
is a required stop.** Such a build contains every replacement above. No tagged
17+
relay release contains #8325: `relay-v0.3.0` has the others but not #8325, so
18+
a deployment on a tagged release must move to a stop build first.
1819

19-
Do not upgrade past the stop to the release with these migrations until no
20-
older relay runs anywhere: every pod and job, not only a rollout's new pods.
21-
The migrations cannot detect an older writer. If an operator upgrades straight
22-
from an older release, the first new pod applies the migrations while older
23-
pods are still serving:
20+
Do not upgrade past the stop build to one with these migrations until no older
21+
relay runs anywhere: every pod and job, not only a rollout's new pods. The
22+
migrations cannot detect an older writer. If an operator upgrades straight
23+
from an older build, the first new pod applies the migrations while older pods
24+
are still serving:
2425

2526
- a relay without #8325 has no floor check, so it accepts backdated channel
2627
events that replica reads can then skip;
@@ -30,7 +31,7 @@ pods are still serving:
3031

3132
## Procedure
3233

33-
1. Deploy the stop release. Check the image of every relay pod and job, and
34+
1. Deploy a stop build. Check the image of every relay pod and job, and
3435
wait until none runs an older one.
3536
2. Stop out-of-band writers (direct SQL, `COPY`, restores, seed scripts). Hold
3637
the replica breaker closed from before the migrations until every replica
@@ -39,16 +40,16 @@ pods are still serving:
3940
`DROP TRIGGER` statements take `ACCESS EXCLUSIVE` on `events` and its
4041
partitions, so event reads and writes can stall for up to that long. A
4142
lock timeout aborts that migration, which is safe to retry.
42-
- **Auto-migration on:** deploy the new release. Its first pod applies the
43+
- **Auto-migration on:** deploy the new build. Its first pod applies the
4344
migrations at startup.
4445
- **Auto-migration off:** run `buzz-admin migrate` with the target
4546
`DATABASE_URL`, confirm that it records 0089, 0090 and 0091, then deploy
46-
the new release. The new release assumes 0091 has run: against a
47+
the new build. The new build assumes 0091 has run: against a
4748
database without it, NIP-RS hard deletes fail closed with
48-
`check_violation`. The stop release works with all three applied.
49-
4. Once every relay runs the new release, run the one-off cleanup SQL in
49+
`check_violation`. The stop build works with all three applied.
50+
4. Once every relay runs the new build, run the one-off cleanup SQL in
5051
[#8211](https://github.com/block/buzz/pull/8211) once per database. While
51-
stop-release pods served after 0091, a replacement could leave a
52+
stop-build pods served after 0091, a replacement could leave a
5253
soft-deleted NIP-RS or mesh-status head that nothing purges any more. The
5354
cleanup is idempotent.
5455

@@ -63,9 +64,9 @@ PostgreSQL refuses with `2BP01`.
6364

6465
## Rollback
6566

66-
Roll back to the stop release, not further, and only with auto-migration off
67+
Roll back to the stop build, not further, and only with auto-migration off
6768
(`BUZZ_AUTO_MIGRATE=false`, or `migrate.autoMigrate=false` in the Helm chart).
68-
With it on, the stop release refuses a database that has migrations it does
69-
not know (`VersionMissing`) and does not start. With it off, the stop release
69+
With it on, the stop build refuses a database that has migrations it does
70+
not know (`VersionMissing`) and does not start. With it off, the stop build
7071
serves, but its startup check finds the floor trigger gone and keeps the
7172
replica fence closed, so cursor reads go to the writer.

‎migrations/0089_retire_created_at_floor.sql‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
SET LOCAL lock_timeout = '5s';
22

33
-- DESTRUCTIVE CONTRACT: deploy phase 1's application floor check to every
4-
-- writer pod/job first, with no rollback expected. The first relay release
5-
-- with it is a required stop (docs/trigger-retirement-deployment.md). Stop out-of-band writers
4+
-- writer pod/job first, with no rollback expected. A relay build with it is
5+
-- a required stop (docs/trigger-retirement-deployment.md). Stop out-of-band writers
66
-- and hold the replica breaker closed through this drop until replay catches
77
-- up. Old pods that already started do not recheck the guard on each probe.
88
-- Keep the 960-second application floor and the ordered heartbeat handshake.

0 commit comments

Comments
 (0)