Skip to content

StarRocks connector

StarRocks is reached through its FE's MySQL-protocol port with the same adapter as MySQL — text protocol, pooled connections, the shared ResultSet normalizer — and compiled SQL is generated for the StarRocks dialect, which keeps FULL OUTER JOIN (unlike MySQL and TiDB).

StarRocks also has a second, faster path: add one key and queries run over Arrow Flight SQL, where the FE plans and the client pulls Arrow batches directly from the BEs — columnar end to end, with no row serialization through the FE.

Gated by exec-mysql, plus exec-flightsql for the Arrow path.

Connection profile

datasources:
  prod-sr:
    type: starrocks
    host: sr.internal
    port: 9030               # FE MySQL-protocol port
    username: dosi
    password: ${SR_PASSWORD}
    database: analytics

With Arrow Flight SQL:

    arrow_flight_port: 9408  # FE arrow_flight_port; presence opts queries into Flight SQL

Parameters

Key Type Required Default Notes
type string yes — starrocks
host string yes* — *Unless uri: is given. Also the Flight SQL host.
port int no 3306 (driver default) The FE MySQL port — normally 9030; set it explicitly.
username string no — Also the Flight SQL handshake user, where it defaults to root.
password string no — Prefer ${VAR}.
database string no — On the Flight path it is applied as USE <database> after the handshake.
arrow_flight_port int no — Presence switches the executor. The FE's arrow_flight_port (StarRocks ≥ 3.5.1). Remove the key to fall back to the MySQL wire.
uri string no — A mysql:// DSN. Note it replaces host/port/username/password/database — the discrete keys are ignored when uri: is set.
default bool no false See connection profiles.

Parsed and ignored on this connector: sslmode, sslrootcert (neither the MySQL nor the Flight path has TLS here), schema, catalog, account, role, warehouse, compat_mode.

Arrow-native results

Adding arrow_flight_port: is the whole configuration change — see Arrow for what it buys. Three operational rules come with it:

  • The client must be able to reach the BEs directly. With the FE result proxy off, the FE hands out each BE's own address for the data pull. In Docker, publish the BE Flight port 1:1 (9419:9419).
  • Turn the FE result proxy off on 4.0.14: SET GLOBAL arrow_flight_proxy_enabled = false. That release defaults it to true, and its proxied reads fail with Failed to proxy result from BE: Failed to read message — with any client, not only Dosi's.
  • Seed and manage schemas over the MySQL wire. Database-level DDL (CREATE/DROP DATABASE) is rejected on the Flight endpoint in StarRocks 4.0; table-level DDL and DML reach the analyzer. Keeping port: in the profile gives you that fallback path.
  • The FE's Flight service can reset the very first connection after startup; the adapter retries the connect once.

Without exec-flightsql in the build, the key is an error rather than a silent downgrade: datasource "x" sets arrow_flight_port but this build lacks the exec-flightsql feature.

Limitations

  • No NTH_VALUE on StarRocks 3.3 — an nth_value window is refused at compile time for this dialect. FIRST_VALUE/LAST_VALUE are unaffected.
  • No 3-argument DATEDIFF; a metric using the unit-first form is refused for this dialect.
  • No TLS on either path.

Verify the connection

$ dosi query --model model.yaml \
    --metrics revenue --group-by orders.status --execute --connection prod-sr

To confirm which path a profile takes, remove or restore arrow_flight_port: — Flight SQL is in use exactly when the key is present and the build has exec-flightsql.

Troubleshooting

Message Cause and fix
datasource "x" sets arrow_flight_port but this build lacks the exec-flightsql feature Rebuild with --features exec-flightsql (or exec-all), or drop the key.
datasource "x": missing arrow_flight_port The Flight executor was selected without the port — normally means the key was emptied rather than removed.
flight sql connect: <e> The FE Flight port is unreachable, or its address is not routable from this client.
flight sql handshake: <e> Credentials rejected by the Flight service.
flight sql: <message> The FE's own error for the statement — database-level DDL over Flight lands here.
cannot reach server: <io error> MySQL-wire path: host, port or network. Remember the FE port is 9030.
server rejected SQL (<code>): <message> StarRocks refused the compiled statement.

Reference