From 997a70e05a2b078bd4df2726b7a21530f15fb9d6 Mon Sep 17 00:00:00 2001 From: justing-bq <62349012+justing-bq@users.noreply.github.com> Date: Thu, 23 Apr 2026 11:40:03 -0700 Subject: [PATCH 1/3] Update ODBC Documentation --- cpp/src/arrow/flight/sql/odbc/README.md | 42 +++++++++--- .../flight/sql/odbc/connection-options.md | 64 +++++++++++++++++++ 2 files changed, 96 insertions(+), 10 deletions(-) create mode 100644 cpp/src/arrow/flight/sql/odbc/connection-options.md diff --git a/cpp/src/arrow/flight/sql/odbc/README.md b/cpp/src/arrow/flight/sql/odbc/README.md index a2a3fd79041a..949ae343c545 100644 --- a/cpp/src/arrow/flight/sql/odbc/README.md +++ b/cpp/src/arrow/flight/sql/odbc/README.md @@ -17,19 +17,25 @@ 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 `build\debug\Debug\arrow_flight_sql_odbc.dll` for a debug build and `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 `build/debug/libarrow_flight_sql_odbc.dylib` for a debug build and `build/release/libarrow_flight_sql_odbc.dylib` for a release build. - Need to replace `` with actual path to repository in the commands. +On Linux, the driver binary will be located at `build/debug/libarrow_flight_sql_odbc.so` for a debug build and `build/release/libarrow_flight_sql_odbc.so` for a release build. - 1. `cd ` - 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 Power Shell in administrator mode. + +2. Register your ODBC binary: + + These commands need `` to be replaced with the actual path to the repository. + + 1. `cd ` + 2. Run script to register your ODBC driver binary as Apache Arrow Flight SQL ODBC Driver.
+ On Windows: ``` .\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd \cpp\build\< release | debug >\< Release | Debug>\arrow_flight_sql_odbc.dll ``` @@ -37,9 +43,24 @@ After the build succeeds, the ODBC DLL will be located in ``` .\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: + ``` + ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/< release | debug >/libarrow_flight_sql_odbc.dylib + ``` + Example command for reference: + ``` + ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/release/libarrow_flight_sql_odbc.dylib + ``` + On Linux: + ``` + ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/< release | debug >/libarrow_flight_sql_odbc.so + ``` + Example command for reference: + ``` + ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /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 & Linux this should be visible in your system odbc.ini. ## Steps to Generate Windows Installer 1. Install WiX toolset v6 from [GitHub](https://github.com/wixtoolset/wix/releases/). @@ -129,3 +150,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 000000000000..87d884aba673 --- /dev/null +++ b/cpp/src/arrow/flight/sql/odbc/connection-options.md @@ -0,0 +1,64 @@ + + +# 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 inside your system's odbc.ini. + +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=1234.56.789;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 = 1234.56.789 +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 +| `dsn` | Data Source Name used for configuring the connection. | `NONE` +| `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` on Windows & Linux, `false` on MacOS +| `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` +| `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 From ba1ba2fee3ae5bfbb551a97cfa9d072fc935f948 Mon Sep 17 00:00:00 2001 From: justing-bq <62349012+justing-bq@users.noreply.github.com> Date: Tue, 28 Apr 2026 12:44:00 -0700 Subject: [PATCH 2/3] Address feedback --- cpp/src/arrow/flight/sql/odbc/README.md | 26 +++++------ .../flight/sql/odbc/connection-options.md | 46 +++++++++---------- 2 files changed, 35 insertions(+), 37 deletions(-) diff --git a/cpp/src/arrow/flight/sql/odbc/README.md b/cpp/src/arrow/flight/sql/odbc/README.md index 949ae343c545..80fac7846593 100644 --- a/cpp/src/arrow/flight/sql/odbc/README.md +++ b/cpp/src/arrow/flight/sql/odbc/README.md @@ -21,46 +21,44 @@ After building the repository you will find the built ODBC binaries in the build artifacts. -On Windows, the driver binary will be located at `build\debug\Debug\arrow_flight_sql_odbc.dll` for a debug build and `build\release\Release\arrow_flight_sql_odbc.dll` for a release build. +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. -On MacOS, the driver binary will be located at `build/debug/libarrow_flight_sql_odbc.dylib` for a debug build and `build/release/libarrow_flight_sql_odbc.dylib` for a release build. +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. -On Linux, the driver binary will be located at `build/debug/libarrow_flight_sql_odbc.so` for a debug build and `build/release/libarrow_flight_sql_odbc.so` for a release build. +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. Open your system terminal. On Windows this should be Power Shell in administrator mode. +1. Open your system terminal. On Windows this should be PowerShell in administrator mode. 2. Register your ODBC binary: - These commands need `` to be replaced with the actual path to the repository. - - 1. `cd ` + 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.
On Windows: ``` - .\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd \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: + On macOS: ``` - ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/< release | debug >/libarrow_flight_sql_odbc.dylib + 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: ``` - ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/release/libarrow_flight_sql_odbc.dylib + 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: ``` - ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/< release | debug >/libarrow_flight_sql_odbc.so + 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: ``` - ./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh /cpp/build/release/libarrow_flight_sql_odbc.so + 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. On Windows this should be visible in the x64 ODBC Driver Manager. On MacOS & Linux this should be visible in your system odbc.ini. +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/). diff --git a/cpp/src/arrow/flight/sql/odbc/connection-options.md b/cpp/src/arrow/flight/sql/odbc/connection-options.md index 87d884aba673..1aeca075e894 100644 --- a/cpp/src/arrow/flight/sql/odbc/connection-options.md +++ b/cpp/src/arrow/flight/sql/odbc/connection-options.md @@ -27,17 +27,17 @@ The following sample connection string and sample DSN are two equivalent ways to ### Sample Connection String ``` -"driver={Apache Arrow Flight SQL ODBC Driver};HOST=1234.56.789;port=12345;uid=sample_user;pwd=sample_password;useEncryption=false;useWideChar=true;" +"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 = 1234.56.789 -Port = 12345 -UID = sample_user -PWD = sample_password +driver = Apache Arrow Flight SQL ODBC Driver +host = 127.0.0.1 +port = 12345 +uid = sample_user +pwd = sample_password useEncryption = false useWideChar = true ``` @@ -45,20 +45,20 @@ useWideChar = true ### Driver Connection Options | Option | Description | Default | |--------|-------------|---------------| -| `driver` | Required: the driver for this ODBC driver. | Apache Arrow Flight SQL -| `dsn` | Data Source Name used for configuring the connection. | `NONE` -| `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` on Windows & Linux, `false` on MacOS -| `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` -| `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 +| `driver` | Required: the driver for this ODBC driver. | Apache Arrow Flight SQL | +| `dsn` | Data Source Name used for configuring the connection. | `NONE` | +| `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 | From 89aa25c80aee6d39394e40bd192c2a67ba6a0db0 Mon Sep 17 00:00:00 2001 From: justing-bq <62349012+justing-bq@users.noreply.github.com> Date: Thu, 30 Apr 2026 11:51:46 -0700 Subject: [PATCH 3/3] Address more feedback --- cpp/src/arrow/flight/sql/odbc/README.md | 2 +- cpp/src/arrow/flight/sql/odbc/connection-options.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/cpp/src/arrow/flight/sql/odbc/README.md b/cpp/src/arrow/flight/sql/odbc/README.md index 80fac7846593..f863ea851b8a 100644 --- a/cpp/src/arrow/flight/sql/odbc/README.md +++ b/cpp/src/arrow/flight/sql/odbc/README.md @@ -148,4 +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. +- 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 index 1aeca075e894..044368c506de 100644 --- a/cpp/src/arrow/flight/sql/odbc/connection-options.md +++ b/cpp/src/arrow/flight/sql/odbc/connection-options.md @@ -21,13 +21,13 @@ ## Setting ODBC Connection Properties -ODBC connection parameters can be set in a connection string or defined in a DSN inside your system's odbc.ini. +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;" +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 @@ -45,8 +45,8 @@ useWideChar = true ### Driver Connection Options | Option | Description | Default | |--------|-------------|---------------| -| `driver` | Required: the driver for this ODBC driver. | Apache Arrow Flight SQL | -| `dsn` | Data Source Name used for configuring the connection. | `NONE` | +| `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` |