github.com/square/finch@v0.0.0-20240412205204-6530c03e2b96/docs/content/operate/command-line.md (about)

     1  ---
     2  weight: 1
     3  ---
     4  
     5  ```sh
     6  Usage:
     7    finch [options] STAGE_FILE [STAGE_FILE...]
     8  
     9  Options:
    10    --client ADDR[:PORT]  Run as client of server at ADDR
    11    --cpu-profile FILE    Save CPU profile of stage execution to FILE
    12    --database (-D) DB    Default database on connect
    13    --debug               Print debug output to stderr
    14    --dsn DSN             MySQL DSN (overrides stage files)
    15    --help                Print help and exit
    16    --param (-p) KEY=VAL  Set param key=value (override stage files)
    17    --server ADDR[:PORT]  Run as server on ADDR
    18    --test                Validate stages, test connections, and exit
    19    --version             Print version and exit
    20  
    21  finch 1.0.0
    22  ```
    23  
    24  You must specify at least one [stage file]({{< relref "syntax/stage-file" >}}) on the command line.
    25  
    26  Finch executes stages files in the order given.
    27  
    28  ## Command Line Options
    29  
    30  ### `--client`
    31  
    32  Run as [client]({{< relref "operate/client-server" >}}) connected to address and (optional) port.
    33  {.tagline}
    34  
    35  |Env Var|Value|Default|Valid Value|
    36  |-------|-----|-------|-----------|
    37  |`FINCH_CLIENT`|ADDR[:PORT]||Server address[:port]|
    38  {.compact .params}
    39  
    40  <br>
    41  
    42  ### `--cpu-profile`
    43  
    44  Save CPU profile of stage execution.
    45  {.tagline}
    46  
    47  |Env Var|Value|Default|Valid Value|
    48  |-------|-----|-------|-----------|
    49  |`FINCH_CPU_PROFILE`|FILE||file name|
    50  {.compact .params}
    51  
    52  For example, `--cpu-profile cpu.prof` then run `go tool pprof -http 127.1:8080 ./finch cpu.prof`.
    53  
    54  <br>
    55  
    56  ### `--database`
    57  
    58  |Env Var|Value|Default|Valid Value|
    59  |-------|-----|-------|-----------|
    60  |`FINCH_DB`|DB||Database name|
    61  {.compact .params}
    62  
    63  Sets [default database]({{< relref "operate/mysql#default-database" >}}) on connect.
    64  Does not override [`--dsn`](#--dsn`).
    65  
    66  <br>
    67  
    68  ### `--debug`
    69  
    70  Print debug output to stderr.
    71  {.tagline}
    72  
    73  |Env Var|
    74  |-------|
    75  |`FINCH_DEBUG`|
    76  {.compact .params}
    77  
    78  Use with `--test` to debug startup validation, data generators, etc.
    79  
    80  <br>
    81  
    82  ### `--dsn`
    83  
    84  Data source name (DSN) for all MySQL connections.
    85  {.tagline}
    86  
    87  |Env Var|Value|Default|Valid Value|
    88  |-------|-----|-------|-----------|
    89  |`FINCH_DSN`|DSN||[Data Source Name](https://github.com/go-sql-driver/mysql#dsn-data-source-name)|
    90  {.compact .params}
    91  
    92  This overrides any [`mysql`]({{< relref "syntax/all-file#mysql" >}}) settings.
    93  
    94  There's no default DSN, but there is a default [MySQL user]({{< relref "operate/mysql#user" >}}).
    95  
    96  <br>
    97  
    98  ### `--help`
    99  
   100  Print help (the usage output above) and exit zero.
   101  {.tagline}
   102  
   103  <br>
   104  
   105  ### `--param`
   106  
   107  Set [params]({{< relref "syntax/all-file#params" >}}) that override all stage files.
   108  {.tagline}
   109  
   110  This option can be specified multiple times:
   111  
   112  ```sh
   113  finch --params key1=value1 --params key2=val2
   114  ```
   115  
   116  <br>
   117  
   118  ### `--server`
   119  
   120  Run as [server]({{< relref "operate/client-server" >}}) on addr:port to listen on for clients.
   121  {.tagline}
   122  
   123  |Env Var|Value|Default|Valid Value|
   124  |-------|-----|-------|-----------|
   125  |`FINCH_SERVER`|ADDR[:PORT]||Interface address and port|
   126  {.compact .params}
   127  
   128  Using value "0" or "0.0.0.0" will bind to all interfaces on port 33075.
   129  
   130  <br>
   131  
   132  ### `--test`
   133  
   134  Start up and validate everything possible, but don't execute any stages.
   135  {.tagline}
   136  
   137  |Env Var|
   138  |-------|
   139  |`FINCH_TEST`|
   140  {.compact .params}
   141  
   142  Use with [`--debug`](#--debug) to debug file syntax, workload allocation, and so forth.
   143  Finch start up is two-phase: prepare and run.
   144  This option makes Finch exit after prepare.
   145  Finch prepares everything in the prepare phase, so a successful test means that the Finch configuration is valid.
   146  The only thing Finch does not check during prepare is that the SQL statements are valid.
   147  That happens in the run phase when Finch executes the SQL statements.
   148  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.
   149  However, statements with the [prepare SQL modifier]({{< relref "syntax/trx-file#prepare" >}}) are prepared on MySQL during the Finch prepare phase, so invalid prepared SQL statements will cause an error during a Finch startup test.
   150  
   151  <br>
   152  
   153  ### `--version`
   154  
   155  Print Finch version and exit zero.
   156  {.tagline}