electric-sql/electric

Feature request: document why a shape handle might get deleted

Open

#2680 opened on May 6, 2025

View on GitHub
 (1 comment) (1 reaction) (0 assignees)Elixir (10,155 stars) (329 forks)batch import
documentationgood first issuehelp wanted

Description

Is your feature request related to a problem? Please describe. People wonder why shapes get deleted. Especially if they have very large shapes as recreating and reloading them into clients can get expensive.

If they understand why it's happening, they might be able to reduce how often shapes are recreated by e.g. preserving their shapes logs when restarting their Electric instance.

Describe the solution you'd like Document the reasons for shape deletions:

  1. the server is restarted and loses all its shape logs
  2. pg has an error of some sort that isn't recoverable so electric deletes all the shapes
  3. probably most common, there's a schema change to the table the shape uses so the log is missing the new data

Contributor guide

Tech stack
elixirpostgresql
Domain
documentationdatabase
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic understanding of Electric syncFamiliarity with PostgreSQL schema changes
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85
Research direction
Review the Electric source code to confirm the three reasons for shape deletions listed in the issue. Look at the shape management module (likely in lib/electric/shape.ex) to understand how shape handles are deleted. Also examine the documentation structure to decide where to add the new section, such as in a troubleshooting or FAQ page. Consider checking existing documentation for any related concepts.