低レベル API の設定オプション

akkaradb::engine::AkkEngineOptions は、AkkEngine::open() の前にエンジン構成を決めるための設定構造体です。エンジンを開いた後は、多くの構成要素を実行中に切り替える前提ではありません。

通常の組み込み用途では、まず paths.dataDir と永続化方針だけ決めれば十分です。それ以外の項目は、ストレージ調整、API サーバー、クラスタ実行時設定、ベンチマーク分離のために使います。

最小構成

akkaradb::engine::AkkEngineOptions opts;
opts.paths.dataDir = "data/akkaradb";
opts.wal.syncMode = akkaradb::engine::wal::WalSyncMode::ASYNC;
opts.runtime.sstPromoteReads = true;

auto db = akkaradb::engine::AkkEngine::open(std::move(opts));

paths.dataDir を設定すると、空のままの各パスはそこから自動的に導出されます。

フィールド	導出される値
`paths.walDir`	`<dataDir>/wal`
`paths.blobDir`	`<dataDir>/blobs`
`paths.sstDir`	`<dataDir>/sstable`
`paths.manifestPath`	`<dataDir>/manifest.akmf`
`paths.versionLogPath`	`<dataDir>/history.akvlog`
`paths.clusterConfigPath`	`<dataDir>/cluster.akcc`
`paths.nodeIdPath`	`<dataDir>/node.id`

構成要素の有効化

フィールド	デフォルト	意味
`components.walEnabled`	`true`	復旧と永続化のための先行書き込みログを有効化します。
`components.blobEnabled`	`true`	大きな値を Blob ストレージへ逃がせるようにします。
`components.manifestEnabled`	`true`	SST のライフサイクルとチェックポイントを記録します。
`components.sstEnabled`	`true`	永続化されたソート済みテーブルを有効化します。
`components.versionLogEnabled`	`false`	履歴、過去時点読取、ロールバックを有効化します。
`components.clusterEnabled`	`false`	クラスタルーティングとレプリケーション実行時処理を有効化します。
`components.apiEnabled`	`false`	設定済みの API 通信層を起動します。

メモリ上だけの軽いテストでは、WAL、Blob、Manifest、SST を無効化できます。実データを扱う組み込み用途では、明確な理由がない限りデフォルトを維持してください。

akkaradb::engine::AkkEngineOptions opts;
opts.components.walEnabled = false;
opts.components.blobEnabled = false;
opts.components.manifestEnabled = false;
opts.components.sstEnabled = false;

実行時オプション

フィールド	デフォルト	意味
`runtime.writerThreads`	`0`	書き込み並列度用の予約項目です。`0` はエンジン側の既定挙動です。
`runtime.recoverWal`	`true`	起動時に WAL を再生します。
`runtime.recoverSst`	`true`	起動時に SST メタデータとファイルを復旧します。
`runtime.pruneWalOnFlush`	`true`	フラッシュ済みチェックポイント以前の WAL を削除対象にします。
`runtime.forceFlushOnClose`	`true`	`close()` 時に未フラッシュの MemTable をフラッシュします。
`runtime.forceSyncOnClose`	`true`	`close()` 時に永続化対象を物理同期します。
`runtime.sstPromoteReads`	`false`	SST でヒットした値を MemTable 側へ昇格し、繰り返し読取を速くします。

sstPromoteReads は読み取り中心の組み込み用途に向いています。ストレージエンジンの読取経路を厳密に検証したいテストでは、無効のままにすると挙動を追いやすくなります。

MemTable オプション

フィールド	デフォルト	意味
`memtable.shardCount`	`0`	明示的なシャード数です。`0` ではエンジンが選択します。
`memtable.expectedConcurrentWriters`	`0`	自動シャード数を決めるための並行書き込み数ヒントです。
`memtable.autoShardCountCap`	`128`	自動シャード数の上限です。
`memtable.thresholdBytesPerShard`	`64 MiB`	シャードごとの概算フラッシュ閾値です。
`memtable.backendFactory`	`nullptr`	カスタム MemTable 実装を差し込むためのファクトリです。
`memtable.onFlush`	`nullptr`	内部用のフラッシュコールバックです。通常の利用者は設定しません。

書き込みが多い場合は thresholdBytesPerShard を上げるとフラッシュ頻度を下げられます。メモリ制約が強い場合は下げて、stats.memtable.approxBytes を監視します。

WAL オプション

