You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2022/11/10 18:48:27 UTC
[arrow-adbc] branch main updated: docs: add docs skeleton (#172)
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-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new f93cc2b docs: add docs skeleton (#172)
f93cc2b is described below
commit f93cc2b16d7c7ce58f9f2af64e77851f7b088130
Author: David Li <li...@gmail.com>
AuthorDate: Thu Nov 10 13:48:21 2022 -0500
docs: add docs skeleton (#172)
---
.github/workflows/cpp.yml | 6 +-
CONTRIBUTING.md | 32 ++++
c/apidoc/Doxyfile | 8 +-
c/driver_manager/adbc_driver_manager.h | 2 +-
.../__init__.py => ci/conda_env_docs.txt | 31 ++--
.../__init__.py => ci/scripts/docs_build.sh | 37 ++---
ci/scripts/python_wheel_upload.sh | 18 ++-
docker-compose.yml | 12 +-
docs/Makefile | 20 +++
docs/make.bat | 35 +++++
docs/source/_static/logo.png | Bin 0 -> 236739 bytes
docs/source/conf.py | 82 ++++++++++
docs/source/contributing.rst | 25 ++++
docs/source/cpp/api/adbc.rst | 22 +++
docs/source/cpp/api/adbc_driver_manager.rst | 22 +++
docs/source/cpp/api/index.rst | 26 ++++
docs/source/cpp/concurrency.rst | 90 +++++++++++
docs/source/cpp/driver/flight_sql.rst | 165 +++++++++++++++++++++
docs/source/cpp/driver/index.rst | 29 ++++
docs/source/cpp/driver/postgres.rst | 63 ++++++++
docs/source/cpp/driver_manager.rst | 61 ++++++++
docs/source/cpp/index.rst | 29 ++++
docs/source/cpp/install.rst | 101 +++++++++++++
docs/source/format/comparison.rst | 71 +++++++++
docs/source/format/specification.rst | 96 ++++++++++++
docs/source/format/versioning.rst | 70 +++++++++
docs/source/index.rst | 66 +++++++++
docs/source/java/index.rst | 25 ++++
docs/source/nightly.rst | 67 +++++++++
docs/source/python/api/adbc_driver_manager.rst | 135 +++++++++++++++++
docs/source/python/api/index.rst | 25 ++++
docs/source/python/index.rst | 27 ++++
.../adbc_driver_manager/__init__.py | 38 ++++-
.../adbc_driver_manager/_lib.pyx | 24 +--
.../adbc_driver_manager/dbapi.py | 57 ++++---
35 files changed, 1533 insertions(+), 84 deletions(-)
diff --git a/.github/workflows/cpp.yml b/.github/workflows/cpp.yml
index 25f32e1..3681dc8 100644
--- a/.github/workflows/cpp.yml
+++ b/.github/workflows/cpp.yml
@@ -79,6 +79,7 @@ jobs:
run: |
mamba install \
--file ci/conda_env_cpp.txt \
+ --file ci/conda_env_docs.txt \
--file ci/conda_env_glib.txt \
--file ci/conda_env_python.txt
- name: Build/Test SQLite3 Driver
@@ -194,7 +195,10 @@ jobs:
bundle exec rake build
gem install pkg/*.gem
popd
-
+ - name: Build Docs
+ shell: bash -l {0}
+ run: |
+ ./ci/scripts/docs_build.sh "$(pwd)"
cpp-conda-windows:
name: "Conda/${{ matrix.os }}"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6b809de..164c433 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -85,6 +85,38 @@ for details.
[cmake-prefix-path]: https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html
[gtest]: https://github.com/google/googletest/
+### Documentation
+
+The documentation uses the [Sphinx][sphinx] documentation generator.
+
+A list of dependencies for Conda (conda-forge) is included, and can be
+used as follows:
+
+```shell
+$ conda create -n adbc -c conda-forge --file ci/conda_env_docs.txt
+$ conda activate adbc
+```
+
+To build the HTML documentation:
+
+```shell
+$ pushd c/apidoc
+$ doxygen
+$ popd
+
+# Optionally: to also build the Python documentation
+$ pushd python/adbc_driver_manager
+$ pip install -e .[test]
+$ popd
+
+$ cd docs
+$ make html
+```
+
+The output can be found in `build/`.
+
+[sphinx]: https://www.sphinx-doc.org/en/master/
+
### GLib
The GLib bindings use the [Meson][meson] build system.
diff --git a/c/apidoc/Doxyfile b/c/apidoc/Doxyfile
index 02f52fd..607579f 100644
--- a/c/apidoc/Doxyfile
+++ b/c/apidoc/Doxyfile
@@ -874,7 +874,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = ../../adbc.h ../../README.md
+INPUT = ../../adbc.h ../../README.md ../../c/driver_manager/adbc_driver_manager.h
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2213,7 +2213,7 @@ ENABLE_PREPROCESSING = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-MACRO_EXPANSION = NO
+MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2221,7 +2221,7 @@ MACRO_EXPANSION = NO
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-EXPAND_ONLY_PREDEF = NO
+EXPAND_ONLY_PREDEF = YES
# If the SEARCH_INCLUDES tag is set to YES, the include files in the
# INCLUDE_PATH will be searched if a #include is found.
@@ -2253,7 +2253,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-PREDEFINED =
+PREDEFINED = ADBC_EXPORT=
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/c/driver_manager/adbc_driver_manager.h b/c/driver_manager/adbc_driver_manager.h
index 7caf56d..69b767a 100644
--- a/c/driver_manager/adbc_driver_manager.h
+++ b/c/driver_manager/adbc_driver_manager.h
@@ -52,7 +52,7 @@ AdbcStatusCode AdbcLoadDriver(const char* driver_name, const char* entrypoint,
/// of functionality for this to be possible, however, and some
/// functions must be implemented by the driver.
///
-/// \param[in] entrypoint The entrypoint to call.
+/// \param[in] init_func The entrypoint to call.
/// \param[in] version The ADBC revision to attempt to initialize.
/// \param[out] driver The table of function pointers to initialize.
/// \param[out] error An optional location to return an error message
diff --git a/python/adbc_driver_manager/adbc_driver_manager/__init__.py b/ci/conda_env_docs.txt
similarity index 61%
copy from python/adbc_driver_manager/adbc_driver_manager/__init__.py
copy to ci/conda_env_docs.txt
index 2c808f5..607aaf2 100644
--- a/python/adbc_driver_manager/adbc_driver_manager/__init__.py
+++ b/ci/conda_env_docs.txt
@@ -15,25 +15,12 @@
# specific language governing permissions and limitations
# under the License.
-from ._lib import ( # noqa: F401
- INGEST_OPTION_TARGET_TABLE,
- AdbcConnection,
- AdbcDatabase,
- AdbcInfoCode,
- AdbcStatement,
- AdbcStatusCode,
- ArrowArrayHandle,
- ArrowArrayStreamHandle,
- ArrowSchemaHandle,
- DatabaseError,
- DataError,
- Error,
- GetObjectsDepth,
- IntegrityError,
- InterfaceError,
- InternalError,
- NotSupportedError,
- OperationalError,
- ProgrammingError,
-)
-from ._version import version as __version__ # noqa: F401
+breathe
+doxygen
+make
+numpydoc
+pydata-sphinx-theme>=0.8.0
+sphinx
+sphinx-book-theme>=0.3.0
+sphinx-copybutton
+sphinx-design
diff --git a/python/adbc_driver_manager/adbc_driver_manager/__init__.py b/ci/scripts/docs_build.sh
old mode 100644
new mode 100755
similarity index 61%
copy from python/adbc_driver_manager/adbc_driver_manager/__init__.py
copy to ci/scripts/docs_build.sh
index 2c808f5..58cb6c1
--- a/python/adbc_driver_manager/adbc_driver_manager/__init__.py
+++ b/ci/scripts/docs_build.sh
@@ -1,3 +1,4 @@
+#!/usr/bin/env bash
# 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
@@ -15,25 +16,17 @@
# specific language governing permissions and limitations
# under the License.
-from ._lib import ( # noqa: F401
- INGEST_OPTION_TARGET_TABLE,
- AdbcConnection,
- AdbcDatabase,
- AdbcInfoCode,
- AdbcStatement,
- AdbcStatusCode,
- ArrowArrayHandle,
- ArrowArrayStreamHandle,
- ArrowSchemaHandle,
- DatabaseError,
- DataError,
- Error,
- GetObjectsDepth,
- IntegrityError,
- InterfaceError,
- InternalError,
- NotSupportedError,
- OperationalError,
- ProgrammingError,
-)
-from ._version import version as __version__ # noqa: F401
+set -ex
+
+main() {
+ local -r source_dir="${1}"
+
+ pushd "$source_dir/c/apidoc"
+ doxygen
+ popd
+
+ pushd "$source_dir/docs"
+ make html
+}
+
+main "$@"
diff --git a/ci/scripts/python_wheel_upload.sh b/ci/scripts/python_wheel_upload.sh
index 8b62aed..5fdc012 100755
--- a/ci/scripts/python_wheel_upload.sh
+++ b/ci/scripts/python_wheel_upload.sh
@@ -1,4 +1,20 @@
-#!/bin/bash
+#!/usr/bin/env bash
+# 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.
main() {
touch curl_output.txt
diff --git a/docker-compose.yml b/docker-compose.yml
index 343f689..ce16eac 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -17,13 +17,19 @@
version: '3.5'
-x-hierarchy:
- - python-wheel-manylinux-2014
-
services:
# These reuse Arrow's images for simplicity. You won't be able to
# build the image from here.
+ ############################ Documentation###################################
+
+ docs:
+ image: condaforge/mambaforge:latest
+ volumes:
+ - .:/adbc:delegated
+ command: |
+ /bin/bash -c 'source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && /adbc/ci/scripts/docs_build.sh /adbc'
+
############################ Java JARs ######################################
java-jars:
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d0c3cbf
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..747ffb7
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
new file mode 100644
index 0000000..1fd89d9
Binary files /dev/null and b/docs/source/_static/logo.png differ
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..10457c0
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,82 @@
+# 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.
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Apache Arrow ADBC"
+copyright = "2022, Apache Arrow Developers"
+author = "the Apache Arrow Developers"
+release = "1.0.0a0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+exclude_patterns = []
+extensions = [
+ "breathe",
+ "numpydoc",
+ "sphinx.ext.autodoc",
+ "sphinx.ext.intersphinx",
+ "sphinx_copybutton",
+ "sphinx_design",
+]
+templates_path = ["_templates"]
+
+# -- Options for autodoc ----------------------------------------------------
+
+try:
+ import adbc_driver_manager
+ import adbc_driver_manager.dbapi # noqa: F401
+except ImportError:
+ autodoc_mock_imports = ["adbc_driver_manager"]
+
+autodoc_default_options = {
+ "show-inheritance": True,
+}
+
+# -- Options for Breathe -----------------------------------------------------
+
+breathe_default_project = "adbc"
+breathe_projects = {
+ "adbc": "../../c/apidoc/xml/",
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_logo = "_static/logo.png"
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+ "path_to_docs": "docs",
+ "repository_branch": "main",
+ "repository_url": "https://github.com/apache/arrow-adbc",
+ "use_edit_page_button": True,
+ "use_issues_button": True,
+ "use_repository_button": True,
+}
+html_static_path = ["_static"]
+
+# -- Options for Intersphinx -------------------------------------------------
+
+intersphinx_mapping = {
+ "arrow": ("https://arrow.apache.org/docs/", None),
+}
+
+# -- Options for numpydoc ----------------------------------------------------
+
+numpydoc_class_members_toctree = False
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
new file mode 100644
index 0000000..5458239
--- /dev/null
+++ b/docs/source/contributing.rst
@@ -0,0 +1,25 @@
+.. 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.
+
+============
+Contributing
+============
+
+To contribute, see CONTRIBUTING.md_ in the repository.
+
+.. _CONTRIBUTING.md:
+ https://github.com/apache/arrow-adbc/blob/main/CONTRIBUTING.md
diff --git a/docs/source/cpp/api/adbc.rst b/docs/source/cpp/api/adbc.rst
new file mode 100644
index 0000000..7653907
--- /dev/null
+++ b/docs/source/cpp/api/adbc.rst
@@ -0,0 +1,22 @@
+.. 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.
+
+==========
+``adbc.h``
+==========
+
+.. doxygenfile:: adbc.h
diff --git a/docs/source/cpp/api/adbc_driver_manager.rst b/docs/source/cpp/api/adbc_driver_manager.rst
new file mode 100644
index 0000000..f624ce9
--- /dev/null
+++ b/docs/source/cpp/api/adbc_driver_manager.rst
@@ -0,0 +1,22 @@
+.. 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.
+
+=========================
+``adbc_driver_manager.h``
+=========================
+
+.. doxygenfile:: adbc_driver_manager.h
diff --git a/docs/source/cpp/api/index.rst b/docs/source/cpp/api/index.rst
new file mode 100644
index 0000000..0011d51
--- /dev/null
+++ b/docs/source/cpp/api/index.rst
@@ -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.
+
+===================
+C/C++ API Reference
+===================
+
+.. toctree::
+ :maxdepth: 2
+
+ adbc
+ adbc_driver_manager
diff --git a/docs/source/cpp/concurrency.rst b/docs/source/cpp/concurrency.rst
new file mode 100644
index 0000000..d7cfbae
--- /dev/null
+++ b/docs/source/cpp/concurrency.rst
@@ -0,0 +1,90 @@
+.. 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.
+
+=============================
+Concurrency and Thread Safety
+=============================
+
+In general, objects allow serialized access from multiple threads: one
+thread may make a call, and once finished, another thread may make a
+call. They do not allow concurrent access from multiple threads.
+
+Somewhat related is the question of overlapping/concurrent execution
+of multi-step operations, from a single thread or multiple threads.
+For example, two AdbcStatement objects can be created from the same
+AdbcConnection:
+
+.. code-block:: c
+
+ struct AdbcStatement stmt1;
+ struct AdbcStatement stmt2;
+
+ struct ArrowArrayStream out1;
+ struct ArrowArrayStream out2;
+
+ /* Ignoring error handling for brevity */
+ AdbcStatementNew(&conn, &stmt1, NULL);
+ AdbcStatementNew(&conn, &stmt2, NULL);
+ AdbcStatementSetSqlQuery(&stmt1, "SELECT * FROM a", NULL);
+ AdbcStatementSetSqlQuery(&stmt2, "SELECT * FROM b", NULL);
+
+ AdbcStatementExecuteQuery(&stmt1, &out1, NULL, NULL);
+ AdbcStatementExecuteQuery(&stmt2, &out2, NULL, NULL);
+ /* What happens to the result set of stmt1? */
+
+What happens if the client application calls
+:cpp:func:`AdbcStatementExecuteQuery` on ``stmt1``, then on ``stmt2``,
+without reading the result set of ``stmt1``? Some existing client
+libraries/protocols, like libpq, don't support concurrent execution of
+queries from a single connection. So the driver would have to
+either 1) buffer all results into memory during the first ``Execute``
+(or otherwise allow the program to continue reading the first result
+set), 2) issue an error on the second ``Execute``, or 3) invalidate
+the first statement's result set on the second ``Execute``.
+
+In this case, ADBC allows drivers to choose 1) or 2). If possible and
+reasonable, the driver should allow concurrent execution, whether
+because the underlying protocol is designed for it or by buffering
+result sets. But the driver is allowed to error if it is not possible
+to support it.
+
+Another use case is having a single statement, but executing it
+multiple times and reading the result sets concurrently. A client
+might desire to do this with a prepared statement, for instance:
+
+.. code-block:: c
+
+ /* Ignoring error handling for brevity */
+ struct AdbcStatement stmt;
+ AdbcStatementNew(&conn, &stmt, NULL);
+ AdbcStatementSetSqlQuery(&stmt, "SELECT * FROM a WHERE foo > ?", NULL);
+ AdbcStatementPrepare(&stmt, NULL);
+
+ struct ArrowArrayStream stream;
+ AdbcStatementBind(&stmt, &array1, &schema, NULL);
+ AdbcStatementExecuteQuery(&stmt, &stream, NULL, NULL);
+ /* Spawn a thread to process `stream` */
+
+ struct ArrowArrayStream stream2;
+ AdbcStatementBind(&stmt, &array2, &schema, NULL);
+ AdbcStatementExecuteQuery(&stmt, &stream2, NULL, NULL);
+ /* What happens to `stream` here? */
+
+ADBC chooses to disallow this (specifically: the second call to
+``Execute`` must invalidate the result set of the first call), in line
+with existing APIs that generally do not support 'overlapping' usage
+of a single prepared statement in this way.
diff --git a/docs/source/cpp/driver/flight_sql.rst b/docs/source/cpp/driver/flight_sql.rst
new file mode 100644
index 0000000..1aa5318
--- /dev/null
+++ b/docs/source/cpp/driver/flight_sql.rst
@@ -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.
+
+=================
+Flight SQL Driver
+=================
+
+The Flight SQL Driver provides access to any database implementing a
+:doc:`arrow:format/FlightSql` compatible endpoint.
+
+Installation
+============
+
+The Flight SQL driver is shipped as part of the Arrow C++ libraries
+and PyArrow. See :ref:`Installation <cpp-install-flight-sql>`.
+
+Usage
+=====
+
+To connect to a database, supply the "uri" parameter when constructing
+the :cpp:class:`AdbcDatabase`.
+
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ .. code-block:: cpp
+
+ #include "adbc.h"
+
+ // Ignoring error handling
+ struct AdbcDatabase database;
+ AdbcDatabaseNew(&database, nullptr);
+ AdbcDatabaseSetOption(&database, "uri", "grpc://localhost:8080", nullptr);
+ AdbcDatabaseInit(&database, nullptr);
+
+ .. tab-item:: Python
+ :sync: python
+
+ .. code-block:: python
+
+ import pyarrow.flight_sql
+
+
+ with pyarrow.flight_sql.connect("grpc://localhost:8080") as conn:
+ pass
+
+Additional Configuration Options
+--------------------------------
+
+The Flight SQL driver supports some additional configuration options
+in addition to the "standard" ADBC options.
+
+Custom Call Headers
+~~~~~~~~~~~~~~~~~~~
+
+Custom HTTP headers can be attached to requests via options that apply
+to both :cpp:class:`AdbcConnection` and :cpp:class:`AdbcStatement`.
+
+``arrow.flight.sql.rpc.call_header.<HEADER NAME>``
+ Add the header ``<HEADER NAME>`` to outgoing requests with the given
+ value.
+
+ .. warning:: Header names must be in all lowercase.
+
+Timeouts
+~~~~~~~~
+
+By default, timeouts are not used for RPC calls. They can be set via
+special options on :cpp:class:`AdbcConnection`. In general, it is
+best practice to set timeouts to avoid unexpectedly getting stuck.
+The options are as follows:
+
+``arrow.flight.sql.rpc.timeout_seconds.fetch``
+ A timeout (in floating-point seconds) for any API calls that fetch
+ data. This corresponds to Flight ``DoGet`` calls.
+
+ For example, this controls the timeout of the underlying Flight
+ calls that fetch more data as a result set is consumed.
+
+``arrow.flight.sql.rpc.timeout_seconds.query``
+ A timeout (in floating-point seconds) for any API calls that
+ execute a query. This corresponds to Flight ``GetFlightInfo``
+ calls.
+
+ For example, this controls the timeout of the underlying Flight
+ calls that implement :func:`AdbcStatementExecuteQuery`.
+
+``arrow.flight.sql.rpc.timeout_seconds.update``
+ A timeout (in floating-point seconds) for any API calls that
+ upload data or perform other updates.
+
+ For example, this controls the timeout of the underlying Flight
+ calls that implement bulk ingestion, or transaction support.
+
+.. TODO: code samples
+
+Type Mapping
+~~~~~~~~~~~~
+
+When executing a bulk ingestion operation, the driver needs to be able
+to construct appropriate SQL queries for the database. (The driver
+does not currently support using Substrait plans instead.) In
+particular, a mapping from Arrow types to SQL type names is required.
+While a default mapping is provided, the client may wish to override
+this mapping, which can be done by setting special options on
+:cpp:class:`AdbcDatabase`. (The driver does not currently inspect
+Flight SQL metadata to construct this mapping.)
+
+All such options begin with ``arrow.flight.sql.quirks.ingest_type.``
+and are followed by a type name below.
+
+.. csv-table:: Type Names
+ :header: "Arrow Type Name", "Default SQL Type Name"
+
+ binary,BLOB
+ bool,BOOLEAN
+ date32,DATE
+ date64,DATE
+ decimal128,NUMERIC
+ decimal256,NUMERIC
+ double,DOUBLE PRECISION
+ float,REAL
+ int16,SMALLINT
+ int32,INT
+ int64,BIGINT
+ large_binary,BLOB
+ large_string,TEXT
+ string,TEXT
+ time32,TIME
+ time64,TIME
+ timestamp,TIMESTAMP
+
+.. TODO: code samples
+
+Partitioned Result Set Support
+------------------------------
+
+The Flight SQL driver supports ADBC's partitioned result sets, mapping
+them onto FlightEndpoints. Each partition of a result set contains a
+serialized FlightInfo, containing one of the FlightEndpoints of the
+original response. Clients who may wish to introspect the partition
+can do so by deserializing the contained FlightInfo from the ADBC
+partitions. (For example, a client that wishes to distribute work
+across multiple workers or machines may want to try to take advantage
+of locality information that ADBC does not have.)
+
+.. TODO: code samples
+
+.. _DBAPI 2.0: https://peps.python.org/pep-0249/
diff --git a/docs/source/cpp/driver/index.rst b/docs/source/cpp/driver/index.rst
new file mode 100644
index 0000000..7a05c79
--- /dev/null
+++ b/docs/source/cpp/driver/index.rst
@@ -0,0 +1,29 @@
+.. 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.
+
+=======
+Drivers
+=======
+
+The project ships with a number of drivers for particular database
+protocols/databases. More may be available from third parties.
+
+.. toctree::
+ :maxdepth: 1
+
+ flight_sql
+ postgres
diff --git a/docs/source/cpp/driver/postgres.rst b/docs/source/cpp/driver/postgres.rst
new file mode 100644
index 0000000..6a8f0b4
--- /dev/null
+++ b/docs/source/cpp/driver/postgres.rst
@@ -0,0 +1,63 @@
+.. 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.
+
+==================
+libpq-based Driver
+==================
+
+The Flight SQL Driver provides access to any database that supports
+the Postgres wire format.
+
+Installation
+============
+
+The libpq-based driver is shipped as a standalone library. See
+:ref:`Installation <cpp-install-libpq>`.
+
+Usage
+=====
+
+To connect to a database, supply the "uri" parameter when constructing
+the :cpp:class:`AdbcDatabase`. This should be a `connection URI
+<https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_.
+
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ .. code-block:: cpp
+
+ #include "adbc.h"
+
+ // Ignoring error handling
+ struct AdbcDatabase database;
+ AdbcDatabaseNew(&database, nullptr);
+ AdbcDatabaseSetOption(&database, "uri", "postgresql://localhost:5433", nullptr);
+ AdbcDatabaseInit(&database, nullptr);
+
+ .. tab-item:: Python
+ :sync: python
+
+ .. code-block:: python
+
+ import adbc_driver_postgres.dbapi
+
+
+ uri = "postgresql://localhost:5433"
+ with adbc_driver_postgres.dbapi.connect(uri) as conn:
+ pass
diff --git a/docs/source/cpp/driver_manager.rst b/docs/source/cpp/driver_manager.rst
new file mode 100644
index 0000000..a017f06
--- /dev/null
+++ b/docs/source/cpp/driver_manager.rst
@@ -0,0 +1,61 @@
+.. 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.
+
+==============
+Driver Manager
+==============
+
+The driver manager is a library that implements the ADBC API by
+delegating to dynamically-loaded drivers. This allows applications to
+use multiple drivers simultaneously, and decouple themselves from the
+specific driver.
+
+Installation
+============
+
+See :doc:`./install`.
+
+Usage
+=====
+
+To create a database, use the :cpp:class:`AdbcDatabase` API as usual,
+but during initialization, provide two additional parameters in
+addition to the driver-specific connection parameters: ``driver`` and
+(optionally) ``entrypoint``. ``driver`` must be the name of a library
+to load, or the path to a library to load. ``entrypoint``, if
+provided, should be the name of the symbol that serves as the ADBC
+entrypoint (see :cpp:type:`AdbcDriverInitFunc`).
+
+.. code-block:: c
+
+ /* Ignoring error handling */
+ struct AdbcDatabase database;
+ memset(&database, 0, sizeof(database));
+ AdbcDatabaseNew(&database, NULL);
+ /* On Linux: loads libadbc_driver_sqlite.so
+ * On MacOS: loads libadbc_driver_sqlite.dylib
+ * On Windows: loads adbc_driver_sqlite.dll */
+ AdbcDatabaseSetOption(&database, "driver", "adbc_driver_sqlite", NULL);
+ /* Set additional options for the specific driver */
+ AdbcDatabaseInit(&database, NULL);
+
+
+API Reference
+=============
+
+The driver manager includes a few additional functions beyond the ADBC
+API. See the API reference: :doc:`./api/adbc_driver_manager`.
diff --git a/docs/source/cpp/index.rst b/docs/source/cpp/index.rst
new file mode 100644
index 0000000..3c13d01
--- /dev/null
+++ b/docs/source/cpp/index.rst
@@ -0,0 +1,29 @@
+.. 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.
+
+=========
+C and C++
+=========
+
+.. toctree::
+ :maxdepth: 2
+
+ install
+ driver/index
+ driver_manager
+ concurrency
+ api/index
diff --git a/docs/source/cpp/install.rst b/docs/source/cpp/install.rst
new file mode 100644
index 0000000..ee2a57b
--- /dev/null
+++ b/docs/source/cpp/install.rst
@@ -0,0 +1,101 @@
+.. 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.
+
+============
+Installation
+============
+
+To build the libraries from source, see :doc:`../contributing`.
+
+.. _cpp-install-driver-manager:
+
+ADBC Driver Manager
+===================
+
+.. _cpp-install-flight-sql:
+
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ .. note:: Under construction
+
+ .. tab-item:: Python (pip)
+ :sync: python
+
+ .. note:: Under construction
+
+ .. tab-item:: Python (conda-forge)
+ :sync: python-conda-forge
+
+ .. note:: Under construction
+
+Flight SQL Driver
+=================
+
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ Link to the Arrow C++ libraries, in particlar the Flight SQL
+ libraries. See :doc:`arrow:cpp/build_system`.
+
+ .. tab-item:: Python (pip)
+ :sync: python
+
+ 1. Install PyArrow 11.0.0 or greater. See
+ :doc:`arrow:python/install`.
+ 2. :ref:`Install the Python ADBC Driver Manager
+ <cpp-install-driver-manager>`.
+ 3. Import ``pyarrow.flight_sql`` for a `DBAPI 2.0`_-compatible
+ interface.
+
+ .. tab-item:: Python (conda-forge)
+ :sync: python-conda-forge
+
+ 1. Install PyArrow 11.0.0 or greater. See
+ :doc:`arrow:python/install`.
+ 2. :ref:`Install the Python ADBC Driver Manager
+ <cpp-install-driver-manager>`.
+ 3. Import ``pyarrow.flight_sql`` for a `DBAPI 2.0`_-compatible
+ interface.
+
+.. _cpp-install-libpq:
+
+libpq-based Driver
+==================
+
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ .. note:: Under construction
+
+ .. tab-item:: Python (pip)
+ :sync: python
+
+ .. note:: Under construction
+
+ .. tab-item:: Python (conda-forge)
+ :sync: python-conda-forge
+
+ .. note:: Under construction
+
+.. _DBAPI 2.0: https://peps.python.org/pep-0249/
diff --git a/docs/source/format/comparison.rst b/docs/source/format/comparison.rst
new file mode 100644
index 0000000..f6779c1
--- /dev/null
+++ b/docs/source/format/comparison.rst
@@ -0,0 +1,71 @@
+.. 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.
+
+==========================
+Comparison with Other APIs
+==========================
+
+.. list-table:: Equivalent concepts between ADBC and other APIs
+ :header-rows: 1
+
+ * - Concept/API
+ - ADBC
+ - database/sql (Golang)
+ - DBAPI 2.0 (PEP 249)
+ - Flight SQL
+ - JDBC
+ - ODBC
+
+ * - Shared connection state
+ - :cpp:class:`AdbcDatabase`
+ - ``DB``
+ - —
+ - —
+ - —
+ - —
+
+ * - Database connection
+ - :cpp:class:`AdbcConnection`
+ - ``Conn``
+ - ``Connection``
+ - ``FlightSqlClient``
+ - ``Connection``
+ - ``SQLHANDLE`` (connection)
+
+ * - Query state
+ - :cpp:class:`AdbcStatement`
+ - —
+ - ``Cursor``
+ - —
+ - ``Statement``
+ - ``SQLHANDLE`` (statement)
+
+ * - Prepared statement handle
+ - :cpp:class:`AdbcStatement`
+ - Stmt
+ - ``Cursor``
+ - ``PreparedStatement``
+ - ``PreparedStatement``
+ - ``SQLHANDLE`` (statement)
+
+ * - Result set
+ - ``ArrowArrayStream``
+ - ``*Rows``
+ - ``Cursor``
+ - ``FlightInfo``
+ - ``ResultSet``
+ - ``SQLHANDLE`` (statement)
diff --git a/docs/source/format/specification.rst b/docs/source/format/specification.rst
new file mode 100644
index 0000000..c0054b1
--- /dev/null
+++ b/docs/source/format/specification.rst
@@ -0,0 +1,96 @@
+.. 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.
+
+=================
+ADBC API Standard
+=================
+
+This document summarizes the general featureset.
+
+- For C/C++ details, see :doc:`adbc.h <../../cpp/api/adbc>`.
+- For Go details, see the `source <https://github.com/apache/arrow-adbc/blob/main/go/adbc/adbc.go>`__.
+- For Java details, see the `source <https://github.com/apache/arrow-adbc/tree/main/java/core>`__.
+
+Databases
+=========
+
+Databases hold state shared by multiple connections. Generally, this
+means common configuration and caches. For in-memory databases, it
+provides a place to hold ownership of the in-memory database.
+
+- C/C++: :cpp:class:`AdbcDatabase`
+- Go: ``Driver``
+- Java: ``org.apache.arrow.adbc.core.AdbcDatabase``
+
+Connections
+===========
+
+A connection is a single, logical connection to a database.
+
+- C/C++: :cpp:class:`AdbcConnection`
+- Go: ``Connection``
+- Java: ``org.apache.arrow.adbc.core.AdbcConnection``
+
+Autocommit
+----------
+
+By default, connections are expected to operate in autocommit mode;
+that is, queries take effect immediately upon execution. This can be
+disabled in favor of manual commit/rollback calls, but not all
+implementations will support this.
+
+- C/C++: :c:macro:`ADBC_CONNECTION_OPTION_AUTOCOMMIT`
+- Go: ``OptionKeyAutoCommit``
+- Java: ``org.apache.arrow.adbc.core.AdbcConnection#setAutoCommit(boolean)``
+
+Statements
+==========
+
+Statements hold state related to query execution. They represent both
+one-off queries and prepared statements. They can be reused, though
+doing so will invalidate prior result sets from that statement. (See
+:doc:`../../cpp/concurrency`.)
+
+- C/C++: :cpp:class:`AdbcStatement`
+- Go: ``Statement``
+- Java: ``org.apache.arrow.adbc.core.AdbcStatement``
+
+Bulk Ingestion
+--------------
+
+ADBC provides explicit facilities to ingest batches of Arrow data into
+a database table. For databases which support it, this can avoid
+overheads from the typical bind-insert loop. Also, this (mostly)
+frees the user from knowing the right SQL syntax for their database.
+
+- C/C++: :c:macro:`ADBC_INGEST_OPTION_TARGET_TABLE` and related
+ options.
+- Go: ``OptionKeyIngestTargetTable``
+- Java: ``org.apache.arrow.adbc.core.AdbcConnection#bulkIngest(String, org.apache.arrow.adbc.core.BulkIngestMode)``
+
+Partitioned Result Sets
+-----------------------
+
+ADBC lets a driver explicitly expose partitioned and/or distributed
+result sets to clients. (This is similar to functionality in Flight
+RPC/Flight SQL.) Clients may take advantage of this to distribute
+computations on a result set across multiple threads, processes, or
+machines.
+
+- C/C++: :cpp:func:`AdbcStatementExecutePartitions`
+- Go: ``Statement.ExecutePartitions``
+- Java: ``org.apache.arrow.adbc.core.AdbcStatement#executePartitioned()``
diff --git a/docs/source/format/versioning.rst b/docs/source/format/versioning.rst
new file mode 100644
index 0000000..3205b79
--- /dev/null
+++ b/docs/source/format/versioning.rst
@@ -0,0 +1,70 @@
+.. 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.
+
+============================
+Versioning and Compatibility
+============================
+
+The goal is to be **ABI-compatible** across releases. Hence, a few
+choices were made:
+
+- Most structures do not contain embedded fields or functions, but
+ instead use free functions, making it easy to add new functions.
+- Enumerations are defined via ``typedef``/``#define``.
+
+Of course, we can never add/remove/change struct members, and we can
+never change the signatures of existing functions.
+
+The main point of concern is compatibility of :cpp:class:`AdbcDriver`.
+
+The driver entrypoint, :cpp:type:`AdbcDriverInitFunc`, is given a
+version and a pointer to a table of function pointers to initialize.
+The type of the table will depend on the version; when a new version
+of ADBC is accepted, then a new table of function pointers will be
+added. That way, the driver knows the type of the table. If/when we
+add a new ADBC version, the following scenarios are possible:
+
+- An updated client application uses an old driver library. The
+ client will pass a `version` field greater than what the driver
+ recognizes, so the driver will return
+ :c:type:`ADBC_STATUS_NOT_IMPLEMENTED` and the client can decide
+ whether to abort or retry with an older version.
+- An old client application uses an updated driver library. The
+ client will pass a ``version`` lower than what the driver
+ recognizes, so the driver can either error, or if it can still
+ implement the old API contract, initialize the older table.
+
+This approach does not let us change the signatures of existing
+functions, but we can add new functions and remove existing ones.
+
+Versioning
+==========
+
+ADBC is versioned separately from the core Arrow project. The API
+standard and components (driver manager, drivers) are also versioned
+separately, but both follow semantic versioning.
+
+For example: components may make backwards-compatible releases as
+1.0.0, 1.0.1, 1.1.0, 1.2.0, etc. They may release
+backwards-incompatible versions such as 2.0.0, but which still
+implement the API standard version 1.0.0.
+
+Similarly, this documentation describes the ADBC API standard version
+1.0.0. If/when a compatible revision is made (e.g. new standard
+options are defined), the next version would be 1.1.0. If
+incompatible changes are made (e.g. new API functions), the next
+version would be 2.0.0.
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..1938240
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,66 @@
+.. 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 ADBC
+=================
+
+ADBC (Arrow Database Connectivity) is an API specification for
+Arrow-based database access. It provides a set of APIs in C, Go, and
+Java that define how to interact with databases, including executing
+queries and fetching metadata, that use Arrow data for result sets and
+query parameters. These APIs are then implemented by drivers (or a
+driver manager) that use some underlying protocol to work with
+specific databases.
+
+ADBC aims to provide applications with a single API to work with
+multiple databases, both Arrow-native and not. Application code
+should not need to juggle conversions from non-Arrow-native
+datasources alongside bindings for multiple Arrow-native database
+protocols. And Arrow Flight SQL by itself cannot solve this problem,
+because it's a specific wire protocol that not all databases will
+implement.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Specifications:
+
+ format/specification
+ format/versioning
+ format/comparison
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Supported Environments:
+
+ C/C++ <cpp/index>
+ Java <java/index>
+ Python <python/index>
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contributing:
+
+ contributing
+ nightly
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/java/index.rst b/docs/source/java/index.rst
new file mode 100644
index 0000000..ccfe071
--- /dev/null
+++ b/docs/source/java/index.rst
@@ -0,0 +1,25 @@
+.. 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.
+
+====
+Java
+====
+
+.. toctree::
+ :maxdepth: 2
+
+.. note:: Under construction
diff --git a/docs/source/nightly.rst b/docs/source/nightly.rst
new file mode 100644
index 0000000..6f8b6f8
--- /dev/null
+++ b/docs/source/nightly.rst
@@ -0,0 +1,67 @@
+.. 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.
+
+================
+Nightly Packages
+================
+
+Nightly builds of some binary packages are available.
+
+.. warning:: These packages are not official releases. These packages
+ are not intended for normal usage, only for project
+ developers.
+
+C/C++
+=====
+
+Not yet available.
+
+Java
+====
+
+Not yet available.
+
+Python
+======
+
+Packages can be installed from an alternative package index:
+https://gemfury.com/arrow-adbc-nightlies
+
+Example::
+
+ $ pip install \
+ --extra-index-url https://gemfury.com/arrow-adbc-nightlies \
+ adbc_driver_manager
+
+.. list-table:: Supported platforms for nightly Python wheels
+ :header-rows: 1
+
+ * - Operating System
+ - AMD64 (x86_64)
+ - AArch64
+
+ * - Linux
+ - Yes ✅
+ - No ❌
+
+ * - macOS
+ - Yes ✅
+ - No ❌
+
+ * - Windows
+ - No ❌
+ - No ❌
diff --git a/docs/source/python/api/adbc_driver_manager.rst b/docs/source/python/api/adbc_driver_manager.rst
new file mode 100644
index 0000000..96414e3
--- /dev/null
+++ b/docs/source/python/api/adbc_driver_manager.rst
@@ -0,0 +1,135 @@
+.. 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.
+
+.. default-domain:: py
+
+===================
+adbc_driver_manager
+===================
+
+Low-Level API
+=============
+
+.. automodule:: adbc_driver_manager
+
+Constants & Enums
+-----------------
+
+.. autoclass:: adbc_driver_manager.AdbcStatusCode
+ :members:
+
+.. autoclass:: adbc_driver_manager.GetObjectsDepth
+ :members:
+
+.. XXX: Sphinx doesn't seem to be able to parse docstrings out of
+ Cython code, so put the descriptions here instead.
+
+ Alternatively: refactor the package into adbc.pxd, _constants.pyx,
+ constants.py, etc.?
+
+.. data:: adbc_driver_manager.INGEST_OPTION_MODE
+
+ Whether to append to or create a new table for bulk ingestion.
+
+.. data:: adbc_driver_manager.INGEST_OPTION_MODE_APPEND
+
+ Append to the table for bulk ingestion.
+
+.. data:: adbc_driver_manager.INGEST_OPTION_MODE_CREATE
+
+ Create a new table for bulk ingestion.
+
+.. data:: adbc_driver_manager.INGEST_OPTION_TARGET_TABLE
+
+ The table to create/append to for bulk ingestion.
+
+Classes
+-------
+
+.. autoclass:: adbc_driver_manager.AdbcConnection
+ :members:
+
+.. autoclass:: adbc_driver_manager.AdbcDatabase
+ :members:
+
+.. autoclass:: adbc_driver_manager.AdbcStatement
+ :members:
+
+.. autoclass:: adbc_driver_manager.ArrowArrayHandle
+ :members:
+
+.. autoclass:: adbc_driver_manager.ArrowArrayStreamHandle
+ :members:
+
+.. autoclass:: adbc_driver_manager.ArrowSchemaHandle
+ :members:
+
+DBAPI 2.0 API
+=============
+
+.. automodule:: adbc_driver_manager.dbapi
+
+Constants & Enums
+-----------------
+
+.. autodata:: adbc_driver_manager.dbapi.apilevel
+.. autodata:: adbc_driver_manager.dbapi.paramstyle
+.. autodata:: adbc_driver_manager.dbapi.threadsafety
+
+.. autodata:: adbc_driver_manager.dbapi.Date
+.. autodata:: adbc_driver_manager.dbapi.Time
+.. autodata:: adbc_driver_manager.dbapi.Timestamp
+
+.. autodata:: adbc_driver_manager.dbapi.BINARY
+.. autodata:: adbc_driver_manager.dbapi.DATETIME
+.. autodata:: adbc_driver_manager.dbapi.NUMBER
+.. autodata:: adbc_driver_manager.dbapi.ROWID
+.. autodata:: adbc_driver_manager.dbapi.STRING
+
+Functions
+---------
+
+.. autofunction:: adbc_driver_manager.dbapi.connect
+.. autofunction:: adbc_driver_manager.dbapi.DateFromTicks
+.. autofunction:: adbc_driver_manager.dbapi.TimeFromTicks
+.. autofunction:: adbc_driver_manager.dbapi.TimestampFromTicks
+
+Classes
+-------
+
+.. autoclass:: adbc_driver_manager.dbapi.Connection
+ :members:
+ :exclude-members: DatabaseError, DataError, Error, IntegrityError,
+ InterfaceError, InternalError, NotSupportedError,
+ OperationalError, ProgrammingError, Warning
+
+.. autoclass:: adbc_driver_manager.dbapi.Cursor
+ :members:
+
+Exceptions
+==========
+
+.. autoexception:: DatabaseError
+.. autoexception:: DataError
+.. autoexception:: Error
+.. autoexception:: IntegrityError
+.. autoexception:: InterfaceError
+.. autoexception:: InternalError
+.. autoexception:: NotSupportedError
+.. autoexception:: OperationalError
+.. autoexception:: ProgrammingError
+.. autoexception:: Warning
diff --git a/docs/source/python/api/index.rst b/docs/source/python/api/index.rst
new file mode 100644
index 0000000..1dd99a0
--- /dev/null
+++ b/docs/source/python/api/index.rst
@@ -0,0 +1,25 @@
+.. 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.
+
+====================
+Python API Reference
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ adbc_driver_manager
diff --git a/docs/source/python/index.rst b/docs/source/python/index.rst
new file mode 100644
index 0000000..e41b85c
--- /dev/null
+++ b/docs/source/python/index.rst
@@ -0,0 +1,27 @@
+.. 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.
+
+======
+Python
+======
+
+.. toctree::
+ :maxdepth: 2
+
+ ../cpp/install
+ ../cpp/driver/index
+ api/index
diff --git a/python/adbc_driver_manager/adbc_driver_manager/__init__.py b/python/adbc_driver_manager/adbc_driver_manager/__init__.py
index 2c808f5..4ad59ab 100644
--- a/python/adbc_driver_manager/adbc_driver_manager/__init__.py
+++ b/python/adbc_driver_manager/adbc_driver_manager/__init__.py
@@ -15,7 +15,17 @@
# specific language governing permissions and limitations
# under the License.
-from ._lib import ( # noqa: F401
+"""Low-level ADBC bindings for Python.
+
+The root module provides a fairly direct, 1:1 mapping to the C API
+definitions in Python. For a higher-level interface, use
+:mod:`adbc_driver_manager.dbapi`. (This requires PyArrow.)
+"""
+
+from ._lib import (
+ INGEST_OPTION_MODE,
+ INGEST_OPTION_MODE_APPEND,
+ INGEST_OPTION_MODE_CREATE,
INGEST_OPTION_TARGET_TABLE,
AdbcConnection,
AdbcDatabase,
@@ -37,3 +47,29 @@ from ._lib import ( # noqa: F401
ProgrammingError,
)
from ._version import version as __version__ # noqa: F401
+
+__all__ = [
+ "__version__",
+ "INGEST_OPTION_MODE",
+ "INGEST_OPTION_MODE_APPEND",
+ "INGEST_OPTION_MODE_CREATE",
+ "INGEST_OPTION_TARGET_TABLE",
+ "AdbcConnection",
+ "AdbcDatabase",
+ "AdbcInfoCode",
+ "AdbcStatement",
+ "AdbcStatusCode",
+ "ArrowArrayHandle",
+ "ArrowArrayStreamHandle",
+ "ArrowSchemaHandle",
+ "DatabaseError",
+ "DataError",
+ "Error",
+ "GetObjectsDepth",
+ "IntegrityError",
+ "InterfaceError",
+ "InternalError",
+ "NotSupportedError",
+ "OperationalError",
+ "ProgrammingError",
+]
diff --git a/python/adbc_driver_manager/adbc_driver_manager/_lib.pyx b/python/adbc_driver_manager/adbc_driver_manager/_lib.pyx
index 894a62c..0e619d9 100644
--- a/python/adbc_driver_manager/adbc_driver_manager/_lib.pyx
+++ b/python/adbc_driver_manager/adbc_driver_manager/_lib.pyx
@@ -229,6 +229,10 @@ cdef extern from "adbc_driver_manager.h":
class AdbcStatusCode(enum.IntEnum):
+ """
+ A status code indicating the type of error.
+ """
+
OK = ADBC_STATUS_OK
UNKNOWN = ADBC_STATUS_UNKNOWN
NOT_IMPLEMENTED = ADBC_STATUS_NOT_IMPLEMENTED
@@ -267,7 +271,7 @@ class Error(Exception):
Attributes
----------
- status_code : CAdbcStatusCode
+ status_code : AdbcStatusCode
The original ADBC status code.
vendor_code : int, optional
A vendor-specific status code if present.
@@ -283,34 +287,36 @@ class Error(Exception):
class InterfaceError(Error):
- pass
+ """Errors related to the database interface."""
class DatabaseError(Error):
- pass
+ """Errors related to the database."""
class DataError(DatabaseError):
- pass
+ """Errors related to processed data."""
class OperationalError(DatabaseError):
- pass
+ """Errors related to database operation, not under user control."""
class IntegrityError(DatabaseError):
- pass
+ """Errors related to relational integrity."""
class InternalError(DatabaseError):
- pass
+ """Errors related to database-internal errors."""
class ProgrammingError(DatabaseError):
- pass
+ """Errors related to user errors."""
class NotSupportedError(DatabaseError):
+ """An operation or some functionality is not supported."""
+
def __init__(self, message, *, vendor_code=None, sqlstate=None):
super().__init__(
message,
@@ -320,10 +326,10 @@ class NotSupportedError(DatabaseError):
)
-INGEST_OPTION_TARGET_TABLE = ADBC_INGEST_OPTION_TARGET_TABLE.decode("utf-8")
INGEST_OPTION_MODE = ADBC_INGEST_OPTION_MODE.decode("utf-8")
INGEST_OPTION_MODE_APPEND = ADBC_INGEST_OPTION_MODE_APPEND.decode("utf-8")
INGEST_OPTION_MODE_CREATE = ADBC_INGEST_OPTION_MODE_CREATE.decode("utf-8")
+INGEST_OPTION_TARGET_TABLE = ADBC_INGEST_OPTION_TARGET_TABLE.decode("utf-8")
cdef void check_error(CAdbcStatusCode status, CAdbcError* error) except *:
diff --git a/python/adbc_driver_manager/adbc_driver_manager/dbapi.py b/python/adbc_driver_manager/adbc_driver_manager/dbapi.py
index 1c67986..14b0245 100644
--- a/python/adbc_driver_manager/adbc_driver_manager/dbapi.py
+++ b/python/adbc_driver_manager/adbc_driver_manager/dbapi.py
@@ -72,21 +72,27 @@ _KNOWN_INFO_VALUES = {
# ----------------------------------------------------------
# Types
+#: The type for date values.
Date = datetime.date
+#: The type for time values.
Time = datetime.time
+#: The type for timestamp values.
Timestamp = datetime.datetime
-def DateFromTicks(ticks):
+def DateFromTicks(ticks: int) -> Date:
+ """Construct a date value from a count of seconds."""
# Standard implementations from PEP 249 itself
return Date(*time.localtime(ticks)[:3])
-def TimeFromTicks(ticks):
+def TimeFromTicks(ticks: int) -> Date:
+ """Construct a time value from a count of seconds."""
return Time(*time.localtime(ticks)[3:6])
-def TimestampFromTicks(ticks):
+def TimestampFromTicks(ticks: int) -> Date:
+ """Construct a timestamp value from a count of seconds."""
return Timestamp(*time.localtime(ticks)[:6])
@@ -101,8 +107,19 @@ class _TypeSet(frozenset):
return False
-STRING = _TypeSet([pyarrow.string().id, pyarrow.large_string().id])
+#: The type of binary columns.
BINARY = _TypeSet({pyarrow.binary().id, pyarrow.large_binary().id})
+#: The type of datetime columns.
+DATETIME = _TypeSet(
+ [
+ pyarrow.date32().id,
+ pyarrow.date64().id,
+ pyarrow.time32("s").id,
+ pyarrow.time64("ns").id,
+ pyarrow.timestamp("s").id,
+ ]
+)
+#: The type of numeric columns.
NUMBER = _TypeSet(
[
pyarrow.int8().id,
@@ -117,16 +134,10 @@ NUMBER = _TypeSet(
pyarrow.float64().id,
]
)
-DATETIME = _TypeSet(
- [
- pyarrow.date32().id,
- pyarrow.date64().id,
- pyarrow.time32("s").id,
- pyarrow.time64("ns").id,
- pyarrow.timestamp("s").id,
- ]
-)
+#: The type of "row ID" columns.
ROWID = _TypeSet([pyarrow.int64().id])
+#: The type of string columns.
+STRING = _TypeSet([pyarrow.string().id, pyarrow.large_string().id])
# ----------------------------------------------------------
# Functions
@@ -146,10 +157,12 @@ def connect(
----------
driver
The driver name. For example, "adbc_driver_sqlite" will
- attempt to load libadbc_driver_sqlite.so on Unix-like systems,
- and adbc_driver_sqlite.dll on Windows.
+ attempt to load libadbc_driver_sqlite.so on Linux systems,
+ libadbc_driver_sqlite.dylib on MacOS, and
+ adbc_driver_sqlite.dll on Windows. This may also be a path to
+ the library to load.
entrypoint
- The driver-specific entrypoint.
+ The driver-specific entrypoint, if different than the default.
db_kwargs
Key-value parameters to pass to the driver to initialize the
database.
@@ -480,19 +493,21 @@ class Cursor(_Closeable):
return self._results.description
@property
- def rowcount(self):
+ def rowcount(self) -> int:
"""
Get the row count of the result set, or -1 if not known.
"""
return self._rowcount
@property
- def rownumber(self):
+ def rownumber(self) -> Optional[int]:
+ """Get the current row number, or None if not applicable."""
if self._results is not None:
return self._results.rownumber
return None
def callproc(self, procname, parameters):
+ """Call a stored procedure (not supported)."""
raise NotSupportedError("Cursor.callproc")
def close(self):
@@ -540,6 +555,7 @@ class Cursor(_Closeable):
)
def executemany(self, operation, seq_of_parameters):
+ """Execute a query with multiple parameter sets."""
self._results = None
if operation != self._last_query:
self._last_query = operation
@@ -600,14 +616,15 @@ class Cursor(_Closeable):
return row
def nextset(self):
+ """Move to the next available result set (not supported)."""
raise NotSupportedError("Cursor.nextset")
def setinputsizes(self, sizes):
- # Not used
+ """Preallocate memory for the parameters (no-op)."""
pass
def setoutputsize(self, size, column=None):
- # Not used
+ """Preallocate memory for the result set (no-op)."""
pass
def __iter__(self):