Common workflows¶

Step-by-step guides for common operational tasks with HyperbyteDB.

Migrating from InfluxDB 1.x¶

HyperbyteDB is designed as a drop-in replacement for InfluxDB 1.x. Most clients, libraries, Telegraf, and Grafana work without modification.

Using the backfill tool¶

HyperbyteDB ships a hyperbytedb-backfill binary for migrating data from InfluxDB 1.x:

cargo build --release --bin hyperbytedb-backfill

# Migrate from a running InfluxDB instance
./target/release/hyperbytedb-backfill \
  --influx-url http://old-influx:8086 \
  --hyperbytedb-url http://new-hyperbytedb:8086 \
  --database mydb \
  --start "2024-01-01T00:00:00Z" \
  --end "2024-12-31T23:59:59Z"

The backfill tool: 1. Queries InfluxDB in time-chunked SELECT statements. 2. Converts results to line protocol. 3. POSTs them to HyperbyteDB via /write. 4. Supports --batch-size, --chunk-interval, and optional --dump-dir for saving raw line protocol to disk.

Replay from line protocol files¶

If you have exported line protocol files:

./target/release/hyperbytedb-backfill \
  --from-dir /path/to/line-protocol-files \
  --hyperbytedb-url http://localhost:8086 \
  --database mydb

What works identically¶

• Line protocol write format and semantics
• /write and /query endpoint behavior
• /ping response for client library connection tests
• JSON response shapes ({"results":[...]})
• epoch parameter for timestamp formatting
• Authentication (query params, Basic, Token; internal APIs need admin)
• Gzip write support
• Chunked query responses

Known differences¶

Integrating Telegraf¶

Telegraf works with HyperbyteDB out of the box using its InfluxDB v1 output plugin.

telegraf.conf¶

[[outputs.influxdb]]
  urls = ["http://hyperbytedb:8086"]
  database = "telegraf"
  skip_database_creation = false
  timeout = "5s"

[[inputs.cpu]]
  percpu = true
  totalcpu = true

[[inputs.mem]]

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]

[[inputs.net]]

[[inputs.system]]

Point Telegraf at HyperbyteDB just as you would at InfluxDB. The skip_database_creation = false setting tells Telegraf to create the database if it doesn't exist.

Integrating Grafana¶

HyperbyteDB works as an InfluxDB v1 datasource in Grafana.

Add datasource¶

1. Open Grafana → Configuration → Data Sources → Add data source.
2. Select InfluxDB.
3. Set the URL to http://hyperbytedb:8086.
4. Set the database name (e.g., telegraf).
5. If auth is enabled, enter credentials in the InfluxDB Details section.
6. Click Save & Test.

Docker Compose (pre-configured)¶

The included docker-compose.yml ships Grafana with pre-provisioned datasources: - An InfluxDB datasource pointing to HyperbyteDB - A Prometheus datasource for internal metrics

Grafana is accessible at http://localhost:3000 with login admin/admin.

Setting Up Monitoring¶

Prometheus scrape config¶

Add HyperbyteDB as a Prometheus target:

scrape_configs:
  - job_name: 'hyperbytedb'
    static_configs:
      - targets: ['hyperbytedb:8086']
    metrics_path: /metrics
    scrape_interval: 15s

Key metrics to watch¶

Alert recommendations¶

Backup and Restore¶

Create a backup¶

hyperbytedb backup --output /backups/hyperbytedb-$(date +%Y%m%d)

The backup contains: - wal/ — RocksDB checkpoint of the WAL - meta/ — RocksDB checkpoint of metadata - data/ — Copy of all Parquet data files - manifest.json — Timestamp, WAL sequence, and file list

Backups can be taken while HyperbyteDB is running. RocksDB checkpoints provide a consistent snapshot without stopping writes.

Restore from backup¶

# 1. Stop HyperbyteDB
# 2. Restore (overwrites data_dir, wal_dir, meta_dir)
hyperbytedb restore --input /backups/hyperbytedb-20240115
# 3. Start HyperbyteDB
hyperbytedb serve

Warning: Restore overwrites the configured data_dir, wal_dir, and meta_dir. Ensure the config file points to the correct directories.

Downsampling with Continuous Queries¶

A typical pattern for long-term data retention:

1. Raw data — kept for 7 days in the default retention policy.
2. 5-minute rollups — kept for 90 days.
3. 1-hour rollups — kept indefinitely.

-- Create retention policies
CREATE RETENTION POLICY "7d" ON "mydb" DURATION 7d REPLICATION 1 DEFAULT
CREATE RETENTION POLICY "90d" ON "mydb" DURATION 90d REPLICATION 1
CREATE RETENTION POLICY "forever" ON "mydb" DURATION INF REPLICATION 1

-- Create downsampling CQs
CREATE CONTINUOUS QUERY "cq_5m" ON "mydb"
BEGIN
  SELECT mean("usage_idle") AS "usage_idle", mean("usage_user") AS "usage_user"
  INTO "mydb"."90d"."cpu_5m"
  FROM "cpu"
  GROUP BY time(5m), *
END

CREATE CONTINUOUS QUERY "cq_1h" ON "mydb"
BEGIN
  SELECT mean("usage_idle") AS "usage_idle", mean("usage_user") AS "usage_user"
  INTO "mydb"."forever"."cpu_1h"
  FROM "cpu"
  GROUP BY time(1h), *
END

See Also¶

• Administration — Backup procedures, cluster operations, compaction tuning
• Troubleshooting — Common problems and fixes
• API & InfluxQL Reference — Full syntax reference