Finch Docs
Toggle Dark/Light/Auto modeToggle Dark/Light/Auto modeToggle Dark/Light/Auto modeBack to homepage



Specify --client ADDR to run Finch as a client connected to the server at ADDR.

A client ignores other command line options and automatically receives stage and trx files from the server.

The client runs only once. This is largely due to MySQL doesn’t properly terminate clients/connections in some cases, especially when the client aborts the connection, which is what the Go MySQL driver does on context cancellation.


Specify --server ADDR to run Finch as a server that listens on ADDR[:PORT} for remote compute instances.

The recommended client-server startup sequence is server then clients: start the server, then start the clients.

The server is counted as one compute instance called “local”. Set stage.compute.disable-local to disable.

A standalone instance of Finch is a pseduo-server that doesn’t bind to an interface and runs only locally. As a result, --debug prints server info even when --server is not specififed.


The client-server protocol is initiated by clients over a standard HTTP port. The server needs to allow incoming HTTP on that port (default 33075).


    activate client
    client->>server: GET /boot
    server-->>client: return stage files

    loop Every trx file
        client->>server: GET /file?trx=N
        server-->>client: return trx file N
    client->>server: POST /boot
    server-->>client: ack
    client->>server: GET /run
    deactivate client
    Note over client: Client waits for server
    Note over server: Server waits for stage.compute.instances

    server-->>client: ack
    activate client
    Note left of client: Client runs stages
    loop While running
        client->>server: POST /stats
        server-->>client: ack
    deactivate client
    Note left of client: Client done running
    client->>server: POST /run
    server-->>client: ack