This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new e7c6d29df6 docs(flight): document Flight SQL schema listing (#11897)
e7c6d29df6 is described below
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.
