# app/electric

> 使用 Pigsty 托管的 PostgreSQL 部署 Electric 实时同步服务

---

LLMS index: [llms.txt](/llms.txt)

---

`app/electric` 配置模板提供了部署 Electric SQL 实时同步服务的参考配置，实现 PostgreSQL 到客户端的实时数据同步。


--------

## 配置概览

- 配置名称： `app/electric`
- 节点数量： 单节点
- 配置说明：使用 Pigsty 托管的 PostgreSQL 部署 Electric 实时同步
- 适用系统：`el8`, `el9`, `el10`, `d12`, `d13`, `u22`, `u24`, `u26`
- 适用架构：`x86_64`, `aarch64`
- 相关配置：[`meta`](/docs/conf/meta/)

启用方式：

```bash
./configure -c app/electric [-i <primary_ip>]
```


--------

## 配置内容

源文件地址：[`pigsty/conf/app/electric.yml`](https://github.com/pgsty/pigsty/blob/main/conf/app/electric.yml)

<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># File      :   electric.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Desc      :   pigsty config for running 1-node electric app</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Ctime     :   2025-03-29</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Mtime     :   2025-12-12</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Docs      :   https://pigsty.io/docs/app/electric</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># Copyright :   2018-2026  Ruohang Feng / Vonng (rh@vonng.com)</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># tutorial: https://pigsty.io/docs/app/electric</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># quick start: https://electric-sql.com/docs/quickstart</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># how to use this template:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c">#  curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./bootstrap                 # prepare local repo &amp; ansible</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./configure -c app/electric # use this electric config template</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># vi pigsty.yml               # IMPORTANT: CHANGE CREDENTIALS!!</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./deploy.yml                # install pigsty &amp; pgsql &amp; minio</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./docker.yml                # install docker &amp; docker-compose</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="c"># ./app.yml                   # install electric with docker-compose</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">all</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">children</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># infra cluster for proxy, monitor, alert, etc..</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">infra</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">10.10.10.10</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">infra_seq</span><span class="p">:</span><span class="w"> </span><span class="m">1</span><span class="w"> </span>}<span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">vars</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">app</span><span class="p">:</span><span class="w"> </span><span class="l">electric</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">apps</span><span class="p">:</span><span class="w">       </span><span class="c"># define all applications</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">electric</span><span class="p">:</span><span class="w"> </span><span class="c"># app name, should have corresponding ~/pigsty/app/electric folder</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">            </span><span class="nt">conf</span><span class="p">:</span><span class="w">   </span><span class="c"># override /opt/electric/.env config file : https://electric-sql.com/docs/api/config</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">DATABASE_URL</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;postgresql://electric:DBUser.Electric@10.10.10.10:5432/electric?sslmode=require&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">ELECTRIC_PORT</span><span class="p">:</span><span class="w"> </span><span class="m">8002</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">ELECTRIC_PROMETHEUS_PORT</span><span class="p">:</span><span class="w"> </span><span class="m">8003</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="nt">ELECTRIC_INSECURE</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">              </span><span class="c">#ELECTRIC_SECRET: 1U6ItbhoQb4kGUU5wXBLbxvNf</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># etcd cluster for ha postgres</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">etcd</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">10.10.10.10</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">etcd_seq</span><span class="p">:</span><span class="w"> </span><span class="nt">1 } }, vars</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">etcd_cluster</span><span class="p">:</span><span class="w"> </span><span class="l">etcd } }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># minio cluster, s3 compatible object storage</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># postgres example cluster: pg-meta</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg-meta</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">hosts</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">10.10.10.10</span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">pg_seq</span><span class="p">:</span><span class="w"> </span><span class="nt">1, pg_role</span><span class="p">:</span><span class="w"> </span><span class="l">primary } }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">vars</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">pg_cluster</span><span class="p">:</span><span class="w"> </span><span class="l">pg-meta</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">pg_users</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- {<span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="nt">electric ,password</span><span class="p">:</span><span class="w"> </span><span class="nt">DBUser.Electric ,pgbouncer</span><span class="p">:</span><span class="w"> </span><span class="nt">true , replication</span><span class="p">:</span><span class="w"> </span><span class="nt">true ,roles</span><span class="p">:</span><span class="w"> </span><span class="nt">[dbrole_admin] ,comment</span><span class="p">:</span><span class="w"> </span><span class="l">electric main user }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">pg_databases</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>{<span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="nt">electric , owner</span><span class="p">:</span><span class="w"> </span><span class="l">electric }]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">pg_hba_rules</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span>- {<span class="w"> </span><span class="nt">user</span><span class="p">:</span><span class="w"> </span><span class="nt">electric , db</span><span class="p">:</span><span class="w"> </span><span class="nt">replication ,addr</span><span class="p">:</span><span class="w"> </span><span class="nt">infra ,auth</span><span class="p">:</span><span class="w"> </span><span class="nt">ssl ,title</span><span class="p">:</span><span class="w"> </span><span class="s1">&#39;allow electric intranet/docker ssl access&#39;</span><span class="w"> </span>}<span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="c"># Global Parameters</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="c">#==============================================================#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">vars</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Meta Data</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l">v4.5.0                  </span><span class="w"> </span><span class="c"># pigsty version string</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">admin_ip</span><span class="p">:</span><span class="w"> </span><span class="m">10.10.10.10</span><span class="w">             </span><span class="c"># admin node ip address</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">region</span><span class="p">:</span><span class="w"> </span><span class="l">default                  </span><span class="w"> </span><span class="c"># upstream mirror region: default|china|europe</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">node_tune</span><span class="p">:</span><span class="w"> </span><span class="l">oltp                  </span><span class="w"> </span><span class="c"># node tuning specs: oltp,olap,tiny,crit</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg_conf</span><span class="p">:</span><span class="w"> </span><span class="l">oltp.yml                </span><span class="w"> </span><span class="c"># pgsql tuning specs: {oltp,olap,tiny,crit}.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">docker_enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">              </span><span class="c"># enable docker on app group</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#docker_registry_mirrors: [&#34;https://docker.1panel.live&#34;,&#34;https://docker.1ms.run&#34;,&#34;https://docker.xuanyuan.me&#34;,&#34;https://registry-1.docker.io&#34;]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">proxy_env</span><span class="p">:</span><span class="w">                        </span><span class="c"># global proxy env when downloading packages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">no_proxy</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.myqcloud.com,*.tsinghua.edu.cn&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># http_proxy:  # set your proxy here: e.g http://user:pass@proxy.xxx.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># https_proxy: # set your proxy here: e.g http://user:pass@proxy.xxx.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="c"># all_proxy:   # set your proxy here: e.g http://user:pass@proxy.xxx.com</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">infra_portal</span><span class="p">:</span><span class="w">                     </span><span class="c"># domain names and upstream servers</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">home </span><span class="p">:</span><span class="w"> </span>{<span class="w"> </span><span class="nt">domain</span><span class="p">:</span><span class="w"> </span><span class="l">i.pigsty }</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">electric</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">domain</span><span class="p">:</span><span class="w"> </span><span class="l">elec.pigsty</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">endpoint</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;${admin_ip}:8002&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">websocket</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="w">               </span><span class="c"># apply free ssl cert with certbot: make cert</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">certbot</span><span class="p">:</span><span class="w"> </span><span class="l">odoo.pigsty         </span><span class="w"> </span><span class="c"># &lt;----- replace with your own domain name!</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Safe Guard</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># you can enable these flags after bootstrap, to prevent purging running etcd / pgsql instances</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">etcd_safeguard</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">             </span><span class="c"># prevent purging running etcd instance?</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg_safeguard</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">               </span><span class="c"># prevent purging running postgres instance? false by default</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Repo, Node, Packages</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">repo_enabled</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">node_repo_modules</span><span class="p">:</span><span class="w"> </span><span class="l">node,infra,pgsql</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg_version</span><span class="p">:</span><span class="w"> </span><span class="m">18</span><span class="w">                    </span><span class="c"># default postgres version</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#pg_extensions: [ pg18-time ,pg18-gis ,pg18-rag ,pg18-fts ,pg18-olap ,pg18-feat ,pg18-lang ,pg18-type ,pg18-util ,pg18-func ,pg18-admin ,pg18-stat ,pg18-sec ,pg18-fdw ,pg18-sim ,pg18-etl]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># PASSWORD : https://pigsty.io/docs/setup/security/</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c">#----------------------------------------------#</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">grafana_admin_password</span><span class="p">:</span><span class="w"> </span><span class="l">pigsty</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">grafana_view_password</span><span class="p">:</span><span class="w"> </span><span class="l">DBUser.Viewer</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg_admin_password</span><span class="p">:</span><span class="w"> </span><span class="l">DBUser.DBA</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg_monitor_password</span><span class="p">:</span><span class="w"> </span><span class="l">DBUser.Monitor</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">pg_replication_password</span><span class="p">:</span><span class="w"> </span><span class="l">DBUser.Replicator</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">patroni_password</span><span class="p">:</span><span class="w"> </span><span class="l">Patroni.API</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">haproxy_admin_password</span><span class="p">:</span><span class="w"> </span><span class="l">pigsty</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">minio_secret_key</span><span class="p">:</span><span class="w"> </span><span class="l">S3User.MinIO</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">etcd_root_password</span><span class="p">:</span><span class="w"> </span><span class="l">Etcd.Root</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">...</span><span class="w">
</span></span></span></code></pre></div>


--------

## 配置解读

`app/electric` 模板提供了 Electric SQL 实时同步服务的一键部署方案。

**Electric 是什么**：
- PostgreSQL 到客户端的实时数据同步服务
- 支持离线优先 (Local-first) 应用架构
- 通过逻辑复制实时同步数据变更
- 提供 HTTP API 供前端应用消费

**关键特性**：
- 使用 Pigsty 管理的 PostgreSQL 作为数据源
- 通过逻辑复制 (Logical Replication) 捕获数据变更
- 支持 SSL 加密连接
- 内置 Prometheus 指标端点

**访问方式**：

```bash
# Electric API 端点
http://elec.pigsty:8002

# Prometheus 指标
http://elec.pigsty:8003/metrics
```

**适用场景**：
- 构建离线优先 (Local-first) 应用
- 需要实时数据同步到客户端
- 移动应用和 PWA 的数据同步
- 协作应用的实时更新

**注意事项**：
- Electric 用户需要 `replication` 权限
- 需要启用 PostgreSQL 逻辑复制
- 生产环境建议使用 SSL 连接（已配置 `sslmode=require`）
