Skip to content

ToplingDB Quick Start

In ToplingDB 501 words 3 min

Historical integration. This 2025 article describes an earlier interface and is retained for reference. For the proposed replacement, see the ToplingDB development guide. That guide describes unreleased changes; do not mix its settings with these historical examples.

ToplingDB is a configurable and observable extension of RocksDB. It supports dynamic tuning via YAML files and enables real-time monitoring through a built-in Web Server.

Update hugegraph.properties

1backend=rocksdb
2serializer=binary
3rocksdb.data_path=.
4rocksdb.wal_path=.
5# Path to YAML configuration file
6#  For security reasons, HG only allows YAML files to be located under the `conf/graphs` directory
7rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
8# Enable Web Server
9rocksdb.open_http=true

Initialize the database (required on the first startup, or a new configuration was manually added under ‘conf/graphs/’)

1cd *hugegraph-${version}
2bin/init-store.sh

Start server

1bin/start-hugegraph.sh
2Starting HugeGraphServer...
3Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK

Verify ToplingDB Is Working Properly

Prerequisite: Ensure Core Parameters Are Correctly Configured

Check that hugegraph.properties includes:

1# Configuration file path
2rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
3# Enable Web Server
4rocksdb.open_http=true

Method 1: Access the Web Monitoring Interface

Visualize the Web monitoring page. Example screenshot:

image

Verify via terminal:

1# Access http://localhost:2011 (port depends on listening_ports in YAML config)
2curl http://localhost:2011 | grep topling

The following output indicates the page is working:

1<p><a href="https://topling.cn">Topling Inc.</a>This is <strong>Engine Inspector</strong>, for metrics, see <a href='javascript:grafana()'>Grafana</a>!</p>

Method 2: Check ToplingDB Initialization Info in Logs

1tail -f logs/hugegraph-server.log | grep -i topling

Similar output indicates ToplingDB is the storage engine:

12025-10-14 08:56:25 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
22025-10-14 08:56:25 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - Topling HTTP Server has been started according to the listening_ports specified in ./conf/graphs/rocksdb_plus.yaml

Common Troubleshooting

Issue 1: Startup Failure Due to YAML Format Error

Sample log during startup:

12025-10-15 01:55:50 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
221:1: (891B):ERROR: 
3sideplugin/rockside/3rdparty/rapidyaml/src/c4/yml/parse.cpp:3310: ERROR parsing yml: parse error: incorrect indentation?

Solutions:

  1. Check YAML indentation (must use spaces, not tabs)
  2. Validate YAML syntax: python -c "import yaml; yaml.safe_load(open('conf/graphs/rocksdb_plus.yaml'))"
  3. Review specific error messages in logs

Issue 2: Web Server Port Conflict

Sample log during startup:

12025-10-15 01:57:34 [db-open-1] [INFO] o.a.h.b.s.r.RocksDBStdSessions - SidePluginRepo found. Will attempt to open multi CFs RocksDB using Topling plugin.
22025-10-15 01:57:34 [db-open-1] [ERROR] o.a.h.b.s.r.RocksDBStore - Failed to open RocksDB 'rocksdb-data/data/g'
3org.rocksdb.RocksDBException: rocksdb::Status rocksdb::SidePluginRepo::StartHttpServer(): null context when constructing CivetServer. Possible problem binding to port.
4    at org.rocksdb.SidePluginRepo.startHttpServer(Native Method) ~[rocksdbjni-8.10.2-20250804.074027-4.jar:?]

Solutions:

  1. Check if the port is occupied: lsof -i :2011
  2. Modify listening_ports in the YAML file
  3. Restart HugeGraph Server

Issue 3: Database Initialization Failure

Sample output indicating lock acquisition failure, possibly due to write permission issues or another process locking the DB:

1Caused by: org.rocksdb.RocksDBException: While lock file: rocksdb-data/data/m/LOCK: Resource temporarily unavailable
2        at org.rocksdb.SidePluginRepo.nativeOpenDBMultiCF(Native Method)
3        at org.rocksdb.SidePluginRepo.openDB(SidePluginRepo.java:22)

Solutions:

  1. Confirm correct config path: rocksdb.option_path=./conf/graphs/rocksdb_plus.yaml
  2. Check data directory permissions: ensure read/write access for the running user
  3. Review detailed logs: bin/init-store.sh 2>&1 | tee init.log
Last modified 2026-10-15 · docs: explain ToplingDB runtime setup (#510) (10a591a21)