feat: add configurable MySQL session timeout to prevent disconnection during long operations

libraz · libraz · commit 91972e5c9fab · 2025-11-20T14:08:35.000+09:00
Add session_timeout_sec configuration parameter to prevent MySQL connection
timeouts during long-running operations such as snapshot building. The timeout
is applied to both wait_timeout and interactive_timeout session variables.

Changes:
- Add session_timeout_sec to MySQL configuration (default: 3600 seconds)
- Implement session timeout setting in Connection::Connect()
- Add validation (min: 60, max: 86400 seconds)
- Add timeout hints in error messages for connection failures
- Update documentation (EN/JA) with SELECT privilege requirements
- Add comprehensive unit tests for timeout configuration
- Update example configs and RPM packaging
- Remove unused test-diff.conf.example file

This prevents "MySQL server has gone away" errors during operations that
exceed the default MySQL timeout (typically 8 hours, but can be lower).
diff --git a/.test-diff.conf.example b/.test-diff.conf.example
diff --git a/docs/en/configuration.md b/docs/en/configuration.md
@@ -107,6 +107,8 @@ mysql:
   binlog_format: "ROW"              # Binary log format (required: ROW)
   binlog_row_image: "FULL"          # Row image format (required: FULL)
   connect_timeout_ms: 3000          # Connection timeout in milliseconds
+  session_timeout_sec: 3600         # Session timeout in seconds (default: 3600 = 1 hour)
+                                    # Prevents disconnection during long operations like snapshot building
 
   # SSL/TLS settings (optional but recommended for production)
   ssl_enable: false                 # Enable SSL/TLS
@@ -129,6 +131,7 @@ mysql:
 | `binlog_format` | string | `ROW` | Binary log format (must be ROW) | ❌ No |
 | `binlog_row_image` | string | `FULL` | Row image format (must be FULL) | ❌ No |
 | `connect_timeout_ms` | integer | `3000` | Connection timeout in milliseconds | ✅ Yes |
+| `session_timeout_sec` | integer | `3600` | Session timeout in seconds - prevents disconnection during long operations like snapshot building | ✅ Yes |
 | `ssl_enable` | boolean | `false` | Enable SSL/TLS connection | ✅ Yes |
 | `ssl_ca` | string | `` | Path to CA certificate file | ✅ Yes |
 | `ssl_cert` | string | `` | Path to client certificate file | ✅ Yes |
diff --git a/docs/en/replication.md b/docs/en/replication.md
@@ -48,13 +48,24 @@ Create a user with replication privileges:
 -- Create replication user
 CREATE USER 'repl_user'@'%' IDENTIFIED BY 'your_password';
 
--- Grant replication privileges
+-- Grant replication privileges (for binlog reading and GTID information)
 GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'repl_user'@'%';
 
