docs(website): add upgrading guide for rolling deployments#4094
Draft
docs(website): add upgrading guide for rolling deployments#4094
Conversation
Add a new guide covering how to upgrade Electric with minimal disruption using rolling deployments, with shared storage (recommended) and separate storage (ephemeral) scenarios. Includes Docker Compose, Kubernetes, and AWS ECS examples. Also documents two previously undocumented config options: CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWN and ELECTRIC_TEMPORARY_REPLICATION_SLOT_USE_RANDOM_NAME. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for electric-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
balegas
approved these changes
Apr 7, 2026
Contributor
balegas
left a comment
balegas
left a comment
There was a problem hiding this comment.
Apply suggestions as you see fit. happy to discuss things we're not aligned on
Restructure the upgrading guide based on review feedback: - Add overview section with read-only mode explanation and comparison table - Lighten advisory lock section, clarify it doesn't conflict with other locks - Move lock breaker to info callout - Reorder ephemeral options: temporary slots first, separate IDs second - Generalize health check warning to cover both K8s and ECS - Add EFS performance caveat - Move SQLite/NFS warning to troubleshooting, link from guide - Add replication slot recreation section to troubleshooting - Remove redundant "When to use" in ephemeral section - Fix broken config.md cross-reference after option reorder - Add rolling upgrade caveat to deployment.md readiness probe section - Add upgrading cross-reference from sharding.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
msfstef
commented
Apr 7, 2026
Contributor
Author
msfstef
left a comment
msfstef
left a comment
There was a problem hiding this comment.
Addressed all review points:
- Overview section added — covers read-only mode, advisory lock concept, and includes the comparison table upfront so readers can self-select their path. Advisory lock section is now lighter.
- Lock breaker → info callout, advisory lock clarified as not conflicting with other locks in the system
- EFS discouraged with a performance warning noting it only suits small deployments
- SQLite/NFS warning → troubleshooting with inline link. Also added a replication slot recreation troubleshooting section explaining full-resync implications, linked from the temporary slots warning.
- Health check warning generalized to cover both K8s and ECS (not K8s-specific anymore). Also added a caveat to
deployment.md's readiness probe section since it recommendsexecprobes that would deadlock during rolling upgrades. - Options reordered: temporary slots first (Option A), separate stream IDs second (Option B). Comparison table columns match.
- Redundant "When to use" removed from ephemeral section, folded into intro paragraph. Added note that shared-storage platform examples apply here too (minus the volume mount).
- Fixed broken
config.mdcross-reference (#option-b→#option-a) after the reorder.
- Consolidate temporary slots and separate stream IDs into a single "separate storage" strategy (both require sticky sessions, cause 409s) - Simplify comparison table to shared vs separate storage - Reframe health check semantics: 200=active, 202=ready - Replace ECS EFS example with EC2 host volumes + placement constraints, mention EFS as alternative with performance caveats - Move inline troubleshooting to dedicated troubleshooting page - Fix anchor references after heading renames Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…advice - Remove deploy.png icon to avoid duplicating deployment guide - Merge EFS tip and network filesystem bullet into a single warning about IO performance on network filesystems - Remove redundant troubleshooting link from configuration section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
website/docs/guides/upgrading.md) covering how to upgrade Electric with minimal disruption using rolling deploymentsconfig.md:CLEANUP_REPLICATION_SLOTS_ON_SHUTDOWNandELECTRIC_TEMPORARY_REPLICATION_SLOT_USE_RANDOM_NAMEContext: PR #4075 introduced read-only mode for shared-disk rolling deploys. Discord conversations showed users struggling with rolling deploy patterns on ECS/Kubernetes.
Test plan
npm run devinwebsite/and verify the guide renders at/docs/guides/upgrading/docs/api/config🤖 Generated with Claude Code