This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository
https://gitbox.apache.org/repos/asf/arrow-flight-sql-postgresql.git
The following commit(s) were added to refs/heads/main by this push:
new f0f9421 Publish website (#80)
f0f9421 is described below
commit f0f9421c641c01685066e34d3f5c1573a9cfce6d
Author: Sutou Kouhei <[email protected]>
AuthorDate: Mon Aug 28 21:36:09 2023 +0900
Publish website (#80)
Closes GH-25
---
.github/workflows/doc.yaml | 64 +++++++
.github/workflows/package.yaml | 10 +-
.gitignore | 11 +-
Rakefile | 52 ++++++
benchmark/integer/README.md | 2 +-
dev/prepare-tls.sh | 58 ++++---
dev/release/rat_exclude_files.txt | 1 +
doc/index.html | 26 +++
.../rat_exclude_files.txt => doc/requirements.txt | 9 +-
doc/source/_static/logo-dark.png | Bin 0 -> 22461 bytes
doc/source/_static/logo-light.png | Bin 0 -> 11027 bytes
doc/source/_static/switcher.json | 17 ++
doc/source/client.md | 152 +++++++++++++++++
doc/source/conf.py | 106 ++++++++++++
doc/source/configuration.md | 85 +++++++++
doc/source/index.md | 40 +++++
doc/source/install.md | 91 ++++++++++
doc/source/overview.md | 45 +++++
doc/source/release-notes.md | 26 +++
example/adbc/authenticate-password.c | 189 +++++++++++++++++++++
meson_options.txt => example/adbc/meson.build | 19 ++-
example/flight-sql/authenticate-password.cc | 127 ++++++++++++++
.../Rakefile => example/flight-sql/meson.build | 22 +--
example/flight-sql/query-ad-hoc.cc | 150 ++++++++++++++++
example/flight-sql/query-prepared.cc | 165 ++++++++++++++++++
meson.build | 19 ++-
meson_options.txt | 5 +
{packages => package}/apt/test.sh | 0
.../arrow-flight-sql-postgresql-package-task.rb | 0
{packages => package}/postgresql-15-pgdg/Rakefile | 0
.../apt/debian-bookworm-amd64/Dockerfile | 0
.../apt/ubuntu-jammy-amd64/Dockerfile | 0
.../postgresql-15-pgdg/debian/changelog | 0
.../postgresql-15-pgdg/debian/control | 0
.../postgresql-15-pgdg/debian/copyright | 0
.../postgresql-15-pgdg/debian/rules | 0
36 files changed, 1426 insertions(+), 65 deletions(-)
diff --git a/.github/workflows/doc.yaml b/.github/workflows/doc.yaml
new file mode 100644
index 0000000..ac506ae
--- /dev/null
+++ b/.github/workflows/doc.yaml
@@ -0,0 +1,64 @@
+# 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.
+
+name: Doc
+
+on:
+ pull_request:
+ push:
+
+concurrency:
+ group: ${{ github.head_ref || github.sha }}-${{ github.workflow }}
+ cancel-in-progress: true
+
+permissions:
+ contents: write
+
+jobs:
+ publish:
+ name: Publish
+ timeout-minutes: 10
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: ruby
+ - uses: actions/setup-python@v4
+ with:
+ python-version: 3
+ - name: Install dependencies
+ run: |
+ pip3 install -r doc/requirements.txt
+ - name: Build
+ run: |
+ rake doc:html
+ - uses: actions/upload-artifact@v3
+ with:
+ name: doc
+ path: doc/build
+ - uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+ path: site
+ persist-credentials: true
+ ref: asf-site
+ - name: Publish
+ run: |
+ git config --global user.name 'github-actions[bot]'
+ git config --global user.email
'github-actions[bot]@users.noreply.github.com'
+ rake doc:publish
diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml
index 66f5ceb..027fbd7 100644
--- a/.github/workflows/package.yaml
+++ b/.github/workflows/package.yaml
@@ -171,7 +171,7 @@ jobs:
password: ${{ github.token }}
- name: Build
run: |
- pushd ${BASE_NAME}/packages/${PACKAGE}
+ pushd ${BASE_NAME}/package/${PACKAGE}
if [ "${GITHUB_REF_TYPE}" != "tag" ]; then
rake version:update
fi
@@ -181,7 +181,7 @@ jobs:
- name: Prepare artifacts
run: |
cp -a \
-
${BASE_NAME}/packages/${PACKAGE}/${TASK_NAMESPACE}/repositories/${DISTRIBUTION}
\
+
${BASE_NAME}/package/${PACKAGE}/${TASK_NAMESPACE}/repositories/${DISTRIBUTION} \
./
tar czf ${{ matrix.target }}.tar.gz ${DISTRIBUTION}
- name: Upload artifacts
@@ -200,7 +200,7 @@ jobs:
GH_TOKEN: ${{ github.token }}
- name: Push Docker image
run: |
- pushd ${BASE_NAME}/packages/${PACKAGE}
+ pushd ${BASE_NAME}/package/${PACKAGE}
rake docker:push || :
popd
- name: Test
@@ -210,6 +210,6 @@ jobs:
--rm \
--volume ${PWD}:/host \
${ARCHITECTURE}/${DISTRIBUTION}:${DISTRIBUTION_VERSION} \
- /host/packages/${TASK_NAMESPACE}/test.sh \
- packages/${PACKAGE}/${TASK_NAMESPACE}/repositories
+ /host/package/${TASK_NAMESPACE}/test.sh \
+ package/${PACKAGE}/${TASK_NAMESPACE}/repositories
popd
diff --git a/.gitignore b/.gitignore
index a888e02..b75d024 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,8 +23,9 @@
/dev/release/dist
/dev/release/filtered_rat.txt
/dev/release/rat.xml
-/packages/*/*.tar.gz
-/packages/*/apt/build.sh
-/packages/*/apt/env.sh
-/packages/*/apt/repositories/
-/packages/*/apt/tmp/
+/doc/build/
+/package/*/*.tar.gz
+/package/*/apt/build.sh
+/package/*/apt/env.sh
+/package/*/apt/repositories/
+/package/*/apt/tmp/
diff --git a/Rakefile b/Rakefile
index 699c6b2..e52b1ad 100644
--- a/Rakefile
+++ b/Rakefile
@@ -32,3 +32,55 @@ file archive_name do
end
desc "Create #{archive_name}"
task :dist => archive_name
+
+namespace :doc do
+ desc "Build HTML documentation"
+ task :html do
+ sh("sphinx-build",
+ "-b", "html",
+ "-j", "auto",
+ "doc/source",
+ "doc/build")
+ end
+
+ desc "Publish HTML documentation"
+ task :publish do
+ site = ENV["ASF_SITE"] || "site"
+ asf_yaml = File.expand_path(".asf.yaml")
+ cleaned_doc = File.expand_path("doc/build.clean")
+ index_html = File.expand_path("doc/index.html")
+
+ rm_rf(cleaned_doc)
+ cp_r("doc/build", cleaned_doc)
+ rm_f("#{cleaned_doc}/.buildinfo")
+ rm_rf("#{cleaned_doc}/.doctrees")
+
+ cd("site") do
+ cp(asf_yaml, ".")
+ sh("git", "add", "--force", ".asf.yaml")
+ cp(index_html, ".")
+ sh("git", "add", "--force", "index.html")
+ if ENV["GITHUB_REF_TYPE"] == "tag"
+ new_version = ENV["GITHUB_REF_NAME"].gsub(/-rc\d+\z/, "")
+ else
+ new_version = "devel"
+ end
+ rm_rf(new_version)
+ cp_r(cleaned_doc, new_version)
+ sh("git", "add", "--force", new_version)
+ unless new_version == "devel"
+ rm_rf("current")
+ cp_r(cleaned_doc, "current")
+ sh("git", "add", "--force", "current")
+ end
+ sh("git", "commit", "-m", "Publish", "--allow-empty")
+ unless ENV["GITHUB_EVENT_NAME"] == "pull_request"
+ dry_run = []
+ if ENV["GITHUB_REF_TYPE"] != "tag" and ENV["GITHUB_REF_NAME"] != "main"
+ dry_run << "--dry-run"
+ end
+ sh("git", "push", *dry_run, "origin", "asf-site:asf-site")
+ end
+ end
+ end
+end
diff --git a/benchmark/integer/README.md b/benchmark/integer/README.md
index eb7ee77..6ec23ae 100644
--- a/benchmark/integer/README.md
+++ b/benchmark/integer/README.md
@@ -32,7 +32,7 @@ shared_preload_libraries = 'arrow_flight_sql'
Prepare database:
```bash
-psql postgres -c '\i benchmark/integer/prepare1.sql'
+psql postgres -c '\i benchmark/integer/prepare-1M.sql'
```
It creates `afs_benchmark` database and `data` table in the database.
diff --git a/dev/prepare-tls.sh b/dev/prepare-tls.sh
index c781ffb..e2620ce 100755
--- a/dev/prepare-tls.sh
+++ b/dev/prepare-tls.sh
@@ -30,58 +30,64 @@ server_name=$2
client_name=$3
openssl req \
+ -addext "subjectAltName = DNS:${root_name}" \
+ -keyout root.key \
-new \
-nodes \
- -text \
-out root.csr \
- -keyout root.key \
- -subj "/CN=${root_name}"
+ -subj "/CN=${root_name}" \
+ -text
chmod go-rwx root.key
openssl x509 \
- -req \
- -in root.csr \
- -text \
+ -copy_extensions copy \
-days 3650 \
- -extfile /etc/ssl/openssl.cnf \
-extensions v3_ca \
+ -extfile /etc/ssl/openssl.cnf \
+ -in root.csr \
+ -out root.crt \
+ -req \
-signkey root.key \
- -out root.crt
+ -text
openssl req \
+ -addext "subjectAltName = DNS:${server_name}" \
+ -keyout server.key \
-new \
-nodes \
- -text \
-out server.csr \
- -keyout server.key \
- -subj "/CN=${server_name}"
+ -subj "/CN=${server_name}" \
+ -text
chmod og-rwx server.key
openssl x509 \
- -req \
- -in server.csr \
- -text \
- -days 365 \
-CA root.crt \
- -CAkey root.key \
-CAcreateserial \
- -out server.crt
+ -CAkey root.key \
+ -copy_extensions copy \
+ -days 365 \
+ -in server.csr \
+ -out server.crt \
+ -req \
+ -text
openssl req \
+ -addext "subjectAltName = DNS:${client_name}" \
+ -keyout client.key \
-new \
-nodes \
- -text \
-out client.csr \
- -keyout client.key \
- -subj "/CN=${client_name}"
+ -subj "/CN=${client_name}" \
+ -text
chmod og-rwx client.key
openssl x509 \
- -req \
- -in client.csr \
- -text \
- -days 365 \
-CA root.crt \
- -CAkey root.key \
-CAcreateserial \
- -out client.crt
+ -CAkey root.key \
+ -copy_extensions copy \
+ -days 365 \
+ -in client.csr \
+ -out client.crt \
+ -req \
+ -text
diff --git a/dev/release/rat_exclude_files.txt
b/dev/release/rat_exclude_files.txt
index 2b7dc1d..5d1761d 100644
--- a/dev/release/rat_exclude_files.txt
+++ b/dev/release/rat_exclude_files.txt
@@ -21,3 +21,4 @@ compile_commands.json
dev/release/apache-rat-*.jar
dev/release/filtered_rat.txt
dev/release/rat.xml
+doc/source/_static/switcher.json
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..b1fa92d
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<!--
+ 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.
+-->
+<html>
+ <head>
+ <meta http-equiv="Refresh" content="0; url=current/">
+ </head>
+ <body>
+ </body>
+</html>
diff --git a/dev/release/rat_exclude_files.txt b/doc/requirements.txt
similarity index 83%
copy from dev/release/rat_exclude_files.txt
copy to doc/requirements.txt
index 2b7dc1d..d8f3312 100644
--- a/dev/release/rat_exclude_files.txt
+++ b/doc/requirements.txt
@@ -15,9 +15,6 @@
# specific language governing permissions and limitations
# under the License.
-benchmark/integer/result.csv
-benchmark/integer/result.svg
-compile_commands.json
-dev/release/apache-rat-*.jar
-dev/release/filtered_rat.txt
-dev/release/rat.xml
+myst-parser[linkify]
+pydata_sphinx_theme
+sphinx_inline_tabs
diff --git a/doc/source/_static/logo-dark.png b/doc/source/_static/logo-dark.png
new file mode 100644
index 0000000..1cf65f0
Binary files /dev/null and b/doc/source/_static/logo-dark.png differ
diff --git a/doc/source/_static/logo-light.png
b/doc/source/_static/logo-light.png
new file mode 100644
index 0000000..ccf6c61
Binary files /dev/null and b/doc/source/_static/logo-light.png differ
diff --git a/doc/source/_static/switcher.json b/doc/source/_static/switcher.json
new file mode 100644
index 0000000..5d13223
--- /dev/null
+++ b/doc/source/_static/switcher.json
@@ -0,0 +1,17 @@
+[
+ {
+ "name": "devel",
+ "url": "https://arrow.apache.org/flight-sql-postgresql/devel/";,
+ "version": "devel"
+ },
+ {
+ "name": "current",
+ "url":
"https://arrow.apache.org/flight-sql-postgresql/current/";,
+ "version": "current"
+ },
+ {
+ "name": "0.1.0",
+ "url": "https://arrow.apache.org/flight-sql-postgresql/0.1.0/";,
+ "version": "0.1.0"
+ }
+]
diff --git a/doc/source/client.md b/doc/source/client.md
new file mode 100644
index 0000000..8fb20c9
--- /dev/null
+++ b/doc/source/client.md
@@ -0,0 +1,152 @@
+<!--
+ 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.
+-->
+
+# Client
+
+## How to connect
+
+You must specify PostgreSQL user and PostgreSQL database to connect
+Apache Arrow Flight SQL endpoint.
+
+User name and password must be passed by `Handshake` call. Note that
+basic authentication is only supported for now. mTLS (mutual-TLS)
+isn't implemented yet. If you're interested in mTLS, please see the
+issue for it:
+https://github.com/apache/arrow-flight-sql-postgresql/issues/79
+
+You need to use a header to specify PostgreSQL database. The header
+name for PostgreSQL database is `x-flight-sql-database`.
+
+````{tab} Apache Arrow Flight SQL C++ client
+You need to use
+[`arrow::flight::FlightClient::AuthenticateBasicToken()`][arrow-flight-authenticate-basic]
+for authentication.
+
+You need to add a `x-flight-sql-database` header to
+[`arrow::flight::FlightCallOptions::headers`][arrow-flight-call-options-headers]
+for database.
+
+The following example uses `PGUSER` (fallback to `USER`) and
+`PGPASSWORD` environment variables like
+`libpq`. `AuthenticateBasicToken()` returns Bearer token on
+success. So the example users the returned Bearer token to request
+headers to use following requests.
+
+The following example uses `PGDATABASE` (fallback to `PGUSER`/`USER`)
+environment variable like `libpq`.
+
+```{literalinclude} ../../example/flight-sql/authenticate-password.cc
+:language: c++
+:linenos:
+:tab-width: 4
+:start-after: // Start authentication
+:end-before: // End authentication
+```
+````
+
+````{tab} ADBC Flight SQL driver
+You need to set the
+`username` and `password` options for authentication. See also the
+[Authentication][arrow-adbc-authentication] document.
+
+You need to set the
+`adbc.flight.sql.rpc.call_header.x-flight-sql-database` option for
+database. See also the [Custom Call
+Headers][arrow-adbc-custom-call-headers] document.
+
+```{literalinclude} ../../example/adbc/authenticate-password.c
+:language: c
+:linenos:
+:tab-width: 4
+:start-after: // Start authentication
+:end-before: // End authentication
+```
+````
+
+## How to query
+
+You can use an ad-hoc SQL statement or a prepared SQL statement to
+query.
+
+### Ad-hoc SQL statement
+
+````{tab} Apache Arrow Flight SQL C++ client
+
+You need to use
+[`arrow::flight::sql::FlightSqlClient::Execute()`][arrow-flight-sql-client-execute]
+to execute a query.
+
+You need to use
+[`arrow::flight::sql::FlightSqlClient::DoGet()`][arrow-flight-sql-client-do-get]
+to get results.
+
+```{literalinclude} ../../example/flight-sql/query-ad-hoc.cc
+:language: c++
+:linenos:
+:tab-width: 4
+:start-after: // Start query
+:end-before: // End query
+```
+````
+
+```{tab} ADBC Flight SQL driver
+TODO
+```
+
+### Prepared SQL statement
+
+````{tab} Apache Arrow Flight SQL C++ client
+You need to use
+[`arrow::flight::sql::FlightSqlClient::Prepare()`][arrow-flight-sql-client-prepare]
+to prepare a query.
+
+You need to use
+[`arrow::flight::sql::PreparedStatement::SetParameters()`][arrow-flight-sql-prepared-statement-set-parameters]
+to set parameters.
+
+You need to use
+[`arrow::flight::sql::PreparedStatement::Execute()`][arrow-flight-sql-prepared-statement-execute]
+to execute a prepared statement with parameters.
+
+You need to use
+[`arrow::flight::sql::FlightSqlClient::DoGet()`][arrow-flight-sql-client-do-get]
+to get results.
+
+```{literalinclude} ../../example/flight-sql/query-prepared.cc
+:language: c++
+:linenos:
+:tab-width: 4
+:start-after: // Start query
+:end-before: // End query
+```
+````
+
+```{tab} ADBC Flight SQL driver
+TODO
+```
+
+[arrow-adbc-authentication]:
https://arrow.apache.org/adbc/current/driver/flight_sql.html#authentication
+[arrow-adbc-custom-call-headers]:
https://arrow.apache.org/adbc/current/driver/flight_sql.html#custom-call-headers
+[arrow-flight-authenticate-basic]:
https://arrow.apache.org/docs/cpp/api/flight.html#clients
+[arrow-flight-call-options-headers]:
https://arrow.apache.org/docs/cpp/api/flight.html#_CPPv4N5arrow6flight17FlightCallOptions7headersE
+[arrow-flight-sql-client-do-get]:
https://arrow.apache.org/docs/cpp/api/flightsql.html#_CPPv4N5arrow6flight3sql15FlightSqlClient5DoGetERK17FlightCallOptionsRK6Ticket
+[arrow-flight-sql-client-execute]:
https://arrow.apache.org/docs/cpp/api/flightsql.html#_CPPv4N5arrow6flight3sql15FlightSqlClient7ExecuteERK17FlightCallOptionsRKNSt6stringERK11Transaction
+[arrow-flight-sql-client-prepare]:
https://arrow.apache.org/docs/cpp/api/flightsql.html#_CPPv4N5arrow6flight3sql15FlightSqlClient7PrepareERK17FlightCallOptionsRKNSt6stringERK11Transaction
+[arrow-flight-sql-prepared-statement-execute]:
https://arrow.apache.org/docs/cpp/api/flightsql.html#_CPPv4N5arrow6flight3sql17PreparedStatement7ExecuteERK17FlightCallOptions
+[arrow-flight-sql-prepared-statement-set-parameters]:
https://arrow.apache.org/docs/cpp/api/flightsql.html#_CPPv4N5arrow6flight3sql17PreparedStatement13SetParametersENSt10shared_ptrI11RecordBatchEE
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..7154947
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,106 @@
+# 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.
+# Configuration file for the Sphinx documentation builder.
+
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import pathlib
+import re
+
+# -- Project information -----------------------------------------------------
+#
https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Apache Arrow Flight SQL adapter for PostgreSQL'
+copyright = '2022-2023, Apache Arrow Developers'
+author = 'Apache Arrow Developers'
+version = os.environ.get('VERSION')
+if not version:
+ meson_build_path = pathlib.Path(__file__).parent / '../../meson.build'
+ with open(meson_build_path) as meson_build:
+ version = re.search('version: \'(.+?)\'', meson_build.read())[1]
+ release = version
+
+# -- General configuration ---------------------------------------------------
+#
https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ 'myst_parser',
+ 'sphinx_inline_tabs',
+]
+
+source_suffix = {
+ '.md': 'markdown',
+}
+
+myst_enable_extensions = [
+ 'amsmath',
+ 'attrs_inline',
+ # 'colon_fence',
+ 'deflist',
+ 'dollarmath',
+ 'fieldlist',
+ 'html_admonition',
+ 'html_image',
+ 'linkify',
+ # 'replacements',
+ # 'smartquotes',
+ 'strikethrough',
+ 'substitution',
+ 'tasklist',
+]
+
+templates_path = ['_templates']
+exclude_patterns = [
+ '**/.#*',
+]
+
+
+
+# -- Options for HTML output -------------------------------------------------
+#
https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+ 'logo': {
+ 'alt_text': 'Apache Arrow Flight SQL adapter for PostgreSQL',
+ 'image_light': '_static/logo-light.png',
+ 'image_dark': '_static/logo-dark.png',
+ },
+ 'github_url': 'https://github.com/apache/arrow-flight-sql-postgresql',
+ 'switcher': {
+ 'json_url':
'https://arrow.apache.org/flight-sql-postgresql/devel/_static/switcher.json',
+ 'version_match': release,
+ },
+ 'navbar_center': [
+ ],
+ 'navbar_end': [
+ 'theme-switcher.html',
+ 'navbar-icon-links.html',
+ 'version-switcher.html',
+ ],
+ 'use_edit_page_button': True,
+ 'show_nav_level': 2,
+}
+html_context = {
+ 'github_user': 'apache',
+ 'github_repo': 'arrow-flight-sql-postgresql',
+ 'github_version': 'main',
+ 'doc_path': 'docs/source',
+}
+html_static_path = ['_static']
diff --git a/doc/source/configuration.md b/doc/source/configuration.md
new file mode 100644
index 0000000..ae220b9
--- /dev/null
+++ b/doc/source/configuration.md
@@ -0,0 +1,85 @@
+<!--
+ 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.
+-->
+
+# Configuration
+
+## `shared_preload_libraries`
+
+You must add `arrow_flight_sql` to
+[`shared_preload_libraries`][postgresql-shared-preload-libraries].
+
+You need to restart your PostgreSQL after changing
+`shared_preload_libraries`.
+
+## `arrow_flight_sql.uri`
+
+The endpoint URI for Apache Arrow Flight SQL.
+
+The default is `grpc://127.0.0.1:15432`.
+
+If you want to use TLS to connect the Apache Arrow Flight SQL
+endpoint, you need to do the followings:
+
+1. Use `grpc+tls` schema such as `grpc+tls://127.0.0.1:15432` for
+ `arrow_flight_sql.uri`
+2. Prepare the standard PostgreSQL TLS configurations such as
+ [`ssl`][postgresql-ssl],
+ [`ssl_ca_file`][postgresql-ca-file]. Apache Arrow Flight SQL
+ adapter for PostgreSQL uses the PostgreSQL's TLS configurations. So
+ you don't need to prepare TLS related things only for Apache Arrow
+ Flight SQL for PostgreSQL. See also the PostgreSQL's [Secure TCP/IP
+ Connections with SSL][postgresql-ssl-tcp] documentation.
+
+Note that you also need to setup client side. For example, see the
+following documentations for the C++ implementation of Apache Arrow
+Flight SQL client:
+
+* [Enable TLS][arrow-flight-tls]
+
+```{note}
+mTLS (mutual-TLS) isn't implemented yet. If you're interested in mTLS,
+please see the issue for it:
https://github.com/apache/arrow-flight-sql-postgresql/issues/79
+```
+
+## `arrow_flight_sql.session_timeout`
+
+The maximum session duration in seconds.
+
+The default is 300 seconds.
+
+-1 means no timeout.
+
+If no query is executed during the timeout, the session is closed
+automatically.
+
+## `arrow_flight_sql.max_n_rows_per_record_batch`
+
+The maximum number of rows per record batch.
+
+The default is 1 * 1024 * 1024 rows.
+
+If this value is small, total data exchange time will be slower.
+
+If this value is larger, latency will be larger.
+
+[arrow-flight-tls]: https://arrow.apache.org/docs/cpp/flight.html#enabling-tls
+[postgresql-ca-file]:
https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-SSL-CA-FILE
+[postgresql-shared-preload-libraries]:
https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES
+[postgresql-ssl-tcp]: https://www.postgresql.org/docs/current/ssl-tcp.html
+[postgresql-ssl]:
https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-SSL
diff --git a/doc/source/index.md b/doc/source/index.md
new file mode 100644
index 0000000..fedc6db
--- /dev/null
+++ b/doc/source/index.md
@@ -0,0 +1,40 @@
+<!--
+ 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.
+-->
+
+# Apache Arrow Flight SQL adapter for PostgreSQL
+
+```{toctree}
+:maxdepth: 1
+release-notes.md
+```
+
+```{toctree}
+:maxdepth: 2
+overview.md
+install.md
+configuration.md
+client.md
+```
+
+
+## Indices and tables
+
+* {ref}`genindex`
+* {ref}`modindex`
+* {ref}`search`
diff --git a/doc/source/install.md b/doc/source/install.md
new file mode 100644
index 0000000..4daa30e
--- /dev/null
+++ b/doc/source/install.md
@@ -0,0 +1,91 @@
+<!--
+ 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.
+-->
+
+# Install
+
+## Debian GNU/Linux and Ubuntu
+
+Supported versions:
+
+* Debian GNU/Linux bookworm
+* Ubuntu 22.04 LTS
+
+Enable the PostgreSQL APT repository:
+
+```bash
+sudo apt update
+sudo apt install -y ca-certificates gpg lsb-release wget
+wget -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
+ sudo gpg --no-default-keyring --keyring /usr/share/keyrings/pgdg.gpg
--import -
+(echo "Types: deb"; \
+ echo "URIs: http://apt.postgresql.org/pub/repos/apt";; \
+ echo "Suites: $(lsb_release --codename --short)-pgdg"; \
+ echo "Components: main"; \
+ echo "Signed-By: /usr/share/keyrings/pgdg.gpg") | \
+ sudo tee /etc/apt/sources.list.d/pgdg.sources
+```
+
+Enable the Apache Arrow APT repository:
+
+```bash
+wget https://apache.jfrog.io/artifactory/arrow/$(lsb_release --id --short | tr
'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename
--short).deb
+sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release
--codename --short).deb
+rm apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb
+sudo apt update
+```
+
+Install `postgresql-15-pgdg-apache-arrow-flight-sql`:
+
+```bash
+sudo apt install -y postgresql-15-pgdg-apache-arrow-flight-sql
+```
+
+See {doc}`configuration` how to configure Apache Arrow Flight SQL adapter for
PostgreSQL.
+
+## Source
+
+You need to install the followings before you build Apache Arrow
+Flight SQL adapter for PostgreSQL:
+
+* PostgreSQL: https://www.postgresql.org/download/
+* Apache Arrow C++ with Flight SQL support: https://arrow.apache.org/install/
+* Meson: https://mesonbuild.com/
+* Ninja: https://ninja-build.org/
+* C++ compiler such as `g++` and `clang++
+
+Here are command lines to build Apache Arrow Flight SQL adapter for
+PostgreSQL:
+
+```{note}
+Replase `${version}` with {{ env.config.version }} or define `version`
variable with {{ env.config.version }}.
+```
+
+```bash
+wget
"https://www.apache.org/dyn/closer.lua?action=download&filename=arrow/apache-arrow-flight-sql-postgresql-${version}/apache-arrow-flight-sql-postgresql-${version}.tar.gz";
+tar xfv apache-arrow-flight-sql-postgresql-${version}.tar.gz
+meson setup \
+ --prefix=/usr/local \
+ -Dpostgresql_dir=$(pg_config --bindir)/.. \
+ apache-arrow-flight-sql-postgresql-${version}.build \
+ apache-arrow-flight-sql-postgresql-${version}
+meson compile -C apache-arrow-flight-sql-postgresql-${version}.build
+sudo meson install -C apache-arrow-flight-sql-postgresql-${version}.build
+```
+
+See {doc}`configuration` how to configure Apache Arrow Flight SQL adapter for
PostgreSQL.
diff --git a/doc/source/overview.md b/doc/source/overview.md
new file mode 100644
index 0000000..7d1521d
--- /dev/null
+++ b/doc/source/overview.md
@@ -0,0 +1,45 @@
+<!--
+ 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.
+-->
+
+# Overview
+
+Apache Arrow Flight SQL adapter for PostgreSQL is a PostgreSQL
+extension that adds an [Apache Arrow Flight
+SQL][apache-arrow-flight-sql] endpoint to PostgreSQL.
+
+Apache Arrow Flight SQL is a protocol to use [Apache Arrow
+format][apache-arrow-format] to interact with SQL databases. You can
+use Apache Arrow Flight SQL instead of [the PostgreSQL wire
+protocol][postgresql-protocol] to interact with PostgreSQL by Apache
+Arrow Flight SQL adapter for PostgreSQL.
+
+Apache Arrow format is designed for fast typed table data exchange. If
+you want to get large data by `SELECT` or `INSERT`/`UPDATE` large
+data, Apache Arrow Flight SQL will be faster than the PostgreSQL wire
+protocol.
+
+See also [a simple benchmark result][benchmark-integer] that just
+executes `SELECT * FROM integer_only_table`. It shows that Apache
+Arrow Flight SQL is faster than the PostgreSQL wire protocol when
+result data is large.
+
+[apache-arrow-flight-sql]: https://arrow.apache.org/docs/format/FlightSql.html
+[apache-arrow-format]: https://arrow.apache.org/docs/format/Columnar.html
+[postgresql-protocol]: https://www.postgresql.org/docs/current/protocol.html
+[benchmark-integer]:
https://github.com/apache/arrow-flight-sql-postgresql/tree/main/benchmark/integer
diff --git a/doc/source/release-notes.md b/doc/source/release-notes.md
new file mode 100644
index 0000000..f3159e3
--- /dev/null
+++ b/doc/source/release-notes.md
@@ -0,0 +1,26 @@
+<!--
+ 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.
+-->
+
+# Release notes
+
+## 0.1.0
+
+### Improvements
+
+ * The initial release!
diff --git a/example/adbc/authenticate-password.c
b/example/adbc/authenticate-password.c
new file mode 100644
index 0000000..dc20de2
--- /dev/null
+++ b/example/adbc/authenticate-password.c
@@ -0,0 +1,189 @@
+// 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.
+
+// Start authentication
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <adbc.h>
+
+#ifndef ADBC_ERROR_INIT
+# define ADBC_ERROR_INIT \
+ { \
+ 0 \
+ }
+#endif
+
+static AdbcStatusCode
+database_init(struct AdbcDatabase* database, struct AdbcError* error)
+{
+ AdbcStatusCode code;
+ code = AdbcDatabaseSetOption(database, "driver",
"adbc_driver_flightsql", error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ const char* uri = getenv("PGFLIGHTSQLURI");
+ char uri_buffer[4096];
+ if (!uri)
+ {
+ const char* host = getenv("PGHOST");
+ if (!host)
+ {
+ host = "localhost";
+ }
+ const char* sslmode = getenv("PGSSLMODE");
+ if (sslmode &&
+ ((strcmp(sslmode, "require") == 0) || (strcmp(sslmode,
"verify-ca") == 0) ||
+ (strcmp(sslmode, "verify-full") == 0)))
+ {
+ snprintf(uri_buffer, sizeof(uri_buffer),
"grpc+tls://%s:15432", host);
+ }
+ else
+ {
+ snprintf(uri_buffer, sizeof(uri_buffer),
"grpc://%s:15432", host);
+ }
+ uri = uri_buffer;
+ }
+ code = AdbcDatabaseSetOption(database, "uri", uri, error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ const char* sslrootcert = getenv("PGSSLROOTCERT");
+ char sslrootcert_buffer[4096];
+ if (!sslrootcert)
+ {
+ const char* home = getenv("HOME");
+ if (home)
+ {
+ snprintf(sslrootcert_buffer,
+ sizeof(sslrootcert_buffer),
+ "%s/.postgresql/root.crt",
+ home);
+ sslrootcert = sslrootcert_buffer;
+ }
+ }
+ if (sslrootcert)
+ {
+ FILE* input = fopen(sslrootcert, "r");
+ if (input)
+ {
+ char sslrootcert_data[40960];
+ size_t read_size =
+ fread(sslrootcert_data, 1,
sizeof(sslrootcert_data), input);
+ fclose(input);
+ if (read_size < sizeof(sslrootcert_data))
+ {
+ code =
+ AdbcDatabaseSetOption(database,
+
"adbc.flight.sql.client_option.tls_root_certs",
+ sslrootcert_data,
+ error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ }
+ }
+ }
+ const char* user = getenv("PGUSER");
+ if (!user)
+ {
+ user = getenv("USER");
+ }
+ if (user)
+ {
+ code = AdbcDatabaseSetOption(database, "username", user, error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ }
+ const char* password = getenv("PGPASSWORD");
+ if (password)
+ {
+ code = AdbcDatabaseSetOption(database, "password", password,
error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ }
+ const char* database_name = getenv("PGDATABASE");
+ if (!database_name)
+ {
+ database_name = user;
+ }
+ if (database_name)
+ {
+ code =
+ AdbcDatabaseSetOption(database,
+
"adbc.flight.sql.rpc.call_header.x-flight-sql-database",
+ database_name,
+ error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ }
+ return AdbcDatabaseInit(database, error);
+}
+
+static AdbcStatusCode
+run(struct AdbcError* error)
+{
+ AdbcStatusCode code;
+ struct AdbcDatabase database = {0};
+ code = AdbcDatabaseNew(&database, error);
+ if (code != ADBC_STATUS_OK)
+ {
+ return code;
+ }
+ code = database_init(&database, error);
+ if (code == ADBC_STATUS_OK)
+ {
+ struct AdbcConnection connection = {0};
+ code = AdbcConnectionNew(&connection, error);
+ if (code == ADBC_STATUS_OK)
+ {
+ code = AdbcConnectionInit(&connection, &database,
error);
+ AdbcConnectionRelease(&connection, error);
+ }
+ }
+ AdbcDatabaseRelease(&database, error);
+ return code;
+}
+
+int
+main(int argc, char** argv)
+{
+ struct AdbcError error = ADBC_ERROR_INIT;
+ AdbcStatusCode code = run(&error);
+ if (code == ADBC_STATUS_OK)
+ {
+ printf("Authenticated!\n");
+ return EXIT_SUCCESS;
+ }
+ else
+ {
+ fprintf(stderr, "%s\n", error.message);
+ error.release(&error);
+ return EXIT_FAILURE;
+ }
+}
+// End authentication
diff --git a/meson_options.txt b/example/adbc/meson.build
similarity index 70%
copy from meson_options.txt
copy to example/adbc/meson.build
index fd63af1..f3b6dc0 100644
--- a/meson_options.txt
+++ b/example/adbc/meson.build
@@ -15,12 +15,15 @@
# specific language governing permissions and limitations
# under the License.
-option('benchmark',
- type: 'boolean',
- value: false,
- description: 'Build benchmark programs')
+adbc_driver_manager = dependency(
+ 'AdbcDriverManager',
+ method: 'cmake',
+ modules: ['AdbcDriverManager::adbc_driver_manager_shared'],
+ required: false
+)
-option('postgresql_dir',
- type: 'string',
- value: '',
- description: 'PostgreSQL binary directory')
+if adbc_driver_manager.found()
+ executable('authenticate-password',
+ 'authenticate-password.c',
+ dependencies: [adbc_driver_manager])
+endif
diff --git a/example/flight-sql/authenticate-password.cc
b/example/flight-sql/authenticate-password.cc
new file mode 100644
index 0000000..c39b533
--- /dev/null
+++ b/example/flight-sql/authenticate-password.cc
@@ -0,0 +1,127 @@
+// 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.
+
+// Start authentication
+#include <cstdlib>
+#include <fstream>
+#include <iostream>
+
+#include <arrow/flight/sql/client.h>
+
+namespace {
+std::string
+getenv(const char* name)
+{
+ auto value = std::getenv(name);
+ if (value)
+ {
+ return std::string(value);
+ }
+ else
+ {
+ return std::string("");
+ }
+}
+
+arrow::Status
+run()
+{
+ auto uri = getenv("PGFLIGHTSQLURI");
+ if (uri.empty())
+ {
+ auto host = getenv("PGHOST");
+ if (host.empty())
+ {
+ host = "localhost";
+ }
+ auto sslmode = getenv("PGSSLMODE");
+ if (sslmode == "require" || sslmode == "verify-ca" || sslmode
== "verify-full")
+ {
+ uri = std::string("grpc+tls://") + host + ":15432";
+ }
+ else
+ {
+ uri = std::string("grpc://") + host + ":15432";
+ }
+ }
+ ARROW_ASSIGN_OR_RAISE(auto location,
arrow::flight::Location::Parse(uri));
+ arrow::flight::FlightClientOptions client_options;
+ auto sslrootcert = getenv("PGSSLROOTCERT");
+ if (sslrootcert.empty())
+ {
+ auto home = getenv("HOME");
+ if (!home.empty())
+ {
+ sslrootcert = home + "/.postgresql/root.crt";
+ }
+ }
+ if (!sslrootcert.empty())
+ {
+ std::ifstream input(sslrootcert);
+ if (input)
+ {
+ client_options.tls_root_certs =
+
std::string(std::istreambuf_iterator<char>{input}, {});
+ }
+ }
+ ARROW_ASSIGN_OR_RAISE(auto client,
+ arrow::flight::FlightClient::Connect(location,
client_options));
+ auto user = getenv("PGUSER");
+ if (user.empty())
+ {
+ user = getenv("USER");
+ }
+ auto password = getenv("PGPASSWORD");
+ if (password.empty())
+ {
+ password = "";
+ }
+ arrow::flight::FlightCallOptions call_options;
+ auto database = getenv("PGDATABASE");
+ if (database.empty())
+ {
+ database = user;
+ }
+ call_options.headers.emplace_back("x-flight-sql-database", database);
+ ARROW_ASSIGN_OR_RAISE(auto bearer_token,
+ client->AuthenticateBasicToken(call_options,
user, password));
+ const auto& bearer_name = bearer_token.first;
+ const auto& bearer_value = bearer_token.second;
+ if (!bearer_name.empty() && !bearer_value.empty())
+ {
+ call_options.headers.emplace_back(bearer_name, bearer_value);
+ }
+ return client->Close();
+}
+}; // namespace
+
+int
+main(int argc, char** argv)
+{
+ auto status = run();
+ if (status.ok())
+ {
+ std::cout << "Authenticated!" << std::endl;
+ return EXIT_SUCCESS;
+ }
+ else
+ {
+ std::cerr << status.ToString() << std::endl;
+ return EXIT_FAILURE;
+ }
+}
+// End authentication
diff --git a/packages/postgresql-15-pgdg/Rakefile
b/example/flight-sql/meson.build
similarity index 70%
copy from packages/postgresql-15-pgdg/Rakefile
copy to example/flight-sql/meson.build
index e80f40f..cf314ce 100644
--- a/packages/postgresql-15-pgdg/Rakefile
+++ b/example/flight-sql/meson.build
@@ -1,5 +1,3 @@
-# -*- ruby -*-
-#
# 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
@@ -17,16 +15,14 @@
# specific language governing permissions and limitations
# under the License.
-require_relative "../arrow-flight-sql-postgresql-package-task"
-
-class PostgreSQL15PGDGPackageTask < ArrowFlightSQLPostgreSQLPackageTask
- def initialize
- super("postgresql-15-pgdg-apache-arrow-flight-sql")
- end
+executable('authenticate-password',
+ 'authenticate-password.cc',
+ dependencies: [arrow_flight_sql])
- def enable_yum?
- false
- end
-end
+executable('query-ad-hoc',
+ 'query-ad-hoc.cc',
+ dependencies: [arrow_flight_sql])
-PostgreSQL15PGDGPackageTask.new.define
+executable('query-prepared',
+ 'query-prepared.cc',
+ dependencies: [arrow_flight_sql])
diff --git a/example/flight-sql/query-ad-hoc.cc
b/example/flight-sql/query-ad-hoc.cc
new file mode 100644
index 0000000..1eef82e
--- /dev/null
+++ b/example/flight-sql/query-ad-hoc.cc
@@ -0,0 +1,150 @@
+// 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.
+
+#include <cstdlib>
+#include <fstream>
+#include <iostream>
+
+#include <arrow/flight/sql/client.h>
+
+namespace {
+std::string
+getenv(const char* name)
+{
+ auto value = std::getenv(name);
+ if (value)
+ {
+ return std::string(value);
+ }
+ else
+ {
+ return std::string("");
+ }
+}
+
+arrow::Result<std::unique_ptr<arrow::flight::sql::FlightSqlClient>>
+connect(arrow::flight::FlightCallOptions& call_options)
+{
+ auto uri = getenv("PGFLIGHTSQLURI");
+ if (uri.empty())
+ {
+ auto host = getenv("PGHOST");
+ if (host.empty())
+ {
+ host = "localhost";
+ }
+ auto sslmode = getenv("PGSSLMODE");
+ if (sslmode == "require" || sslmode == "verify-ca" || sslmode
== "verify-full")
+ {
+ uri = std::string("grpc+tls://") + host + ":15432";
+ }
+ else
+ {
+ uri = std::string("grpc://") + host + ":15432";
+ }
+ }
+ ARROW_ASSIGN_OR_RAISE(auto location,
arrow::flight::Location::Parse(uri));
+ arrow::flight::FlightClientOptions client_options;
+ auto sslrootcert = getenv("PGSSLROOTCERT");
+ if (sslrootcert.empty())
+ {
+ auto home = getenv("HOME");
+ if (!home.empty())
+ {
+ sslrootcert = home + "/.postgresql/root.crt";
+ }
+ }
+ if (!sslrootcert.empty())
+ {
+ std::ifstream input(sslrootcert);
+ if (input)
+ {
+ client_options.tls_root_certs =
+
std::string(std::istreambuf_iterator<char>{input}, {});
+ }
+ }
+ ARROW_ASSIGN_OR_RAISE(auto client,
+ arrow::flight::FlightClient::Connect(location,
client_options));
+ auto user = getenv("PGUSER");
+ if (user.empty())
+ {
+ user = getenv("USER");
+ }
+ auto password = getenv("PGPASSWORD");
+ if (password.empty())
+ {
+ password = "";
+ }
+ auto database = getenv("PGDATABASE");
+ if (database.empty())
+ {
+ database = user;
+ }
+ call_options.headers.emplace_back("x-flight-sql-database", database);
+ ARROW_ASSIGN_OR_RAISE(auto bearer_token,
+ client->AuthenticateBasicToken(call_options,
user, password));
+ const auto& bearer_name = bearer_token.first;
+ const auto& bearer_value = bearer_token.second;
+ if (!bearer_name.empty() && !bearer_value.empty())
+ {
+ call_options.headers.emplace_back(bearer_name, bearer_value);
+ }
+ return
std::make_unique<arrow::flight::sql::FlightSqlClient>(std::move(client));
+}
+
+// Start query
+arrow::Status
+run()
+{
+ arrow::flight::FlightCallOptions call_options;
+ ARROW_ASSIGN_OR_RAISE(auto sql_client, connect(call_options));
+ ARROW_ASSIGN_OR_RAISE(
+ auto info,
+ sql_client->Execute(call_options, "SELECT 1 AS number, 'hello'
AS string"));
+ for (const auto& endpoint : info->endpoints())
+ {
+ ARROW_ASSIGN_OR_RAISE(auto reader,
+ sql_client->DoGet(call_options,
endpoint.ticket));
+ while (true)
+ {
+ ARROW_ASSIGN_OR_RAISE(auto chunk, reader->Next());
+ if (!chunk.data)
+ {
+ break;
+ }
+ std::cout << chunk.data->ToString() << std::endl;
+ }
+ }
+ return sql_client->Close();
+}
+// End query
+}; // namespace
+
+int
+main(int argc, char** argv)
+{
+ auto status = run();
+ if (status.ok())
+ {
+ return EXIT_SUCCESS;
+ }
+ else
+ {
+ std::cerr << status.ToString() << std::endl;
+ return EXIT_FAILURE;
+ }
+}
diff --git a/example/flight-sql/query-prepared.cc
b/example/flight-sql/query-prepared.cc
new file mode 100644
index 0000000..621b650
--- /dev/null
+++ b/example/flight-sql/query-prepared.cc
@@ -0,0 +1,165 @@
+// 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.
+
+#include <cstdlib>
+#include <fstream>
+#include <iostream>
+
+#include <arrow/builder.h>
+#include <arrow/flight/sql/client.h>
+#include <arrow/table_builder.h>
+
+namespace {
+std::string
+getenv(const char* name)
+{
+ auto value = std::getenv(name);
+ if (value)
+ {
+ return std::string(value);
+ }
+ else
+ {
+ return std::string("");
+ }
+}
+
+arrow::Result<std::unique_ptr<arrow::flight::sql::FlightSqlClient>>
+connect(arrow::flight::FlightCallOptions& call_options)
+{
+ auto uri = getenv("PGFLIGHTSQLURI");
+ if (uri.empty())
+ {
+ auto host = getenv("PGHOST");
+ if (host.empty())
+ {
+ host = "localhost";
+ }
+ auto sslmode = getenv("PGSSLMODE");
+ if (sslmode == "require" || sslmode == "verify-ca" || sslmode
== "verify-full")
+ {
+ uri = std::string("grpc+tls://") + host + ":15432";
+ }
+ else
+ {
+ uri = std::string("grpc://") + host + ":15432";
+ }
+ }
+ ARROW_ASSIGN_OR_RAISE(auto location,
arrow::flight::Location::Parse(uri));
+ arrow::flight::FlightClientOptions client_options;
+ auto sslrootcert = getenv("PGSSLROOTCERT");
+ if (sslrootcert.empty())
+ {
+ auto home = getenv("HOME");
+ if (!home.empty())
+ {
+ sslrootcert = home + "/.postgresql/root.crt";
+ }
+ }
+ if (!sslrootcert.empty())
+ {
+ std::ifstream input(sslrootcert);
+ if (input)
+ {
+ client_options.tls_root_certs =
+
std::string(std::istreambuf_iterator<char>{input}, {});
+ }
+ }
+ ARROW_ASSIGN_OR_RAISE(auto client,
+ arrow::flight::FlightClient::Connect(location,
client_options));
+ auto user = getenv("PGUSER");
+ if (user.empty())
+ {
+ user = getenv("USER");
+ }
+ auto password = getenv("PGPASSWORD");
+ if (password.empty())
+ {
+ password = "";
+ }
+ auto database = getenv("PGDATABASE");
+ if (database.empty())
+ {
+ database = user;
+ }
+ call_options.headers.emplace_back("x-flight-sql-database", database);
+ ARROW_ASSIGN_OR_RAISE(auto bearer_token,
+ client->AuthenticateBasicToken(call_options,
user, password));
+ const auto& bearer_name = bearer_token.first;
+ const auto& bearer_value = bearer_token.second;
+ if (!bearer_name.empty() && !bearer_value.empty())
+ {
+ call_options.headers.emplace_back(bearer_name, bearer_value);
+ }
+ return
std::make_unique<arrow::flight::sql::FlightSqlClient>(std::move(client));
+}
+
+// Start query
+arrow::Status
+run()
+{
+ arrow::flight::FlightCallOptions call_options;
+ ARROW_ASSIGN_OR_RAISE(auto sql_client, connect(call_options));
+ ARROW_ASSIGN_OR_RAISE(auto statement,
+ sql_client->Prepare(call_options,
+ "SELECT i "
+ " FROM generate_series(1,
100) "
+ " AS series (i) "
+ " WHERE i < $1"));
+ auto schema = arrow::schema({arrow::field("i", arrow::int32())});
+ ARROW_ASSIGN_OR_RAISE(
+ auto record_batch_builder,
+ arrow::RecordBatchBuilder::Make(schema,
arrow::default_memory_pool()));
+ auto i_builder =
record_batch_builder->GetFieldAs<arrow::Int32Builder>(0);
+ ARROW_RETURN_NOT_OK(i_builder->Append(10));
+ ARROW_ASSIGN_OR_RAISE(auto record_batch, record_batch_builder->Flush());
+ ARROW_RETURN_NOT_OK(statement->SetParameters(record_batch));
+ ARROW_ASSIGN_OR_RAISE(auto info, statement->Execute());
+ for (const auto& endpoint : info->endpoints())
+ {
+ ARROW_ASSIGN_OR_RAISE(auto reader,
+ sql_client->DoGet(call_options,
endpoint.ticket));
+ while (true)
+ {
+ ARROW_ASSIGN_OR_RAISE(auto chunk, reader->Next());
+ if (!chunk.data)
+ {
+ break;
+ }
+ std::cout << chunk.data->ToString() << std::endl;
+ }
+ }
+ ARROW_RETURN_NOT_OK(statement->Close());
+ return sql_client->Close();
+}
+// End query
+}; // namespace
+
+int
+main(int argc, char** argv)
+{
+ auto status = run();
+ if (status.ok())
+ {
+ return EXIT_SUCCESS;
+ }
+ else
+ {
+ std::cerr << status.ToString() << std::endl;
+ return EXIT_FAILURE;
+ }
+}
diff --git a/meson.build b/meson.build
index da8a4fa..5110ad8 100644
--- a/meson.build
+++ b/meson.build
@@ -43,6 +43,18 @@ arrow_flight_sql = dependency(
method: 'cmake',
modules: ['ArrowFlightSql::arrow_flight_sql_shared']
)
+if arrow_flight_sql.version().version_compare('<14.0.0')
+ # Workaround for a bug that ArrowFlightSQL::arrow_flight_sql_shared
+ # doesn't depend on ArrowFlight::arrow_flight_shared.
+ arrow_flight = dependency(
+ 'ArrowFlight',
+ method: 'cmake',
+ modules: ['ArrowFlight::arrow_flight_shared']
+ )
+ arrow_flight_sql = declare_dependency(
+ dependencies: [arrow_flight_sql, arrow_flight],
+ )
+endif
postgresql = declare_dependency(
compile_args: run_command(pg_config,
'--cflags_sl',
@@ -52,7 +64,7 @@ postgresql = declare_dependency(
check: true).stdout().strip(),
)
install_dir = run_command(pg_config, '--pkglibdir', check:
true).stdout().strip()
-arrow_flight_sql = shared_module(
+afs = shared_module(
'arrow_flight_sql',
'src/afs.cc',
dependencies: [arrow_flight_sql, postgresql],
@@ -71,3 +83,8 @@ install_data(
if get_option('benchmark')
subdir('benchmark/integer')
endif
+
+if get_option('example')
+ subdir('example/adbc')
+ subdir('example/flight-sql')
+endif
diff --git a/meson_options.txt b/meson_options.txt
index fd63af1..03af785 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -20,6 +20,11 @@ option('benchmark',
value: false,
description: 'Build benchmark programs')
+option('example',
+ type: 'boolean',
+ value: false,
+ description: 'Build example programs')
+
option('postgresql_dir',
type: 'string',
value: '',
diff --git a/packages/apt/test.sh b/package/apt/test.sh
similarity index 100%
rename from packages/apt/test.sh
rename to package/apt/test.sh
diff --git a/packages/arrow-flight-sql-postgresql-package-task.rb
b/package/arrow-flight-sql-postgresql-package-task.rb
similarity index 100%
rename from packages/arrow-flight-sql-postgresql-package-task.rb
rename to package/arrow-flight-sql-postgresql-package-task.rb
diff --git a/packages/postgresql-15-pgdg/Rakefile
b/package/postgresql-15-pgdg/Rakefile
similarity index 100%
rename from packages/postgresql-15-pgdg/Rakefile
rename to package/postgresql-15-pgdg/Rakefile
diff --git a/packages/postgresql-15-pgdg/apt/debian-bookworm-amd64/Dockerfile
b/package/postgresql-15-pgdg/apt/debian-bookworm-amd64/Dockerfile
similarity index 100%
rename from packages/postgresql-15-pgdg/apt/debian-bookworm-amd64/Dockerfile
rename to package/postgresql-15-pgdg/apt/debian-bookworm-amd64/Dockerfile
diff --git a/packages/postgresql-15-pgdg/apt/ubuntu-jammy-amd64/Dockerfile
b/package/postgresql-15-pgdg/apt/ubuntu-jammy-amd64/Dockerfile
similarity index 100%
rename from packages/postgresql-15-pgdg/apt/ubuntu-jammy-amd64/Dockerfile
rename to package/postgresql-15-pgdg/apt/ubuntu-jammy-amd64/Dockerfile
diff --git a/packages/postgresql-15-pgdg/debian/changelog
b/package/postgresql-15-pgdg/debian/changelog
similarity index 100%
rename from packages/postgresql-15-pgdg/debian/changelog
rename to package/postgresql-15-pgdg/debian/changelog
diff --git a/packages/postgresql-15-pgdg/debian/control
b/package/postgresql-15-pgdg/debian/control
similarity index 100%
rename from packages/postgresql-15-pgdg/debian/control
rename to package/postgresql-15-pgdg/debian/control
diff --git a/packages/postgresql-15-pgdg/debian/copyright
b/package/postgresql-15-pgdg/debian/copyright
similarity index 100%
rename from packages/postgresql-15-pgdg/debian/copyright
rename to package/postgresql-15-pgdg/debian/copyright
diff --git a/packages/postgresql-15-pgdg/debian/rules
b/package/postgresql-15-pgdg/debian/rules
similarity index 100%
rename from packages/postgresql-15-pgdg/debian/rules
rename to package/postgresql-15-pgdg/debian/rules
