Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GH-37889: [Java][Doc] Improve JDBC driver documentation #38469

Merged
merged 2 commits into from
Oct 30, 2023
Merged

GH-37889: [Java][Doc] Improve JDBC driver documentation #38469

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8aa7b18
GH-37899: [Java][Doc] Improve JDBC driver documentation
jduo Oct 25, 2023
f3c3c3a
Note that property names are case-sensitive
jduo Oct 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions docs/source/java/flight_sql_jdbc_driver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -115,18 +115,20 @@ 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe discuss if this is case sensitive? When I was setting up DBeaver, all the other major parameters were in the form FOO_BAR, and this one is documented as fooBar

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, all parameters should be camelCase per:

arrow/java/flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/ArrowFlightConnectionConfigImpl.java

Line 168 in 547b240

public enum ArrowFlightConnectionProperty implements ConnectionProperty {

and

arrow/java/flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/ArrowFlightConnectionConfigImpl.java

Line 202 in 547b240

Object value = properties.get(camelName);

Though the get() implementation seems to also allow fully lower-case. It's probably supposed to be case-insensitive though.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's explicitly document whether it's case-sensitive or not, and maybe we can split out a separate ticket to make it case-insensitive if needed

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've documented that names are case-sensitive for simplicity's sake.

If we want to be more precise, names are case-insensitive on the connection URI (since we internally lower-case them after parsing) and case-sensitive in the Properties object, but really they should consistently be case-insensitive.

- Whether to use TLS (the default is an encrypted connection)

* - username
* - user
- null
- The username for user/password authentication

* - useSystemTrustStore
- 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 ::

Expand All @@ -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.