Pass on troubleshooting guide (#1912)

website/docs/guides/troubleshooting.md

@@ -41,13 +41,17 @@ EOF
 
 Now change your shape URLs to use port `3001` instead of port 3000 and everything will run much faster 🚀
 
-### Clear data — how do I clear the server state?
+### Shape logs — how do I clear the server state?
 
-Electric creates resources, including a logical replication publication and replication slots in your Postgres database. Electric also stores [shape logs](/docs/api/http#shape-log) to disk.
+Electric writes [shape logs](/docs/api/http#shape-log) to disk.
 
-Sometimes in development you may want to clear this state. However, just restarting the services doesn't clear the underlying storage. This can lead to unexpected data in your database or shape logs.
+During development, you may want to clear this state. However, just restarting Electric doesn't clear the underlying storage, which can lead to unexpected behaviour.
 
-##### Solution — clear the storage volumes
+##### Solution — clear shape logs
+
+You can remove [```STORAGE_DIR```](https://electric-sql.com/docs/api/config#storage-dir) to delete all shape logs. This will ensure that following shape requests will be re-synced from scratch.
+
+###### Using docker
 
 If you're running using Docker Compose, the simplest solution is to bring the Postgres and Electric services down, using the `--volumes` flag to also clear their mounted storage volumes:
 
@@ -65,10 +69,33 @@ docker compose up
 
 ### WAL growth — why is my Postgres database storage filling up?
 
-Electric creates a logical replication publication in your Postgres database and adds tables dynamically (as you request shapes) to this publication.
+Electric creates a durable replication slot in Postgres to prevent data loss during downtime. 
+
+During normal execution, Electric consumes the WAL file and keeps advancing `confirmed_flush_lsn`. However, if Electric is disconnected, the WAL file accumulates the changes that haven't be delivered to Electric.
+
+##### Solution — Remove replication slot after Electric is gone
+
+If you're stopping Electric for the weekend, we recommend removing the ```electric_slot_default``` replication slot to prevent unbounded WAL growth. When Electric restarts, if it doesn't find the replication slot at resume point, it will recreate the replication slot and drop all shape logs.
+
+You can also control the size of the WAL with [```wal_keep_size```](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-WAL-KEEP-SIZE). On restart, Electric will detect if the WAL is past the resume point too.
+
+## IPv6 support
+
+If Electric or Postgres are running behind a IPv6 network, you might have perform additional configurations on your network.
+
+### Postgres running behind Ipv6 network
+
+In order for Electric to connect to Postgres over IPv6, you need to set [`ELECTRIC_DATABASE_USE_IPV6`](/docs/api/config#database-use-ipv6) to `true`.
+
+#### Local development
+If you're running Electric on your own computer, check if you have IPv6 support by opening [test-ipv6.com](https://test-ipv6.com). If you see "No IPv6 address detected" on that page, consider `ssh`ing into another machine or using a VPN service that works with IPv6 networks.
+
+When running Electric in a Docker container, there's an additional hurdle in that Docker does not enable IPv6 out-of-the-box. Follow the [official guide](https://docs.docker.com/config/daemon/ipv6/#use-ipv6-for-the-default-bridge-network) to configure your Docker daemon for IPv6.
+
+#### Cloud
 
-If you don't consume this publication, the WAL can fill up and your Postgres database can run out of storage space. A common way for this to happen is that you create an Electric publication and then stop running Electric.
+If you're running Electric in a Cloud provider, you need to ensure that your VPC is configured with IPv6 support. Check your Cloud provider documentation to learn how to set it up.
 
-##### Solution — run Electric
+### Electric running behind Ipv6 network
 
-The simplest way to avoid this is to make sure you're running the Electric sync service against Postgres. This will consume the publication and allow the WAL to be released.
+By default Electric only binds to IPv4 addresses. You need to set [`ELECTRIC_LISTEN_ON_IPV6`](/docs/api/config#electric-use-ipv6) to `true` to bind to bind to IPv6 addresses as well.

website/docs/integrations/fly.md

@@ -29,7 +29,7 @@ One of Fly's specialities is deploying Elixir applications. So Fly is especially
 
 [Fly Postgres](https://fly.io/docs/postgres) is not a managed Postgres service. See the general advice on [Running Postgres](/docs/guides/deployment#_1-running-postgres) in the deployment guide for information on how to configure Postgres to work with Electric.
 
-Fly's [Supabase Postgres](https://fly.io/docs/supabase) is a managed Postgres service, powered by [Supabase](./supabase). If you use it, make sure to connect on the IPv6 `DATABASE_URL` rather than the `DATABASE_POOLER_URL` and see the [Supabase guide](./supabase#deploy-postgres) for more context.
+Fly's [Supabase Postgres](https://fly.io/docs/supabase) is a managed Postgres service, powered by [Supabase](./supabase). If you use it, make sure to connect on the IPv6 `DATABASE_URL` rather than the `DATABASE_POOLER_URL`. See the [Supabase deployment docs](./supabase#deploy-postgres) and the IPv6 section of the [troubleshooting guide](/docs/guides/troubleshooting#ipv6-support) for more information about IPv6 support.
 
 ### Deploy Electric
 

website/docs/integrations/gcp.md

@@ -63,7 +63,7 @@ For example, you can deploy Electric on a [Container-Optimized OS](https://cloud
 > We **don't recommend** that you use [Cloud Run](https://cloud.google.com/run) to deploy the Electric sync service because Cloud Run uses an in-memory filesystem and does not provide persistent file storage for Shape logs.
 
 > [!Warning] IPv6 support
-> If you're connecting to Postgres over IPv6 (for example, if you're [connecting to Supabase Postgres](./supabase#troubleshooting-ipv6)) then you may need to be on a Premium Network Tier to configure IPv6 for your VPC. See [this article](https://cloud.google.com/vpc/docs/subnets#ipv6-ranges) for more details.
+> If you're connecting to Postgres over IPv6, (for example, if you're [connecting to Supabase Postgres](./supabase#deploy-postgres)) then you may need to [enable IPv6 support](/docs/guides/troubleshooting#ipv6-support) and be on a [Premium Network Tier](https://cloud.google.com/vpc/docs/subnets#ipv6-ranges).
 
 ### Deploy your app
 

website/docs/integrations/supabase.md

@@ -43,11 +43,7 @@ docker run -it \
 
 #### Troubleshooting IPv6
 
-The network where Electric is running must support IPv6. If you're running Electric on your own computer, check if you have IPv6 support by opening [test-ipv6.com](https://test-ipv6.com). If you see "No IPv6 address detected" on that page, consider `ssh`ing into another machine or using a VPN service that works with IPv6 networks.
-
-When running Electric in a Docker container, there's an additional hurdle in that Docker does not enable IPv6 out-of-the-box. Follow the [official guide](https://docs.docker.com/config/daemon/ipv6/#use-ipv6-for-the-default-bridge-network) to configure your Docker daemon for IPv6.
-
-If you're subscribed to the Pro or Team plan on Supabase Platform, you can side-step those hurdles by purchasing the [IPv4 add-on](https://supabase.com/docs/guides/platform/ipv4-address#enabling-the-add-on) to make your database host available at an IPv4 address.
+When connecting to a Supabase Postgres, you either need to make sure Electric and its network supports IPv6, or you need to be on a Pro or Team plan with Supabase Platform to enable their IPv4 add-on. See the [troubleshooting guide on IPv6](/docs/guides/troubleshooting#ipv6-support) for tips on enabling IPv6 support for Electric. Or see [this Supabase guide](https://supabase.com/docs/guides/platform/ipv4-address#enabling-the-add-on) for information about enabling their IPv4 add-on.
 
 > [!Tip] Need somewhere to host Electric?
 > If you need to deploy Electric, then [Supabase works great](https://supabase.com/blog/postgres-on-fly-by-supabase) with [Fly.io](./fly#deploy-electric).