データベース管理

概要

このページでは、インストール済みのPlantPulse Platformが使用するデータストレージの構成、接続方法、状態確認、基本的なチューニングポリシーについて説明します。

Platformは用途別に4種類のデータストレージを内蔵して運用しています。

ストレージ	用途	デフォルトポート	備考
Cassandra	時系列 / 大容量データ（タグポイント、イベント）	9042 (CQL)	キースペース `pp`。Platformの単一大容量DBエンジン
PostgreSQL	メタストア（マスター/設定データ）	5432	データベース `pp`、スキーマ `pp`
Valkey (Redis互換)	キャッシュ/セッション/リアルタイム状態	6379	redis-cli で接続可能
MinIO	オブジェクトストレージ（S3互換）	9000 (S3) / 9001 (コンソール)	ファイル/大容量成果物の保存

このほか、分析層（Spark / Kyuubi）が使用するHive Metastore + Iceberg テーブル形式がありますが、これはPlatformが内部的に管理するため、別途の運用作業は不要です。

参考: Cassandra の7000（クラスタゴシップ）、7199（JMX）ポートは内部通信専用です。外部に公開しないでください。

接続方法

以下のコマンドはすべてデータレイクコンテナ内部を基準としています。4つのストレージはすべてplantpulse-datalakeの同一コンテナ内で動作するため、引数なしでシェルを開くとそのコンテナに直接入ります。

cd /opt/kopens/plantpulse-platform-docker/bin
./shell.sh

接続アカウントとパスワードは環境変数（PP_CASSANDRA_USER/PASSWORD、PP_PG_USER/PASSWORD、PP_REDIS_PASSWORD など）で管理されます。

項目	場所
実際に適用された値	ホストのシークレットサイドカー `/etc/kopens/plantpulse-platform.env`（権限 `0600`）
値を変更する方法	`bin/passwd.sh` — ファイルを直接編集しても反映されません → パスワード回転

パス確認 — シークレットサイドカーのオリジナルは/etc/kopens/plantpulse-platform.env 1つです（権限 0600）。古いインストールでは/opt/kopens/配下に同じ名前が残っている場合もありますが、読み込まれず、インストールスクリプトがオリジナルに戻します → 環境変数リファレンス

Cassandra (cqlsh)

cd /opt/kopens/plantpulse-platform/plantpulse-storage/db/cassandra/bin
./cqlsh -u <PP_CASSANDRA_USER> 127.0.0.1 9042

-- 키스페이스 / 테이블 확인
DESCRIBE KEYSPACE pp;
SELECT table_name FROM system_schema.tables WHERE keyspace_name = 'pp';

PostgreSQL (psql)

PostgreSQL 18が使用されており、クライアントバイナリは/usr/pgsql-18/binにあります。

/usr/pgsql-18/bin/psql -h 127.0.0.1 -U <PP_PG_USER> -d pp

-- 메타스토어 스키마 확인 (기본 search_path 는 pp 스키마)
\dn
\dt pp.*

Valkey (redis-cli)

redis-cli -h 127.0.0.1 -p 6379 -a '<PP_REDIS_PASSWORD>' ping

注意: 照会（SELECT / DESCRIBE / ping）用途のみでご使用ください。データ修正やスキーマ変更は注意事項をご参照ください。

状態確認

Cassandraノード状態

pd node動詞がnooletoolをラップして提供します。

cd /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin
./pd node status

正常な状態では、ノードがUN（Up / Normal）と表示されます。DN（Down）ノードが表示される場合は、ストレージの再起動またはログの確認が必要です。

PostgreSQL状態

/usr/pgsql-18/bin/pg_isready -h 127.0.0.1 -p 5432
/usr/pgsql-18/bin/psql -h 127.0.0.1 -U <PP_PG_USER> -d pp -c "SELECT version();"

統合状態ダッシュボード / ヘルスAPI

# 포트별 서비스 상태 + CPU / 메모리 / 디스크 요약
cd /opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin
./status.sh

# 헬스 API — cassandra / postgres 컴포넌트 상태 포함
curl -kfsS https://127.0.0.1:4950/api/health | jq

ヘルスAPI応答のcassandra、postgresコンポーネントが正常（UP）であることを確認してください。

スキーマ/データ配置

項目	場所	内容
Cassandraキースペース	`pp`	時系列データテーブル（`tm_*`）
PostgreSQLスキーマ	データベース `pp` / スキーマ `pp`	マスター/設定テーブル（`mm_*`）
データファイルパス	`/data1/pp-data`	Dockerボリューム `pp-data` にマウント

