This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 603eeec8f6 GH-49723: [C++][FlightRPC][ODBC] Update ODBC Documentation
(#49851)
603eeec8f6 is described below
commit 603eeec8f6d75fa3d029be0aefbf1405a0dde69b
Author: justing-bq <[email protected]>
AuthorDate: Tue May 19 18:56:11 2026 -0700
GH-49723: [C++][FlightRPC][ODBC] Update ODBC Documentation (#49851)
### Rationale for this change
Update ODBC Documentation in preparation for public release.
Resolves https://github.com/apache/arrow/issues/49723
### What changes are included in this PR?
Miscellaneous doc changes.
### Are these changes tested?
N/A
### Are there any user-facing changes?
No
* GitHub Issue: #49723
Authored-by: justing-bq <[email protected]>
Signed-off-by: Sutou Kouhei <[email protected]>
---
cpp/src/arrow/flight/sql/odbc/README.md | 42 ++++++++++----
.../arrow/flight/sql/odbc/connection-options.md | 64 ++++++++++++++++++++++
2 files changed, 95 insertions(+), 11 deletions(-)
diff --git a/cpp/src/arrow/flight/sql/odbc/README.md
b/cpp/src/arrow/flight/sql/odbc/README.md
index a2a3fd7904..f863ea851b 100644
--- a/cpp/src/arrow/flight/sql/odbc/README.md
+++ b/cpp/src/arrow/flight/sql/odbc/README.md
@@ -17,29 +17,48 @@
under the License.
-->
-## Steps to Register the 64-bit Apache Arrow ODBC driver on Windows
+## Steps to Register the Apache Arrow Flight SQL ODBC driver
-After the build succeeds, the ODBC DLL will be located in
-`build\debug\Debug` for a debug build and `build\release\Release` for a
release build.
+After building the repository you will find the built ODBC binaries in the
build artifacts.
-1. Open Windows Power Shell as administrator.
+On Windows, the driver binary will be located at
`C:\path\to\arrow\cpp\build\debug\Debug\arrow_flight_sql_odbc.dll` for a debug
build and
`C:\path\to\arrow\cpp\build\release\Release\arrow_flight_sql_odbc.dll` for a
release build.
-2. Register your ODBC DLL:
+On macOS, the driver binary will be located at
`/path/to/arrow/cpp/build/debug/libarrow_flight_sql_odbc.dylib` for a debug
build and `/path/to/arrow/cpp/build/release/libarrow_flight_sql_odbc.dylib` for
a release build.
- Need to replace `<path\to\repo>` with actual path to repository in the
commands.
+On Linux, the driver binary will be located at
`/path/to/arrow/cpp/build/debug/libarrow_flight_sql_odbc.so` for a debug build
and `/path/to/arrow/cpp/build/release/libarrow_flight_sql_odbc.so` for a
release build.
- 1. `cd <path\to\repo>`
- 2. Run script to register your ODBC DLL as Apache Arrow Flight SQL ODBC
Driver
+1. Open your system terminal. On Windows this should be PowerShell in
administrator mode.
+
+2. Register your ODBC binary:
+
+ 1. Navigate to the root of the Arrow repo.
+ 2. Run script to register your ODBC driver binary as Apache Arrow Flight
SQL ODBC Driver.<br>
+ On Windows:
```
- .\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd
<path\to\repo>\cpp\build\< release | debug >\< Release |
Debug>\arrow_flight_sql_odbc.dll
+ .\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd
C:\path\to\arrow\cpp\build\< release | debug >\< Release |
Debug>\arrow_flight_sql_odbc.dll
```
Example command for reference:
```
.\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd
C:\path\to\arrow\cpp\build\release\Release\arrow_flight_sql_odbc.dll
```
+ On macOS:
+ ```
+ sudo ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh
/path/to/arrow/cpp/build/< release | debug >/libarrow_flight_sql_odbc.dylib
+ ```
+ Example command for reference:
+ ```
+ sudo ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh
/path/to/arrow/cpp/build/release/libarrow_flight_sql_odbc.dylib
+ ```
+ On Linux:
+ ```
+ sudo ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh
/path/to/arrow/cpp/build/< release | debug >/libarrow_flight_sql_odbc.so
+ ```
+ Example command for reference:
+ ```
+ sudo ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh
/path/to/arrow/cpp/build/release/libarrow_flight_sql_odbc.so
+ ```
-If the registration is successful, then Apache Arrow Flight SQL ODBC Driver
-should show as an available ODBC driver in the x64 ODBC Driver Manager.
+If the registration is successful, then Apache Arrow Flight SQL ODBC Driver
should show as an available ODBC driver. On Windows this should be visible in
the x64 ODBC Driver Manager. On macOS this should be visible in
`$HOME/Library/ODBC/odbcinst.ini`. On Linux this should be visible in
`/etc/odbcinst.ini`.
## Steps to Generate Windows Installer
1. Install WiX toolset v6 from
[GitHub](https://github.com/wixtoolset/wix/releases/).
@@ -129,3 +148,4 @@ After ODBC has been registered, you can run the ODBC tests.
It is recommended to
- Conversion from timestamp data type with specified time zone value to
strings is not supported at the moment. This doesn't impact driver's usage of
retrieving timestamp data from Power BI on Windows, and Excel on macOS and
Windows. See GH-47504 for more context.
- Conversion from strings to big int data type has a limit range of
-9007199254740992 to 9007199254740992.
+- On Linux, `isql` commands `tables` and `columns` don't work due to GH-49702.
Users are not blocked from fetching data tables.
diff --git a/cpp/src/arrow/flight/sql/odbc/connection-options.md
b/cpp/src/arrow/flight/sql/odbc/connection-options.md
new file mode 100644
index 0000000000..044368c506
--- /dev/null
+++ b/cpp/src/arrow/flight/sql/odbc/connection-options.md
@@ -0,0 +1,64 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Connection Properties on Apache Arrow Flight SQL ODBC Driver
+
+## Setting ODBC Connection Properties
+
+ODBC connection parameters can be set in a connection string or defined in a
DSN. On macOS and Linux, DSNs are typically defined in your system's
`odbc.ini`. On Windows they are typically configured with the ODBC Data Source
Administrator.
+
+The following sample connection string and sample DSN are two equivalent ways
to connect to Arrow.
+
+### Sample Connection String
+```
+driver={Apache Arrow Flight SQL ODBC
Driver};host=127.0.0.1;port=12345;uid=sample_user;pwd=sample_password;useEncryption=false;useWideChar=true;
+```
+
+### Sample DSN
+```
+[Apache Arrow Flight SQL]
+driver = Apache Arrow Flight SQL ODBC Driver
+host = 127.0.0.1
+port = 12345
+uid = sample_user
+pwd = sample_password
+useEncryption = false
+useWideChar = true
+```
+
+### Driver Connection Options
+| Option | Description | Default |
+|--------|-------------|---------------|
+| `driver` | Required: the driver for this ODBC driver. | `Apache Arrow Flight
SQL ODBC Driver` |
+| `dsn` | Data Source Name used for configuring the connection. | `Apache
Arrow Flight SQL` |
+| `host` | The IP address or hostname for the server. | `NONE` |
+| `port` | The TCP port number the server uses for ODBC connections. | `NONE` |
+| `user` | The username for authentication to the server. | `NONE` |
+| `user id` | The username for authentication to the server. | `NONE` |
+| `uid` | The username for authentication to the server. | `NONE` |
+| `password` | The password for authentication to the server. | `NONE` |
+| `pwd` | The password for authentication to the server. | `NONE` |
+| `token` | The personal access token for authentication to the server. |
`NONE` |
+| `useEncryption` | Setting to determine if an SSL-encrypted connection should
be used. | `true` |
+| `disableCertificateVerification` | Setting to determine if the driver should
verify the host certificate against the trust store. | `false` |
+| `trustedCerts` | The full path of the .pem file containing certificates for
the purpose of verifying the server. | `NONE` |
+| `useSystemTrustStore` | Setting to determine whether to use a CA certificate
from the system's trust store or from a specified .pem file. | `true` on
Windows, `false` on macOS & Linux |
+| `stringColumnLength` | Maximum length of a string column. Some apps may
require a lower length. | `NONE` |
+| `useWideChar` | Setting to determine if wide characters should be used.
Important for Unicode applications. | `true` on Windows, `false` on macOS &
Linux |
+| `chunkBufferCapacity` | Capacity of a chunk buffer. Larger values will
improve throughput at the cost of increased memory usage. | 5 |