フィールド	デフォルト	意味
`wal.walDir`	自動導出	WAL セグメントのディレクトリです。
`wal.syncMode`	`SYNC`	永続化モードです。`SYNC`、`ASYNC`、`OFF` があります。
`wal.shardCount`	`0`	WAL シャード数です。`0` はハードウェアスレッド数ベースの自動選択です。
`wal.groupN`	`128`	非同期フラッシュでまとめる最大エントリ数です。
`wal.groupMicros`	`100`	非同期フラッシュで待つ最大時間です。
`wal.groupBytes`	`4 MiB`	非同期フラッシュでまとめる最大バイト数です。
`wal.asyncMaxPendingBytes`	`64 MiB`	非同期 WAL の未同期データ上限です。

書き込みごとに fsync 境界を越えたい場合は SYNC を使います。短い耐久性ウィンドウを許容してスループットを上げたい場合は ASYNC を使います。OFF は一時データや制御されたベンチマークに限定してください。

SST オプション

フィールド	デフォルト	意味
`sst.sstDir`	自動導出	SST ファイルのディレクトリです。
`sst.maxLevels`	`7`	LSM の最大レベル数です。
`sst.maxL0Files`	`4`	L0 ファイル数の目安です。増えると圧縮処理の圧力が高まります。
`sst.l1MaxBytes`	`64 MiB`	Level 1 のサイズ予算です。
`sst.levelSizeMultiplier`	`10.0`	レベルごとのサイズ拡大倍率です。
`sst.targetFileSize`	エンジン既定値	生成される SST ファイルの目標サイズです。
`sst.blockSize`	エンジン既定値	SST 内部のブロックサイズです。
`sst.bloomBitsPerKey`	エンジン既定値	Bloom filter の密度です。
`sst.blockCacheBytes`	`64 MiB`	SST ブロックキャッシュの容量です。
`sst.compactThreads`	`2`	バックグラウンド圧縮スレッド数です。
`sst.codec`	`ZSTD`	SST の圧縮形式です。

stats.sst.l0Stalls が増える場合は、圧縮処理が書き込みに追いついていない可能性があります。読取時のキャッシュ効率を上げたい場合は blockCacheBytes を見直します。

Blob オプション

フィールド	デフォルト	意味
`blob.blobDir`	自動導出	Blob ファイルのディレクトリです。
`blob.thresholdBytes`	エンジン既定値	このサイズ以上の値を Blob として保存します。
`blob.codec`	`NONE`	Blob の圧縮形式です。
`blob.gcOnFlush`	`false`	フラッシュ時に Blob GC を走らせます。
`blob.gcOnClose`	`false`	クローズ時に Blob GC を走らせます。

Blob は大きな値を MemTable や SST 本体から分離するための仕組みです。バージョン履歴と組み合わせる場合、古い履歴が Blob を参照していないことを確認するまで GC の扱いは慎重にしてください。

バージョン履歴オプション

フィールド	デフォルト	意味
`vlog.logPath`	自動導出	バージョン履歴ログのパスです。
`vlog.syncMode`	`ASYNC`	履歴ログの同期モードです。`SYNC`、`ASYNC`、`BATCHED_SYNC` があります。
`vlog.groupN`	`128`	まとめてフラッシュする最大エントリ数です。
`vlog.groupMicros`	`500`	まとめてフラッシュする最大待ち時間です。
`vlog.groupBytes`	`1 MiB`	まとめてフラッシュする最大バイト数です。
`vlog.asyncMaxPendingBytes`	`64 MiB`	未同期の履歴ログデータ上限です。
`vlog.writeAdmission`	`SERIAL`	書き込み admission mode です。`SERIAL`、`PREPARE_PARALLEL`、`PARALLEL` があります。
`vlog.parallelWriteLanes`	`0`	parallel writer lane 数です。`0` は `PARALLEL` 利用時に hardware 由来の上限付き値を選びます。
`vlog.recoveryMode`	`EAGER`	recovery mode です。`EAGER` または `BACKGROUND` があります。
`vlog.codec`	`NONE`	VersionLog value codec です。`NONE` または `ZSTD` があります。
`vlog.zstdCompressionLevel`	`1`	`codec = ZSTD` の場合に、新規 VersionLog record に使う Zstd level です。
`vlog.segmentBytes`	`64 MiB`	active segment の rotation size です。`0` で rotation を無効化します。
`vlog.retentionDays`	`0`	closed segment を削除する age boundary です。`0` で age boundary を無効化します。
`vlog.retentionMinCommitSeq`	`0`	closed segment を削除する commit-sequence boundary です。`0` で sequence boundary を無効化します。

history()、getAt()、rollbackKey()、rollbackTo() を使う場合は、エンジンを開く前に components.versionLogEnabled を有効化します。

使い方とロールバックの挙動は VersionLog の使い方に、ファイル形式と recovery の挙動は VersionLog のアーキテクチャに分けています。診断と保守コマンドは VersionLog の運用を参照してください。

Manifest とクラスタ

