greptimedb/tests-fuzz

Fuzz Test for GreptimeDB

Setup

1. Install the fuzz cli first.

cargo install cargo-fuzz

Note: cargo-fuzz instruments targets with -Zsanitizer=fuzzer, so fuzz targets must be built with a nightly toolchain (the workspace default toolchain does not need to be nightly — make fuzz / make fuzz-ls invoke cargo +nightly for you; CI pins its own nightly in FUZZ_RUST_TOOLCHAIN).

2. Start GreptimeDB
3. 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

1. List all fuzz targets

cargo fuzz list --fuzz-dir tests-fuzz

2. Run a fuzz target.

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.

echo "Base64" > .crash

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

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:

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.