Skip to content

Commit c9d55a8

Browse files
justing-bqjusting-bq
committed
Update ODBC Documentation
1 parent 487f148 commit c9d55a8

2 files changed

Lines changed: 96 additions & 10 deletions

File tree

‎cpp/src/arrow/flight/sql/odbc/README.md‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,29 +17,50 @@
1717
under the License.
1818
-->
1919

20-
## Steps to Register the 64-bit Apache Arrow ODBC driver on Windows
20+
## Steps to Register the Apache Arrow Flight SQL ODBC driver
2121

22-
After the build succeeds, the ODBC DLL will be located in
23-
`build\debug\Debug` for a debug build and `build\release\Release` for a release build.
22+
After building the repository you will find the built ODBC binaries in the build artifacts.
2423

25-
1. Open Windows Power Shell as administrator.
24+
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.
2625

27-
2. Register your ODBC DLL:
26+
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.
2827

29-
Need to replace `<path\to\repo>` with actual path to repository in the commands.
28+
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.
3029

31-
1. `cd <path\to\repo>`
32-
2. Run script to register your ODBC DLL as Apache Arrow Flight SQL ODBC Driver
30+
1. Open your system terminal. On Windows this should be Power Shell in administrator mode.
31+
32+
2. Register your ODBC binary:
33+
34+
These commands need `<path/to/repo>` to be replaced with the actual path to the repository.
35+
36+
1. `cd <path/to/repo>`
37+
2. Run script to register your ODBC driver binary as Apache Arrow Flight SQL ODBC Driver.<br>
38+
On Windows:
3339
```
3440
.\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd <path\to\repo>\cpp\build\< release | debug >\< Release | Debug>\arrow_flight_sql_odbc.dll
3541
```
3642
Example command for reference:
3743
```
3844
.\cpp\src\arrow\flight\sql\odbc\tests\install_odbc.cmd C:\path\to\arrow\cpp\build\release\Release\arrow_flight_sql_odbc.dll
3945
```
46+
On MacOS:
47+
```
48+
./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh <path/to/repo>/cpp/build/< release | debug >/libarrow_flight_sql_odbc.dylib
49+
```
50+
Example command for reference:
51+
```
52+
./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh <path/to/arrow>/cpp/build/release/libarrow_flight_sql_odbc.dylib
53+
```
54+
On Linux:
55+
```
56+
./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh <path/to/repo>/cpp/build/< release | debug >/libarrow_flight_sql_odbc.so
57+
```
58+
Example command for reference:
59+
```
60+
./cpp/src/arrow/flight/sql/odbc/install/unix/install_odbc.sh <path/to/arrow>/cpp/build/release/libarrow_flight_sql_odbc.so
61+
```
4062
41-
If the registration is successful, then Apache Arrow Flight SQL ODBC Driver
42-
should show as an available ODBC driver in the x64 ODBC Driver Manager.
63+
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.
4364
4465
## Steps to Generate Windows Installer
4566
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
129150
130151
- 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.
131152
- Conversion from strings to big int data type has a limit range of -9007199254740992 to 9007199254740992.
153+
- On Linux, `isql` commands `tables` and `columns` don’t work due to GH-49702. Users are not blocked from fetching data tables.

‎cpp/src/arrow/flight/sql/odbc/connection-options.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
<!---
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# Connection Properties on Apache Arrow Flight SQL ODBC Driver
21+
22+
## Setting ODBC Connection Properties
23+
24+
ODBC connection parameters can be set in a connection string or defined in a DSN inside your system's odbc.ini.
25+
26+
The following sample connection string and sample DSN are two equivalent ways to connect to Arrow.
27+
28+
### Sample Connection String
29+
```
30+
"driver={Apache Arrow Flight SQL ODBC Driver};HOST=1234.56.789;port=12345;uid=sample_user;pwd=sample_password;useEncryption=false;UseWideChar=true;"
31+
```
32+
33+
### Sample DSN
34+
```
35+
[Apache Arrow Flight SQL]
36+
Driver = Apache Arrow Flight SQL ODBC Driver
37+
Host = 1234.56.789
38+
Port = 12345
39+
UID = sample_user
40+
PWD = sample_password
41+
useEncryption = false
42+
UseWideChar = true
43+
```
44+
45+
### Driver Connection Options
46+
| Option | Description | Default |
47+
|--------|-------------|---------------|
48+
| `driver` | Required: the driver for this ODBC driver. | Apache Arrow Flight SQL
49+
| `dsn` | Data Source Name used for configuring the connection. | `NONE`
50+
| `host` | The IP address or hostname for the server. | `NONE`
51+
| `port` | The TCP port number the server uses for ODBC connections. | `NONE`
52+
| `user` | The username for authentication to the server. | `NONE`
53+
| `user id` | The username for authentication to the server. | `NONE`
54+
| `uid` | The username for authentication to the server. | `NONE`
55+
| `password` | The password for authentication to the server. | `NONE`
56+
| `pwd` | The password for authentication to the server. | `NONE`
57+
| `token` | The personal access token for authentication to the server. | `NONE`
58+
| `useEncryption` | Setting to determine if an SSL-encrypted connection should be used. | `true` on Windows & Linux, `false` on MacOS
59+
| `disableCertificateVerification` | Setting to determine if the driver should verify the host certificate against the trust store. | `false`
60+
| `trustedCerts` | The full path of the .pem file containing certificates for the purpose of verifying the server. | `NONE`
61+
| `useSystemTrustStore` | Setting to determine whether to use a CA certificate from the system's trust store or from a specified .pem file. | `true`
62+
| `stringColumnLength` | Maximum length of a string column. | `NONE`
63+
| `useWideChar` | Setting to determine if wide characters should be used. | `true` on Windows, `false` on MacOS & Linux
64+
| `chunkBufferCapacity` | Capacity of a chunk buffer. | 5

0 commit comments

Comments
 (0)