Finch Docs
Toggle Dark/Light/Auto modeToggle Dark/Light/Auto modeToggle Dark/Light/Auto modeBack to homepage
  2. /
  3. Operate
  4. /
  5. Command Line

Command Line

Usage:
  finch [options] STAGE_FILE [STAGE_FILE...]

Options:
  --client ADDR[:PORT]  Run as client of server at ADDR
  --cpu-profile FILE    Save CPU profile of stage execution to FILE
  --database (-D) DB    Default database on connect
  --debug               Print debug output to stderr
  --dsn DSN             MySQL DSN (overrides stage files)
  --help                Print help and exit
  --param (-p) KEY=VAL  Set param key=value (override stage files)
  --server ADDR[:PORT]  Run as server on ADDR
  --test                Validate stages, test connections, and exit
  --version             Print version and exit

finch 1.0.0

You must specify at least one stage file on the command line.

Finch executes stages files in the order given.

Command Line Options

--client

Run as client connected to address and (optional) port.

Env VarValueDefaultValid Value
FINCH_CLIENTADDR[:PORT]Server address[:port]

--cpu-profile

Save CPU profile of stage execution.

Env VarValueDefaultValid Value
FINCH_CPU_PROFILEFILEfile name

For example, --cpu-profile cpu.prof then run go tool pprof -http 127.1:8080 ./finch cpu.prof.


--database

Env VarValueDefaultValid Value
FINCH_DBDBDatabase name

Sets default database on connect. Does not override --dsn.


--debug

Print debug output to stderr.

Env Var
FINCH_DEBUG

Use with --test to debug startup validation, data generators, etc.


--dsn

Data source name (DSN) for all MySQL connections.

Env VarValueDefaultValid Value
FINCH_DSNDSNData Source Name

This overrides any mysql settings.

There’s no default DSN, but there is a default MySQL user.


--help

Print help (the usage output above) and exit zero.


--param

Set params that override all stage files.

This option can be specified multiple times:

finch --params key1=value1 --params key2=val2

--server

Run as server on addr:port to listen on for clients.

Env VarValueDefaultValid Value
FINCH_SERVERADDR[:PORT]Interface address and port

Using value “0” or “0.0.0.0” will bind to all interfaces on port 33075.


--test

Start up and validate everything possible, but don’t execute any stages.

Env Var
FINCH_TEST

Use with --debug to debug file syntax, workload allocation, and so forth. Finch start up is two-phase: prepare and run. This option makes Finch exit after prepare. Finch prepares everything in the prepare phase, so a successful test means that the Finch configuration is valid. The only thing Finch does not check during prepare is that the SQL statements are valid. That happens in the run phase when Finch executes the SQL statements. For example, Finch doesn’t check if “SELECT c FRM t WHRE id=1” is valid; it relies on MySQL to parse and validate SQL statements. However, statements with the prepare SQL modifier are prepared on MySQL during the Finch prepare phase, so invalid prepared SQL statements will cause an error during a Finch startup test.


--version

Print Finch version and exit zero.