This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-11897-a543411b6a5fbb71de613651604de5456252de7e in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
commit e7c6d29df68a1c69af413af6848be7e787ea173f Author: RIchard Baah <[email protected]> AuthorDate: Sun Oct 25 21:38:48 2026 +0000 docs(flight): document Flight SQL schema listing (#11897) # Which issue does this PR close? - Closes #7049 # Why The Flight crate links to its examples but does not show how to run a complete `GetFlightInfo` and `DoGet` flow. Without an end-to-end example, it is easy to construct `FlightData` fields as arbitrary IPC buffers and produce opaque decode failures. # What changed Adds a short walkthrough for running the existing Flight SQL server and listing schemas with the bundled client. It also calls out the helpers used to encode the schema and `DoGet` response, since constructing `FlightData` fields directly produces invalid IPC messages. --- arrow-flight/README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/arrow-flight/README.md b/arrow-flight/README.md index 49bf5a12b0..ae57e66b25 100644 --- a/arrow-flight/README.md +++ b/arrow-flight/README.md @@ -81,6 +81,44 @@ $ flight_sql_client --host example.com statement-query "SELECT 1;" +----------+ ``` +## Running the Flight SQL Example + +The [Flight SQL server example](examples/flight_sql_server.rs) implements the +`GetFlightInfo` and `DoGet` requests needed to list database schemas. From the +repository root, start the server with: + +```console +$ cargo run -p arrow-flight --example flight_sql_server --features flight-sql,tls-ring +Listening on 0.0.0.0:50051 +``` + +In another terminal, use the bundled client to list schemas: + +```console +$ cargo run -p arrow-flight --bin flight_sql_client --features cli,flight-sql,tls-ring -- \ + --host localhost --port 50051 db-schemas flight_sql --db-schema-filter '%' ++--------------+----------------+ +| catalog_name | db_schema_name | ++--------------+----------------+ +| flight_sql | example | ++--------------+----------------+ +``` + +This request has two steps: + +1. `get_flight_info_schemas` returns a `FlightInfo` containing the result + schema and an endpoint ticket. The example uses `FlightInfo::try_with_schema` + to encode the schema in the format required by the Flight protocol. +2. The client passes the ticket to `do_get_schemas`, which builds the metadata + `RecordBatch` and uses `FlightDataEncoderBuilder` to produce a correctly + framed stream of `FlightData` messages. + +`FlightData.data_header` and `FlightData.data_body` are IPC message components, +not arbitrary schema and IPC stream bytes. Constructing them directly, for +example by putting `Schema::to_string()` in `data_header`, produces invalid +messages. Use `FlightInfo::try_with_schema` for `FlightInfo` schemas and +`FlightDataEncoderBuilder` for `DoGet` response streams. + ## Security See the [Security Policy] for information on the security model and how to report vulnerabilities.