PostgreSQLメタストアスキーマはイメージビルド時点で事前シード済みのため、インストール後の別途スキーマ生成作業は不要です。接続時にsearch_pathがppスキーマに設定されているため、テーブル名のみで照会できます。

データはすべて/data1/pp-data（ボリューム pp-data）配下に保存されるため、コンテナを削除したりイメージを更新してもデータは保存されます。

チューニング基本値（出荷時設定）

Cassandraはプラットフォームのワークロードに合わせて以下の基本値で出荷されます。

項目	出荷時基本値	説明
JVMヒープ	`-Xms16G -Xmx16G`	初期/最大ヒープ同一（動的リサイジング防止）
GC	ZGC (Generational)	低遅延ガベージコレクター
ファイルキャッシュ	`file_cache_enabled: false`	OS ページキャッシュ活用、オフヒープ上限削除
Direct メモリ	`-XX:MaxDirectMemorySize=6G`	memtableオフヒープ + IOバッファ用途

重要 — 設定変更パス: 各サービスパスにデプロイされた設定ファイル（例：Cassandraのcassandra.yaml、jvm-server.options）はplantpulse-datalake-cli/config/templates/のテンプレートからレンダリングされた成果物です。このファイルを直接編集すると、次回の再起動/再設定（configure）時にテンプレート値で上書きされ、変更が失われます。

チューニング値を変更する場合は、必ず以下のパスで進めてください。

ホストの/etc/kopens/confにあるテンプレート（コンテナのplantpulse-datalake-cli/config/templatesにバインドマウントされます）またはbin/env.shのPP_*変数を修正

データレイクコンテナ内で./configure.shを実行 — テンプレートを再レンダリングして各サービスパスにデプロイ

該当サービスを再起動（例：pd restart storage）

テンプレートはホストディレクトリのため、オペレータはホストから直接編集でき、再インストール後も編集内容が保存されます。

基本値の変更が必要な場合は、まず技術サポートチームと相談されることをお勧めします。

バックアップ概要

データベースを含むすべてのデータはpp-dataボリュームに保存されるため、ボリューム単位のバックアップが最も簡単で安全な方法です。

cd /opt/kopens/plantpulse-platform-docker/bin

# 기본 세트 (pp-data · pp-security) 를 한 번에
./backup.sh

# 볼륨 하나만 — <volume-name> [보관일수] [백업경로]
./tools/backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume

backup.shの基本セットでは、pp-backupはバックアップの宛先であるため、pp-tempは復旧に役に立たないため含まれていません。必要な場合は引数で指定してバックアップできます。

ポイントインタイムリカバリ、DB別個別バックアップ、外部ストレージ同期など詳細な手順は管理者ガイド - バックアップ及び復旧ページをご参照ください。

注意事項

運用DBへのDDL直接実行禁止 — テーブルの作成/変更/削除（CREATE / ALTER / DROP / TRUNCATE）を直接実行しないでください。スキーマはPlatformがバージョン別マイグレーションで管理しており、任意の変更は更新失敗またはデータ喪失を招く可能性があります。
データの直接編集を避けてください — マスターデータ（mm_*）は管理コンソール画面から変更してください。DB直接UPDATE はキャッシュ/連携サービスとの不一致を引き起こします。
エンベッド/代替DBの使用禁止 — 内蔵CassandraおよびPostgreSQLを他のDB製品またはエンベッドDBに置き換える構成はサポートされていません。
データファイルの直接削除禁止 — ディスク空容量確保のため/data1/pp-data配下のファイルを直接削除しないでください。データクリーニングが必要な場合は技術サポートチームにお問い合わせください。
アカウント/ポート変更は環境変数で — DBアカウントやポートを変更する必要がある場合は、設定ファイルの直接編集ではなく、環境変数（PP_*）オーバーライド方式で進めてください。

技術サポート

データベース運用に関するご質問があればいつでもお問い合わせください。

部門	連絡先
技術サポート	webmaster@kopens.com

概要​

接続方法​

Cassandra (cqlsh)​

PostgreSQL (psql)​

Valkey (redis-cli)​

状態確認​

Cassandraノード状態​

PostgreSQL状態​

統合状態ダッシュボード / ヘルスAPI​

スキーマ/データ配置​

チューニング基本値（出荷時設定）​

バックアップ概要​

注意事項​

技術サポート​

概要