+-- Grant SELECT privilege for snapshot creation (REQUIRED)
+-- Note: SELECT privilege on target tables is necessary for snapshot building
+GRANT SELECT ON database_name.table_name TO 'repl_user'@'%';
+
 -- Apply changes
 FLUSH PRIVILEGES;
 ```
 
+**Important Notes:**
+
+1. **REPLICATION CLIENT privilege is required**: Necessary for retrieving GTID information
+2. **SELECT privilege is required**: Necessary for reading table data during initial snapshot creation
+3. **No restart required**: `GRANT` statements are applied online and take effect immediately
+4. **Principle of least privilege**: When synchronizing multiple tables, grant SELECT privilege for each table individually
+
 ### Security Considerations
 
 - MySQL credentials are transmitted in plain text unless your MySQL server requires TLS. Place MygramDB close to MySQL on a trusted network, or terminate TLS/SSH tunnels in front of it when replicating across untrusted links.
diff --git a/docs/ja/configuration.md b/docs/ja/configuration.md
@@ -107,6 +107,8 @@ mysql:
   binlog_format: "ROW"              # バイナリログ形式(必須: ROW)
   binlog_row_image: "FULL"          # 行イメージ形式(必須: FULL)
   connect_timeout_ms: 3000          # 接続タイムアウト(ミリ秒)
+  session_timeout_sec: 3600         # セッションタイムアウト(秒、デフォルト: 3600 = 1時間)
+                                    # スナップショット作成などの長時間処理中の切断を防ぐ
 
   # SSL/TLS設定(オプションだが本番環境では推奨)
   ssl_enable: false                 # SSL/TLSを有効化
@@ -129,6 +131,7 @@ mysql:
 | `binlog_format` | string | `ROW` | バイナリログ形式(ROWである必要がある) | ❌ 不可 |
 | `binlog_row_image` | string | `FULL` | 行イメージ形式(FULLである必要がある) | ❌ 不可 |
 | `connect_timeout_ms` | integer | `3000` | 接続タイムアウト(ミリ秒) | ✅ 可能 |
+| `session_timeout_sec` | integer | `3600` | セッションタイムアウト(秒) - スナップショット作成などの長時間処理中の切断を防ぐ | ✅ 可能 |
 | `ssl_enable` | boolean | `false` | SSL/TLS接続を有効化 | ✅ 可能 |
 | `ssl_ca` | string | `` | CA証明書ファイルへのパス | ✅ 可能 |
 | `ssl_cert` | string | `` | クライアント証明書ファイルへのパス | ✅ 可能 |
diff --git a/docs/ja/replication.md b/docs/ja/replication.md
@@ -48,13 +48,24 @@ SET GLOBAL binlog_format = ROW;
 -- レプリケーションユーザーを作成
 CREATE USER 'repl_user'@'%' IDENTIFIED BY 'your_password';
 
--- レプリケーション権限を付与
+-- レプリケーション権限を付与（binlog読み取りとGTID情報取得用）
 GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'repl_user'@'%';
 
+-- スナップショット作成用のSELECT権限を付与（必須）
+-- 注意: 対象テーブルに対するSELECT権限が必要です
+GRANT SELECT ON database_name.table_name TO 'repl_user'@'%';
+
 -- 変更を適用
 FLUSH PRIVILEGES;
 ```
 
+**重要な注意事項:**
+
+1. **REPLICATION CLIENT権限は必須**: GTID情報を取得するために必要です
+2. **SELECT権限は必須**: 初期スナップショット作成時にテーブルデータを読み取るために必要です
+3. **権限の追加は再起動不要**: `GRANT`文はオンラインで即座に反映されます
+4. **最小権限の原則**: 複数のテーブルを同期する場合は、各テーブルごとにSELECT権限を付与してください
+
 ### セキュリティ上の注意
 
 - MySQL が TLS を必須にしていない場合、MygramDB から送信される資格情報は平文のままになります。信頼できるネットワーク内に配置するか、TLS/SSH トンネルなどで暗号化された経路を確保してください。
diff --git a/examples/config.json b/examples/config.json
@@ -9,6 +9,7 @@
     "binlog_format": "ROW",
     "binlog_row_image": "FULL",
     "connect_timeout_ms": 3000,
