From 8f8c59bc1732263d310a7a18be8cd610304e4149 Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 15 Sep 2022 11:16:36 -0400 Subject: [PATCH 1/2] ARROW-17332: [Docs][Java] Add minimal JDBC driver docs --- docs/source/java/flight_sql.rst | 32 ++++++ docs/source/java/flight_sql_jdbc_driver.rst | 120 ++++++++++++++++++++ docs/source/java/index.rst | 2 + 3 files changed, 154 insertions(+) create mode 100644 docs/source/java/flight_sql.rst create mode 100644 docs/source/java/flight_sql_jdbc_driver.rst diff --git a/docs/source/java/flight_sql.rst b/docs/source/java/flight_sql.rst new file mode 100644 index 00000000000..dbf97238d4c --- /dev/null +++ b/docs/source/java/flight_sql.rst @@ -0,0 +1,32 @@ +.. 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. + +================ +Arrow Flight SQL +================ + +Arrow Flight SQL is an RPC framework for efficient transfer of Arrow data +over the network. + +.. seealso:: + + :doc:`Flight SQL protocol documentation <../format/FlightSql>` + Documentation of the Flight SQL protocol. + +For usage information, see the `API documentation`_. + +.. _API documentation: https://arrow.apache.org/docs/java/reference/org/apache/arrow/flight/sql/package-summary.html diff --git a/docs/source/java/flight_sql_jdbc_driver.rst b/docs/source/java/flight_sql_jdbc_driver.rst new file mode 100644 index 00000000000..a6124b4084b --- /dev/null +++ b/docs/source/java/flight_sql_jdbc_driver.rst @@ -0,0 +1,120 @@ +.. 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. + +============================ +Arrow Flight SQL JDBC Driver +============================ + +The Flight SQL JDBC driver is a JDBC driver implementation that uses +the :doc:`Flight SQL protocol <../format/FlightSql>` under the hood. +This driver can be used with any database that implements Flight SQL. + +.. contents:: + +Installation and Requirements +============================= + +The driver is compatible with JDK 8+. On JDK 9+, the following JVM +parameter is required: + +.. code-block:: shell + + java --add-opens=java.base/java.nio=ALL-UNNAMED ... + +To add a dependency via Maven, use a ``pom.xml`` like the following: + +.. code-block:: xml + + + + 4.0.0 + org.example + demo + 1.0-SNAPSHOT + + 10.0.0 + + + + org.apache.arrow + flight-sql-jdbc-driver + ${arrow.version} + + + + +Connecting to a Database +======================== + +The URI format is as follows:: + + jdbc:arrow-flight-sql://HOSTNAME:PORT[/?param1=val1¶m2=val2&...] + +where + +* **HOSTNAME** is the hostname of the Flight SQL service. +* **PORT** is the port of the Flight SQL service. + +By default, this will create an insecure (plaintext) connection. + +Additional options can be passed as query parameters. The supported +parameters are: + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Default + - Description + + * - disableCertificateVerification + - false + - When TLS is enabled, whether to verify the server certificate + + * - password + - null + - The password for user/password authentication + + * - threadPoolSize + - 1 + - The size of an internal thread pool + + * - token + - null + - The token used for token authentication + + * - trustStore + - null + - When TLS is enabled, the path to the certificate store + + * - trustStorePassword + - null + - When TLS is enabled, the password for the certificate store + + * - useEncryption + - false + - Whether to use TLS + + * - username + - null + - The username for user/password authentication + + * - useSystemTrustStore + - true + - When TLS is enabled, whether to use the system certificate store diff --git a/docs/source/java/index.rst b/docs/source/java/index.rst index 3c9bde6ba53..a1e924f9c09 100644 --- a/docs/source/java/index.rst +++ b/docs/source/java/index.rst @@ -34,6 +34,8 @@ on the Arrow format and other language bindings see the :doc:`parent documentati ipc algorithm flight + flight_sql + flight_sql_jdbc_driver dataset cdata jdbc From 08adf3bf7b5e963b538cb576c714e0f167eae2b2 Mon Sep 17 00:00:00 2001 From: David Li Date: Tue, 18 Oct 2022 14:55:44 -0400 Subject: [PATCH 2/2] Add example URI --- docs/source/java/flight_sql_jdbc_driver.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/source/java/flight_sql_jdbc_driver.rst b/docs/source/java/flight_sql_jdbc_driver.rst index a6124b4084b..65b1a7162f4 100644 --- a/docs/source/java/flight_sql_jdbc_driver.rst +++ b/docs/source/java/flight_sql_jdbc_driver.rst @@ -66,13 +66,20 @@ The URI format is as follows:: jdbc:arrow-flight-sql://HOSTNAME:PORT[/?param1=val1¶m2=val2&...] -where +For example, take this URI:: + jdbc:arrow-flight-sql://localhost:12345/?username=admin&password=pass&useEncryption=1 + +This will connect to a Flight SQL service running on ``localhost`` on +port 12345. It will create a secure, encrypted connection, and +authenticate using the username ``admin`` and the password ``pass``. + +The components of the URI are as follows. + +* The URI scheme must be ``jdbc:arrow-flight-sql://``. * **HOSTNAME** is the hostname of the Flight SQL service. * **PORT** is the port of the Flight SQL service. -By default, this will create an insecure (plaintext) connection. - Additional options can be passed as query parameters. The supported parameters are: @@ -109,7 +116,8 @@ parameters are: * - useEncryption - false - - Whether to use TLS + - Whether to use TLS (the default is an insecure, plaintext + connection) * - username - null