フィールド	デフォルト	意味
`manifest.fastMode`	`false`	Manifest の永続化処理をバックグラウンドでまとめます。
`cluster.config`	空	永続化されたクラスタ構成です。
`cluster.runtimeBackendPath`	空	動的なランタイムプロバイダのパスです。
`cluster.runtime`	既定値	レプリケーション通信の実行時設定です。

クラスタ設定はローカル組み込み用途とは分けて考えます。ノード ID、メンバーシップ、通信方式、ACK ポリシーが明確になるまでは components.clusterEnabled は無効のままにしてください。

実行時ロール、レプリケーションモード、起動例は、Cluster の使い方に分けています。ルーティング、レプリケーションの流れ、通信形式は、Cluster のアーキテクチャに分けています。

API サーバーオプション

components.apiEnabled を有効にすると、api.backends で指定した通信層が起動します。プロセス内から直接 AkkEngine を呼ぶだけなら、無効のままで問題ありません。

フィールド	意味
`api.backends`	起動するサーバーバックエンドです。HTTP、TCP、gRPC、または複数指定です。
`api.serverBackendPath`	動的なサーバープロバイダのパスです。
`api.transportBackendPath`	動的な通信プロバイダのパスです。
`api.httpBackendPath`	HTTP バックエンド実装のパスです。
`api.tcpBackendPath`	TCP バックエンド実装のパスです。
`api.grpcBackendPath`	gRPC バックエンド実装のパスです。

HTTP 設定:

フィールド	意味
`api.bindHost`	API リスナーが bind するホストアドレスです。
`api.httpPort`	HTTP リスナーのポートです。
`api.httpMaxBatchItems`	1 回の HTTP バッチで受け付ける最大項目数です。
`api.httpMaxScanItems`	1 回の HTTP リクエストで返す最大スキャン行数です。
`api.httpMaxHistoryEntries`	1 回の HTTP リクエストで返す最大履歴件数です。
`api.httpMaxContentLength`	HTTP リクエストボディの最大サイズです。

TCP 設定:

フィールド	意味
`api.tcpPort`	TCP リスナーのポートです。
`api.tcpIoBackend`	TCP I/O バックエンドの選択です。
`api.tcpWorkerThreads`	TCP ワーカースレッド数です。`0` は自動挙動です。
`api.tcpAcceptQueueLimit`	ワーカー待ちの accepted socket 上限です。
`api.tcpListenBacklog`	OS の listen backlog です。
`api.tcpReadTimeoutMs`	読み取りタイムアウトです。
`api.tcpWriteTimeoutMs`	書き込みタイムアウトです。
`api.tcpNoDelay`	Nagle 回避を有効化するかどうかです。
`api.tcpKeepAlive`	TCP keepalive を有効化するかどうかです。

gRPC 設定:

フィールド	意味
`api.grpcPort`	gRPC リスナーのポートです。
`api.grpcWorkerThreads`	gRPC ワーカースレッド数です。
`api.grpcCompletionQueues`	Completion queue の数です。
`api.grpcMinPollers`	最小 poller 数です。
`api.grpcMaxPollers`	最大 poller 数です。
`api.grpcMaxConcurrentStreams`	HTTP/2 stream の同時実行上限です。
`api.grpcResourceQuotaBytes`	gRPC resource quota のバイト数です。

TLS 設定:

フィールド	意味
`api.transportMode`	`TLS` または `PLAIN` です。
`api.tls.certPath`	サーバー証明書のパスです。
`api.tls.keyPath`	サーバー秘密鍵のパスです。
`api.tls.caPath`	peer 検証に使う CA bundle のパスです。
`api.tls.psk`	事前共有鍵のバイト列です。
`api.tls.pskIdentity`	事前共有鍵の identity です。
`api.tls.verifyPeer`	peer 検証を必須にするかどうかです。

API サーバーは、AkkEngine をプロセス境界や組み込みサービスとして公開したい場合に使います。ライブラリとして直接 AkkEngine を呼ぶだけなら無効のままで問題ありません。

起動例と HTTP エンドポイントは、API サーバーの使い方に分けています。TCP フレーミングと通信方式の内部構造は、API サーバーのアーキテクチャに分けています。

推奨プリセット

用途	重要な設定
単体テスト	WAL、Blob、Manifest、SST を無効化します。
永続化ありの組み込み DB	`paths.dataDir` を設定し、WAL、Manifest、SST を有効のままにします。
書き込みスループット重視	`wal.syncMode = ASYNC`、WAL グループ設定、未同期バイト数を調整します。
読み取り中心	`runtime.sstPromoteReads` を有効化し、SST ブロックキャッシュを調整します。
履歴・過去時点読取	`components.versionLogEnabled` を有効化し、`vlog.syncMode` を明示します。
外部公開	`components.apiEnabled` を有効化し、各通信層の上限値と TLS を設定します。