Electric-SQL 存储目录配置问题解析

背景介绍

Electric-SQL 是一个开源的实时数据同步框架，它提供了本地持久化存储功能。在配置 Electric-SQL 时，开发者可以通过 ELECTRIC_STORAGE_DIR 环境变量来指定存储根目录。然而，当前版本中存在一个配置行为不一致的问题，值得开发者注意。

问题现象

当开发者仅设置 ELECTRIC_STORAGE_DIR 环境变量时，期望 Electric-SQL 的所有持久化数据（包括形状日志和持久化键值存储）都应该使用该目录作为根路径。但实际上，系统仍然会默认使用 ./persistent 目录，除非同时设置了以下两个额外的配置项：

1. ELECTRIC_STORAGE=file
2. ELECTRIC_PERSISTENT_STATE=file

这种行为与直觉相悖，也不符合最小惊讶原则（Principle of Least Surprise）。

技术分析

Electric-SQL 的持久化存储系统由两个主要组件构成：

1. 形状日志存储（Shape Log Store）：用于记录数据同步的形状信息
2. 持久化键值存储（Persistent KV Store）：用于保存本地状态

这两个组件默认都会使用磁盘存储，但在当前实现中，它们仅在被显式配置为文件存储模式时才会尊重 ELECTRIC_STORAGE_DIR 的设置。这种设计存在以下问题：

• 配置冗余：需要设置三个相关变量才能实现简单的存储目录自定义
• 行为不一致：默认使用磁盘存储但不使用配置的存储目录
• 文档误导：表面上看 ELECTRIC_STORAGE_DIR 应该足够控制存储位置

解决方案

该问题已被项目维护者修复。修复后的行为更加合理：

• 当 ELECTRIC_STORAGE_DIR 被设置时，无论是否显式配置存储类型为文件模式，都会使用该目录作为根路径
• 形状日志存储和持久化键值存储都会自动继承这一配置
• 保持向后兼容，不影响现有显式配置 ELECTRIC_STORAGE=file 和 ELECTRIC_PERSISTENT_STATE=file 的情况

最佳实践建议

对于使用 Electric-SQL 的开发者，建议：

1. 明确设置 ELECTRIC_STORAGE_DIR 以确保数据存储在预期位置
2. 在生产环境中，建议将存储目录设置在可靠的持久化卷上
3. 对于需要严格控制存储位置的情况，可以考虑同时设置所有相关配置项以确保行为一致
4. 测试存储配置是否生效，可以通过检查指定目录下是否生成了相关子目录来验证

总结

存储配置是数据库相关系统的重要方面。Electric-SQL 通过修复这个配置问题，使得存储目录的定制更加直观和一致。开发者现在可以更简单地控制数据存储位置，而无需担心隐式的默认行为带来的意外结果。这一改进提升了框架的易用性和可配置性，特别是在容器化部署和多租户场景下尤为重要。