+    "session_timeout_sec": 3600,
     "ssl_enable": false
   },
   "tables": [
diff --git a/examples/config.yaml b/examples/config.yaml
@@ -20,6 +20,8 @@ mysql:
   binlog_format: "ROW"              # Binary log format (default: ROW, required for replication)
   binlog_row_image: "FULL"          # Row image format (default: FULL, required for replication)
   connect_timeout_ms: 3000          # Connection timeout in milliseconds (default: 3000)
+  session_timeout_sec: 3600         # Session timeout in seconds (default: 3600 = 1 hour)
+                                    # Prevents disconnection during long operations like snapshot building
   # SSL/TLS settings (optional but highly recommended for production)
   ssl_enable: false                 # Enable SSL/TLS (default: false)
   # ssl_ca: "/path/to/ca-cert.pem" # CA certificate for SSL/TLS
diff --git a/src/app/server_orchestrator.cpp b/src/app/server_orchestrator.cpp
@@ -212,6 +212,7 @@ mygram::utils::Expected<void, mygram::utils::Error> ServerOrchestrator::Initiali
   mysql_config.connect_timeout = deps_.config.mysql.connect_timeout_ms / kMillisecondsPerSecond;
   mysql_config.read_timeout = deps_.config.mysql.read_timeout_ms / kMillisecondsPerSecond;
   mysql_config.write_timeout = deps_.config.mysql.write_timeout_ms / kMillisecondsPerSecond;
+  mysql_config.session_timeout_sec = deps_.config.mysql.session_timeout_sec;
   mysql_config.ssl_enable = deps_.config.mysql.ssl_enable;
   mysql_config.ssl_ca = deps_.config.mysql.ssl_ca;
   mysql_config.ssl_cert = deps_.config.mysql.ssl_cert;
@@ -440,6 +441,7 @@ mygram::utils::Expected<void, mygram::utils::Error> ServerOrchestrator::HandleMy
       .connect_timeout = static_cast<uint32_t>(new_config.mysql.connect_timeout_ms / kMillisecondsPerSecond),
       .read_timeout = static_cast<uint32_t>(new_config.mysql.read_timeout_ms / kMillisecondsPerSecond),
       .write_timeout = static_cast<uint32_t>(new_config.mysql.write_timeout_ms / kMillisecondsPerSecond),
+      .session_timeout_sec = static_cast<uint32_t>(new_config.mysql.session_timeout_sec),
       .ssl_enable = new_config.mysql.ssl_enable,
       .ssl_ca = new_config.mysql.ssl_ca,
       .ssl_cert = new_config.mysql.ssl_cert,
diff --git a/src/config/config-schema.json b/src/config/config-schema.json
@@ -77,6 +77,13 @@
           "minimum": 1000,
           "maximum": 86400000
         },
