Fuzz Test for GreptimeDB

Setup

Install the fuzz cli first.

bash

cargo install cargo-fuzz

Start GreptimeDB
Copy the .env.example, which is at project root, to .env and change the values on need.

For stable fuzz tests

Set the GreptimeDB MySQL address.

GT_MYSQL_ADDR = localhost:4002

For unstable fuzz tests

Set the binary path of the GreptimeDB:

GT_FUZZ_BINARY_PATH = /path/to/

Change the instance root directory(the default value: /tmp/unstable_greptime/)

GT_FUZZ_INSTANCE_ROOT_DIR = /path/to/

Run

List all fuzz targets

bash

cargo fuzz list --fuzz-dir tests-fuzz

Run a fuzz target.

bash

cargo fuzz run fuzz_create_table --fuzz-dir tests-fuzz -D -s none

Crash Reproduction

If you want to reproduce a crash, you first need to obtain the Base64 encoded code, which usually appears at the end of a crash report, and store it in a file.

Alternatively, if you already have the crash file, you can skip this step.

bash

echo "Base64" > .crash

Print the std::fmt::Debug output for an input.

bash

cargo fuzz fmt fuzz_target .crash --fuzz-dir tests-fuzz -D -s none

Rerun the fuzz test with the input. You can override fuzz input with environment variables. For example, to override fuzz input like:

FuzzInput {
    seed: 6666,
    actions: 175
}

you can run with GT_FUZZ_OVERRIDE_SEED=6666 and GT_FUZZ_OVERRIDE_ACTIONS=175:

bash

GT_FUZZ_OVERRIDE_SEED=6666 GT_FUZZ_OVERRIDE_ACTIONS=175 cargo fuzz run fuzz_target .crash --fuzz-dir tests-fuzz -D -s none

For more details, visit cargo fuzz or run the command cargo fuzz --help.

Repartition Metric Dump Artifacts

For fuzz_repartition_metric_table, dump artifacts are written under one run directory.

Table data snapshots: <logical_table>.table-data.csv
SQL traces per logical table: <logical_table>.trace.sql
Seed metadata: seed.meta

SQL trace behavior:

Insert SQL is appended after successful execution with comment fields including started_at_ms and elapsed_ms.
Repartition events are broadcast to all logical table trace files with comment fields including action_idx, started_at_ms, elapsed_ms, and SQL text.

Run directory lifecycle:

On success, the run directory is cleaned up.
On failure, the run directory is retained for CI/local diffing.