SQLpage容器时区设置的最佳实践

在使用SQLpage容器化部署时，正确显示本地时间戳是一个常见需求。本文将详细介绍如何为SQLpage容器设置时区，确保UI中的时间戳能够正确显示为本地时间而非UTC时间。

时区设置的重要性

在数据库应用中，时间戳的正确显示对于用户体验至关重要。默认情况下，SQLpage容器使用UTC时区，这可能导致显示的时间与用户期望的本地时间存在偏差。通过正确配置时区，可以确保时间相关数据以符合用户习惯的方式呈现。

常见配置方法分析

许多开发者尝试通过以下方式设置时区，但这些方法对SQLpage容器并不适用：

1. 环境变量方式：

   environment:
     TZ: "Australia/Sydney"
     TIME_ZONE: "Australia/Sydney"
     TIMEZONE: "Australia/Sydney"
   

2. 文件挂载方式：

   volumes:
     - /etc/localtime:/etc/localtime:ro
     - /etc/timezone:/etc/timezone:ro
   

3. SQL连接时设置：

   SET TIME ZONE 'Australia/Sydney';
   SET TIME_ZONE 'Australia/Sydney';
   SET TZ 'Australia/Sydney';
   

这些方法之所以无效，是因为SQLpage容器有自己特定的时区配置机制。

正确的配置方法

要为SQLpage容器正确设置时区，需要通过专门的on_connect.sql文件进行配置。以下是具体步骤：

1. 创建on_connect.sql文件

创建一个名为on_connect.sql的文件，内容如下：

SET @@SESSION.TIME_ZONE = "+11:00";  -- 对于悉尼时区

2. 正确的文件挂载方式

在docker-compose.yml中，确保将包含on_connect.sql的目录正确挂载到容器的/etc/sqlpage路径：

volumes:
  - ./sqlpage:/etc/sqlpage

3. 目录结构示例

正确的项目目录结构应如下所示：

.
├── docker-compose.yml
├── sqlpage
│   └── on_connect.sql
└── src
    └── index.sql

4. 验证配置

启动容器后，检查日志中是否出现以下信息，确认配置已生效：

Creating a custom SQL database connection handler from "/etc/sqlpage/on_connect.sql"

技术原理

SQLpage容器通过/etc/sqlpage/on_connect.sql文件在建立数据库连接时执行自定义SQL命令。这种方式比传统的环境变量或文件挂载更灵活，因为它：

1. 直接作用于数据库会话层面
2. 支持不同数据库引擎的特定语法
3. 可以在连接建立时执行多个配置命令

注意事项

1. 时区偏移量格式必须符合数据库要求，如"+11:00"表示悉尼时区
2. 确保挂载路径正确，文件权限适当
3. 不同数据库引擎(MySQL/PostgreSQL等)可能有略微不同的时区设置语法
4. 对于生产环境，建议测试不同时区的显示效果

通过以上方法，开发者可以确保SQLpage容器中的时间戳正确显示为本地时间，提升用户体验。