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. The FE hands out each BE's own address for the data pull. In Docker, publish the BE Flight port 1:1 (9419:9419); otherwise use the FE-proxy fallbacks (arrow_flight_proxy* session variables).
  • 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