資料儲存Storage

支援 MySQL / MariaDB 或平面檔。使用 MySQL 時，HikariCP 與 JDBC 驅動會在執行期下載，不需自行打包。

MySQL

storage:
  use_mysql: true
  mysql:
    host: localhost
    port: 3306
    database: vault
    username: root
    password: ""
    params: useSSL=false&serverTimezone=UTC
    pool:
      max: 10
      min_idle: 2
      connection_timeout_ms: 10000
      idle_timeout_ms: 600000
      max_lifetime_ms: 1800000

兩個鍵名很容易寫錯，而且寫錯不會報錯。

連線參數的鍵是 params，不是 properties
連線池參數必須巢狀在 pool: 底下，不能平放在 mysql:

寫錯只會靜默套用預設值 —— 你會以為設定生效了，實際上沒有。

資料表

啟動時自動建立，不需手動執行 SQL：

vault_balances         (uuid CHAR(36) PK, balance DECIMAL(19,4))
vault_charge_requests  (id BIGINT PK, recipient, sender, amount, created_at)

寫入時機

storage:
  save_on_transaction: true          # 交易後即時存檔（非同步）
  transaction_flush_delay_ticks: 20  # 去抖動視窗，20 tick = 1 秒
  autosave_seconds: 60               # 週期性安全網
  recover_emergency_dumps: true      # 啟動時補寫先前未成功的資料

transaction_flush_delay_ticks 越低越安全、資料庫往返越多；越高則相反。預設 20 tick 表示當機最多損失約一秒的交易。

平面檔

use_mysql: false 時餘額存在 plugins/Vault/balances.yml。格式是 balances.<uuid>: <金額>。平面檔無法只寫單列，每次 flush 都會重寫整個檔案 —— 但仍在非同步執行緒上，且只在有變動時才寫。

MySQL / MariaDB or flat file. With MySQL, HikariCP and the JDBC driver are downloaded at runtime, so nothing has to be bundled.

MySQL

storage:
  use_mysql: true
  mysql:
    host: localhost
    port: 3306
    database: vault
    username: root
    password: ""
    params: useSSL=false&serverTimezone=UTC
    pool:
      max: 10
      min_idle: 2
      connection_timeout_ms: 10000
      idle_timeout_ms: 600000
      max_lifetime_ms: 1800000

Two keys are easy to get wrong, and getting them wrong fails silently.

The connection string key is params, not properties
Pool settings must be nested under pool:, not flat under mysql:

A wrong key logs no error. It quietly falls back to the default, so the settings look applied when they are not.

Tables

Created automatically on startup; no manual SQL needed:

vault_balances         (uuid CHAR(36) PK, balance DECIMAL(19,4))
vault_charge_requests  (id BIGINT PK, recipient, sender, amount, created_at)

When writes happen

storage:
  save_on_transaction: true          # persist shortly after each transaction
  transaction_flush_delay_ticks: 20  # debounce window, 20 ticks = 1 second
  autosave_seconds: 60               # periodic safety net
  recover_emergency_dumps: true      # re-apply what a failed shutdown could not write

A lower transaction_flush_delay_ticks is safer but means more database round trips; higher is the reverse. The default of 20 ticks means a crash loses at most about one second of transactions.

Flat file

With use_mysql: false, balances live in plugins/Vault/balances.yml as balances.<uuid>: <amount>. A flat file cannot be written row by row, so each flush rewrites the whole file — but still off the main thread, and only when something changed.