+        "session_timeout_sec": {
+          "type": "integer",
+          "description": "Session timeout in seconds (wait_timeout and interactive_timeout) - prevents disconnection during long operations like snapshot building",
+          "default": 3600,
+          "minimum": 60,
+          "maximum": 86400
+        },
         "ssl_enable": {
           "type": "boolean",
           "description": "Enable SSL/TLS for MySQL connection",
diff --git a/src/config/config.cpp b/src/config/config.cpp
@@ -104,6 +104,9 @@ MysqlConfig ParseMysqlConfig(const json& json_obj) {
   if (json_obj.contains("write_timeout_ms")) {
     config.write_timeout_ms = json_obj["write_timeout_ms"].get<int>();
   }
+  if (json_obj.contains("session_timeout_sec")) {
+    config.session_timeout_sec = json_obj["session_timeout_sec"].get<int>();
+  }
   if (json_obj.contains("ssl_enable")) {
     config.ssl_enable = json_obj["ssl_enable"].get<bool>();
   }
diff --git a/src/config/config.h b/src/config/config.h
@@ -22,6 +22,7 @@ constexpr int kMysqlPort = 3306;
 constexpr int kMysqlConnectTimeoutMs = 3000;
 constexpr int kMysqlReadTimeoutMs = 3600000;   // 1 hour (for long-running binlog connections)
 constexpr int kMysqlWriteTimeoutMs = 3600000;  // 1 hour
+constexpr int kMysqlSessionTimeoutSec = 3600;  // 1 hour (prevents disconnection during snapshot building)
 
 // Posting list defaults
 constexpr int kPostingBlockSize = 128;
@@ -71,6 +72,7 @@ struct MysqlConfig {
   int connect_timeout_ms = defaults::kMysqlConnectTimeoutMs;
   int read_timeout_ms = defaults::kMysqlReadTimeoutMs;
   int write_timeout_ms = defaults::kMysqlWriteTimeoutMs;
+  int session_timeout_sec = defaults::kMysqlSessionTimeoutSec;
   // SSL/TLS settings
   bool ssl_enable = false;
   std::string ssl_ca;
diff --git a/src/mysql/connection.cpp b/src/mysql/connection.cpp
@@ -147,6 +147,20 @@ mygram::utils::Expected<void, mygram::utils::Error> Connection::Connect(const st
         MakeError(ErrorCode::kMySQLConnectionFailed, last_error_, config_.host + ":" + std::to_string(config_.port)));
   }
 
+  // Set session timeout to prevent disconnection during long-running operations
+  // (e.g., snapshot building which can take several minutes)
+  // This only affects the current session and does not impact other MySQL connections
+  const std::string set_timeout_query =
+      "SET SESSION wait_timeout = " + std::to_string(config_.session_timeout_sec) +
+      ", SESSION interactive_timeout = " + std::to_string(config_.session_timeout_sec);
+  if (mysql_query(mysql_, set_timeout_query.c_str()) != 0) {
+    // Log warning but don't fail connection - timeout setting is not critical
+    SetMySQLError();
+    spdlog::warn("Failed to set session timeouts (non-critical): {}", last_error_);
+  } else {
+    spdlog::debug("Session timeouts set to {} seconds", config_.session_timeout_sec);
+  }
+
   std::string context_prefix = context.empty() ? "" : "[" + context + "] ";
   std::string db_info = config_.database.empty() ? "" : "/" + config_.database;
   std::string ssl_info = config_.ssl_enable ? " (SSL/TLS)" : "";
diff --git a/src/mysql/connection.h b/src/mysql/connection.h
@@ -78,9 +78,11 @@ class Connection {
     std::string user;
     std::string password;
     std::string database;
-    uint32_t connect_timeout = 10;  // Default timeout in seconds
-    uint32_t read_timeout = 30;     // Default timeout in seconds
-    uint32_t write_timeout = 30;    // Default timeout in seconds
+    uint32_t connect_timeout = 10;        // Default timeout in seconds
+    uint32_t read_timeout = 30;           // Default timeout in seconds
+    uint32_t write_timeout = 30;          // Default timeout in seconds
+    uint32_t session_timeout_sec = 3600;  // Session timeout in seconds (default: 1 hour)
+                                          // Prevents disconnection during long operations like snapshot building
     // SSL/TLS settings
     bool ssl_enable = false;
     std::string ssl_ca;
diff --git a/src/server/sync_operation_manager.cpp b/src/server/sync_operation_manager.cpp
@@ -74,6 +74,13 @@ std::string SyncOperationManager::StartSync(const std::string& table_name) {
     return ResponseFormatter::FormatError("Memory critically low. Cannot start SYNC.");
   }
 
+  // Log session timeout warning
+  uint32_t session_timeout = full_config_->mysql.session_timeout_sec;
+  spdlog::info(
+      "Starting SYNC for table '{}' with MySQL session_timeout_sec={} "
+      "(ensure this is sufficient for snapshot duration)",
+      table_name, session_timeout);
+
   // Mark as syncing
   {
     std::lock_guard<std::mutex> sync_lock(syncing_tables_mutex_);
@@ -255,11 +262,13 @@ void SyncOperationManager::BuildSnapshotAsync(const std::string& table_name) {
     }
 
     // Connect to MySQL
-    mysql::Connection::Config mysql_config{.host = full_config_->mysql.host,
-                                           .port = static_cast<uint16_t>(full_config_->mysql.port),
-                                           .user = full_config_->mysql.user,
-                                           .password = full_config_->mysql.password,
-                                           .database = full_config_->mysql.database};
+    mysql::Connection::Config mysql_config{
+        .host = full_config_->mysql.host,
+        .port = static_cast<uint16_t>(full_config_->mysql.port),
+        .user = full_config_->mysql.user,
+        .password = full_config_->mysql.password,
+        .database = full_config_->mysql.database,
+        .session_timeout_sec = static_cast<uint32_t>(full_config_->mysql.session_timeout_sec)};
 
     auto mysql_conn = std::make_unique<mysql::Connection>(mysql_config);
 
@@ -377,6 +386,18 @@ void SyncOperationManager::BuildSnapshotAsync(const std::string& table_name) {
       }
     } else {
       std::string error_msg = result.error().message();
+
+      // Check if error might be session timeout related
+      bool is_timeout_related =
+          (error_msg.find("disconnected") != std::string::npos || error_msg.find("timeout") != std::string::npos ||
+           error_msg.find("connection") != std::string::npos || error_msg.find("Lost connection") != std::string::npos);
+
+      if (is_timeout_related) {
+        uint32_t session_timeout = full_config_->mysql.session_timeout_sec;
+        error_msg += " (check if session_timeout_sec=" + std::to_string(session_timeout) +
+                     " is sufficient for snapshot duration)";
+      }
+
       update_state([&error_msg](SyncState& state) {
         state.status = "FAILED";
         state.error_message = error_msg;
diff --git a/support/rpm/mygramdb.spec b/support/rpm/mygramdb.spec
@@ -59,9 +59,9 @@ find %{buildroot}/usr/lib64 -name '*.so*' -delete 2>/dev/null || true
 find %{buildroot}/usr/lib -name 'libmygramclient.a' -delete 2>/dev/null || true
 find %{buildroot}/usr/lib -name 'libmygramclient.so*' -delete 2>/dev/null || true
 
-# Create config directory
+# Create config directory and install example config
 install -d %{buildroot}%{_sysconfdir}/%{name}
-install -m 644 examples/config-minimal.yaml %{buildroot}%{_sysconfdir}/%{name}/config.yaml.example
+install -m 644 examples/config.yaml %{buildroot}%{_sysconfdir}/%{name}/config.yaml.example
 
 # Create systemd service file
 install -d %{buildroot}/usr/lib/systemd/system
@@ -87,14 +87,16 @@ NoNewPrivileges=true
 PrivateTmp=true
 ProtectSystem=strict
 ProtectHome=true
-ReadWritePaths=/var/lib/mygramdb
+ReadWritePaths=/var/lib/mygramdb /var/log/mygramdb
 
 [Install]
 WantedBy=multi-user.target
 EOF
 
-# Create data directory
+# Create data directories
 install -d %{buildroot}%{_sharedstatedir}/%{name}
+install -d %{buildroot}%{_sharedstatedir}/%{name}/dumps
+install -d %{buildroot}%{_localstatedir}/log/%{name}
 
 %pre
 getent group mygramdb >/dev/null || groupadd -r mygramdb
@@ -105,9 +107,13 @@ exit 0
 
 %post
 %systemd_post %{name}.service
+# Set ownership for data and log directories
 if [ -d %{_sharedstatedir}/%{name} ]; then
     chown -R mygramdb:mygramdb %{_sharedstatedir}/%{name}
 fi
+if [ -d %{_localstatedir}/log/%{name} ]; then
+    chown -R mygramdb:mygramdb %{_localstatedir}/log/%{name}
+fi
 
 %preun
 %systemd_preun %{name}.service
@@ -124,6 +130,8 @@ fi
 %dir %{_sysconfdir}/%{name}
 %config(noreplace) %{_sysconfdir}/%{name}/config.yaml.example
 %dir %attr(0755,mygramdb,mygramdb) %{_sharedstatedir}/%{name}
+%dir %attr(0755,mygramdb,mygramdb) %{_sharedstatedir}/%{name}/dumps
+%dir %attr(0755,mygramdb,mygramdb) %{_localstatedir}/log/%{name}
 
 # Static build - no devel package needed
 
diff --git a/tests/config/config_test.cpp b/tests/config/config_test.cpp

Original file line number	Diff line number	Diff line change
`@@ -104,6 +104,9 @@ MysqlConfig ParseMysqlConfig(const json& json_obj) {`
`104`	`104`	`if (json_obj.contains("write_timeout_ms")) {`
`105`	`105`	`config.write_timeout_ms = json_obj["write_timeout_ms"].get<int>();`
`106`	`106`	`}`
	`107`	`+ if (json_obj.contains("session_timeout_sec")) {`
	`108`	`+ config.session_timeout_sec = json_obj["session_timeout_sec"].get<int>();`
	`109`	`+ }`
`107`	`110`	`if (json_obj.contains("ssl_enable")) {`
`108`	`111`	`config.ssl_enable = json_obj["ssl_enable"].get<bool>();`
`109`	`112`	`}`