Database Management

Overview

This page explains the configuration, connection methods, status checks, and default tuning policy for the data stores used by an installed PlantPulse Platform.

The Platform operates 4 types of built-in data stores according to purpose.

Store	Purpose	Default Port	Notes
Cassandra	Time series / large-volume data (tag points, events)	9042 (CQL)	Keyspace pp. The Platform's single large-volume DB engine
PostgreSQL	Metastore (master / configuration data)	5432	Database pp, schema pp
Valkey (Redis-compatible)	Cache / session / real-time state	6379	Can be accessed via redis-cli
MinIO	Object storage (S3-compatible)	9000 (S3) / 9001 (console)	Storage for files / large output artifacts

There is also a Hive Metastore + Iceberg table format used by the analytics layer (Spark / Kyuubi), which is managed internally by the Platform and requires no separate operational work.

Note: Cassandra's ports 7000 (cluster gossip) and 7199 (JMX) are for internal communication only. Do not expose them externally.

Connection Methods

All commands below assume you are inside the data lake container. Since all four data stores run inside the single plantpulse-datalake container, opening a shell without arguments takes you directly into that container.

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

Access accounts and passwords are managed via environment variables (PP_CASSANDRA_USER/PASSWORD, PP_PG_USER/PASSWORD, PP_REDIS_PASSWORD, etc.).

Item	Location
Actually applied values	Host's secret sidecar /etc/kopens/plantpulse-platform.env (permissions 0600)
How to change values	bin/passwd.sh — editing the file directly will not take effect → Password Rotation

Path note — The authoritative source for the secret sidecar is only /etc/kopens/plantpulse-platform.env (permissions 0600). Older installations may still have a file of the same name under /opt/kopens/, but it is not read, and the install script restores the authoritative copy → Environment Variable Reference

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 is used, and the client binaries are located at /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

Caution: Please use this only for lookups (SELECT / DESCRIBE / ping). For data modification or schema changes, refer to Precautions.

Status Checks

Cassandra Node Status

The pd node verb wraps nodetool.

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

Under normal conditions, nodes are shown as UN (Up / Normal). If a node shows DN (Down), a storage restart or log check is needed.

PostgreSQL Status

/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();"

Integrated Status Dashboard / Health 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

Please check whether the cassandra and postgres components in the health API response are normal (UP).

Schema / Data Layout

Item	Location	Contents
Cassandra keyspace	pp	Time series data tables (tm_*)
PostgreSQL schema	Database pp / schema pp	Master / configuration tables (mm_*)
Data file path	/data1/pp-data	Mounted as Docker volume pp-data

The PostgreSQL metastore schema is pre-seeded at image build time, so no separate schema creation work is needed after installation. On connection, search_path is set to the pp schema, so you can query using table names alone.

All data is stored under /data1/pp-data (volume pp-data), so data is preserved even if the container is removed or the image is updated.

Default Tuning Values (Factory Settings)

Cassandra ships with the following default values tuned for the Platform's workload.

Item	Factory Default	Description
JVM Heap	-Xms16G -Xmx16G	Initial / max heap are equal (prevents dynamic resizing)
GC	ZGC (Generational)	Low-latency garbage collector
File cache	file_cache_enabled: false	Uses OS page cache, off-heap cap removed
Direct memory	-XX:MaxDirectMemorySize=6G	For memtable off-heap + IO buffer purposes

Important — Configuration Change Path: The configuration files deployed at each service path (e.g., cassandra.yaml, jvm-server.options for Cassandra) are rendered outputs from templates at plantpulse-datalake-cli/config/templates/. Editing these files directly will be overwritten by the template values on the next restart / reconfigure, and changes will be lost.

If you need to change tuning values, please follow the path below.

1. Edit the template at /etc/kopens/conf on the host (bind-mounted to plantpulse-datalake-cli/config/templates in the container), or edit the PP_* variable in bin/env.sh
2. Run ./configure.sh inside the data lake container — this re-renders templates and deploys them to each service path
3. Restart the relevant service (e.g., pd restart storage)

Because the templates are a host directory, operators can edit them directly on the host, and edits are preserved even after reinstallation.

If a change to the default values is needed, we recommend consulting the technical support team first.

Backup Overview

Since all data, including databases, is stored in the pp-data volume, volume-level backup is the simplest and safest method.

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

In the default set for backup.sh, pp-backup is excluded because it is the backup destination, and pp-temp is excluded because it is useless for recovery. If needed, they can be backed up by specifying them as arguments.

For detailed procedures such as point-in-time recovery, per-DB individual backup, and external storage sync, please refer to Admin Guide - Backup and Recovery.

Precautions

• Do not run DDL directly on the production DB — Do not directly execute table creation / modification / deletion (CREATE / ALTER / DROP / TRUNCATE). The schema is managed by the Platform through versioned migrations, and arbitrary changes may cause update failures or data loss.
• Avoid direct data modification — Please change master data (mm_*) through the admin console screens. Direct UPDATE on the DB may cause inconsistency with cache / integrated services.
• Do not use embedded / alternative DBs — Configurations that replace the built-in Cassandra / PostgreSQL with other DB products or embedded DBs are not supported.
• Do not delete data files directly — Do not directly delete files under /data1/pp-data to free up disk space. If data cleanup is needed, please contact the technical support team.
• Change accounts / ports via environment variables — If you need to change DB accounts or ports, please do so via environment variable (PP_*) overrides rather than editing configuration files directly.

Technical Support

If you have any questions regarding database operations, please feel free to contact us at any time.

Contact	Details
Technical Support	webmaster@kopens.com