Client

How to connect

You must specify PostgreSQL user and PostgreSQL database to connect Apache Arrow Flight SQL endpoint.

User name and password must be passed by Handshake call. Note that basic authentication is only supported for now. mTLS (mutual-TLS) isn‘t implemented yet. If you’re interested in mTLS, please see the issue for it: https://github.com/apache/arrow-flight-sql-postgresql/issues/79

You need to use a header to specify PostgreSQL database. The header name for PostgreSQL database is x-flight-sql-database.

You need to use
[`arrow::flight::FlightClient::AuthenticateBasicToken()`][arrow-flight-authenticate-basic]
for authentication.

You need to add a `x-flight-sql-database` header to
[`arrow::flight::FlightCallOptions::headers`][arrow-flight-call-options-headers]
for database.

The following example uses `PGUSER` (fallback to `USER`) and
`PGPASSWORD` environment variables like
`libpq`. `AuthenticateBasicToken()` returns Bearer token on
success. So the example users the returned Bearer token to request
headers to use following requests.

The following example uses `PGDATABASE` (fallback to `PGUSER`/`USER`)
environment variable like `libpq`.

```{literalinclude} ../../example/flight-sql/authenticate-password.cc
:language: c++
:linenos:
:tab-width: 4
:start-after: // Start authentication
:end-before: // End authentication
```

You need to set the
`username` and `password` options for authentication. See also the
[Authentication][arrow-adbc-authentication] document.

You need to set the
`adbc.flight.sql.rpc.call_header.x-flight-sql-database` option for
database. See also the [Custom Call
Headers][arrow-adbc-custom-call-headers] document.

```{literalinclude} ../../example/adbc/authenticate-password.c
:language: c
:linenos:
:tab-width: 4
:start-after: // Start authentication
:end-before: // End authentication
```

How to query

You can use an ad-hoc SQL statement or a prepared SQL statement to query.

Ad-hoc SQL statement

You need to use
[`arrow::flight::sql::FlightSqlClient::Execute()`][arrow-flight-sql-client-execute]
to execute a query.

You need to use
[`arrow::flight::sql::FlightSqlClient::DoGet()`][arrow-flight-sql-client-do-get]
to get results.

```{literalinclude} ../../example/flight-sql/query-ad-hoc.cc
:language: c++
:linenos:
:tab-width: 4
:start-after: // Start query
:end-before: // End query
```

TODO

Prepared SQL statement

You need to use
[`arrow::flight::sql::FlightSqlClient::Prepare()`][arrow-flight-sql-client-prepare]
to prepare a query.

You need to use
[`arrow::flight::sql::PreparedStatement::SetParameters()`][arrow-flight-sql-prepared-statement-set-parameters]
to set parameters.

You need to use
[`arrow::flight::sql::PreparedStatement::Execute()`][arrow-flight-sql-prepared-statement-execute]
to execute a prepared statement with parameters.

You need to use
[`arrow::flight::sql::FlightSqlClient::DoGet()`][arrow-flight-sql-client-do-get]
to get results.

```{literalinclude} ../../example/flight-sql/query-prepared.cc
:language: c++
:linenos:
:tab-width: 4
:start-after: // Start query
:end-before: // End query
```

TODO