Connect with a database client

​

Enable the endpoint

[flight_sql]
enabled = true
bind = "0.0.0.0"
port = 5083
# Default time window when the SQL carries no pruning hint (see below)
default_lookback_hours = 24

​

Authentication

• SSO accounts: OIDC/SAML-only accounts have no local password, so account login cannot work. Use an API token instead.
• Session expiry: the JWT issued by account login expires after the server’s token_ttl_secs. Requests then fail with UNAUTHENTICATED; DBeaver silently reconnects with saved credentials, so interactive use is unaffected. Long-running ADBC scripts should use a non-expiring API token instead.

​

DBeaver

1. Database → Driver Manager → New
2. On the Libraries tab, click Add Artifact and paste org.apache.arrow:flight-sql-jdbc-driver:RELEASE, then Download/Update (or Add File with a locally downloaded driver jar)
3. Back on Settings: Driver Name Arrow Flight SQL, Class Name org.apache.arrow.driver.jdbc.ArrowFlightJdbcDriver, URL Template jdbc:arrow-flight-sql://{host}:{port}/?useEncryption=false
4. New Connection → select the newly created driver → Host: MoleSignal server, Port: 5083
5. Username: account email (optionally email@org), Password: account password — or Username token / Password ms_...

​

JDBC

jdbc:arrow-flight-sql://molesignal.example.com:5083/?useEncryption=false&user=token&password=ms_...

​

Python (ADBC)

import adbc_driver_flightsql.dbapi as flightsql

conn = flightsql.connect(
    "grpc://molesignal.example.com:5083",
    db_kwargs={"username": "token", "password": "ms_..."},
)
cur = conn.cursor()
cur.execute("SELECT level, count(*) AS n FROM logs.nginx GROUP BY level")
print(cur.fetch_arrow_table())   # or fetchall() / .fetch_df()

​

Writing queries

• Qualify tables with the stream type: logs.nginx, metrics.cpu_usage, traces.checkout, extend.lookup_table. An unqualified name defaults to logs. Fully qualified names including the catalog (molesignal.logs.nginx — the form generated by DBeaver during table browsing) work too.
• Read-only: INSERT / UPDATE / DELETE / DDL are rejected.
• Time window: Flight SQL has no time-range parameter, so the server scans the last default_lookback_hours (24h by default) for partition pruning. A _timestamp filter in the WHERE clause still applies within that window. To query further back, raise default_lookback_hours, or use the HTTP query API which takes an explicit time range.
• _timestamp is returned as a microsecond-precision timestamp column.

​

Limitations

• Prepared statements work, but parameter binding does not — inline literals instead.
• No transactions (read-only engine).
• PromQL is not available over Flight SQL; use the HTTP API for PromQL.
• Result schema in FlightInfo is empty; clients read the schema from the data stream (DBeaver and ADBC handle this transparently).