This is an automated email from the ASF dual-hosted git repository.
lidavidm 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 b42d44e32f GH-37889: [Java][Doc] Improve JDBC driver documentation
(#38469)
b42d44e32f is described below
commit b42d44e32fe64c2f9e04d701300f170c9f47f3b3
Author: James Duong <[email protected]>
AuthorDate: Mon Oct 30 08:02:57 2023 -0700
GH-37889: [Java][Doc] Improve JDBC driver documentation (#38469)
### Rationale for this change
Correct inaccuracies and better document how to connect with the Flight SQL
JDBC Driver.
### What changes are included in this PR?
- Correct the user property.
- Correct the default for useEncryption.
- Elaborate on using the Properties object when connecting and describe the
order of precedence.
### Are these changes tested?
N/A
### Are there any user-facing changes?
Yes
* Closes: #37889
Authored-by: James Duong <[email protected]>
Signed-off-by: David Li <[email protected]>
---
docs/source/java/flight_sql_jdbc_driver.rst | 25 +++++++++++++++++++------
1 file changed, 19 insertions(+), 6 deletions(-)
diff --git a/docs/source/java/flight_sql_jdbc_driver.rst
b/docs/source/java/flight_sql_jdbc_driver.rst
index 3b45cdd8b8..8268242302 100644
--- a/docs/source/java/flight_sql_jdbc_driver.rst
+++ b/docs/source/java/flight_sql_jdbc_driver.rst
@@ -80,8 +80,8 @@ The components of the URI are as follows.
* **HOSTNAME** is the hostname of the Flight SQL service.
* **PORT** is the port of the Flight SQL service.
-Additional options can be passed as query parameters. The supported
-parameters are:
+Additional options can be passed as query parameters. Parameter names are
+case-sensitive. The supported parameters are:
.. list-table::
:header-rows: 1
@@ -115,11 +115,10 @@ parameters are:
- When TLS is enabled, the password for the certificate store
* - useEncryption
- - false
- - Whether to use TLS (the default is an insecure, plaintext
- connection)
+ - true
+ - Whether to use TLS (the default is an encrypted connection)
- * - username
+ * - user
- null
- The username for user/password authentication
@@ -127,6 +126,9 @@ parameters are:
- true
- When TLS is enabled, whether to use the system certificate store
+Note that URI values must be URI-encoded if they contain characters such
+as !, @, $, etc.
+
Any URI parameters that are not handled by the driver are passed to
the Flight SQL service as gRPC headers. For example, the following URI ::
@@ -135,3 +137,14 @@ the Flight SQL service as gRPC headers. For example, the
following URI ::
This will connect without authentication or encryption, to a Flight
SQL service running on ``localhost`` on port 12345. Each request will
also include a `database=mydb` gRPC header.
+
+Connection parameters may also be supplied using the Properties object
+when using the JDBC Driver Manager to connect. When supplying using
+the Properties object, values should *not* be URI-encoded.
+
+Parameters specified by the URI supercede parameters supplied by the
+Properties object. When calling the `user/password overload of
+DriverManager#getConnection()
+<https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html#getConnection-java.lang.String-java.lang.String-java.lang.String->`_,
+the username and password supplied on the URI supercede the username and
+password arguments to the function call.
