From 5ab6102c74e7987793855797f3c3947c372db93a Mon Sep 17 00:00:00 2001
From: David Li
Date: Wed, 19 Jul 2023 11:22:05 -0400
Subject: [PATCH] docs: add page for DuckDB
Fixes #874.
---
docs/source/driver/duckdb.rst | 102 +++++++++++++++++++
docs/source/driver/postgresql.rst | 50 ++++-----
docs/source/driver/sqlite.rst | 21 ++--
docs/source/index.rst | 1 +
docs/source/python/recipe/driver_manager.rst | 2 +
5 files changed, 140 insertions(+), 36 deletions(-)
create mode 100644 docs/source/driver/duckdb.rst
diff --git a/docs/source/driver/duckdb.rst b/docs/source/driver/duckdb.rst
new file mode 100644
index 0000000000..f27d6062aa
--- /dev/null
+++ b/docs/source/driver/duckdb.rst
@@ -0,0 +1,102 @@
+.. 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.
+
+==============
+DuckDB Support
+==============
+
+**Available for:** C/C++, GLib/Ruby, Go, Python
+
+`DuckDB`_ provides ADBC support since `version 0.8.0
+`_.
+
+.. note:: DuckDB is not part of the Apache Arrow project and is
+ developed separately.
+
+.. _DuckDB: https://duckdb.org/
+
+Installation
+============
+
+See the `DuckDB documentation
+`_.
+
+Usage
+=====
+
+ADBC support in DuckDB requires the driver manager.
+
+.. tab-set::
+
+ .. tab-item:: C++
+ :sync: cpp
+
+ .. code-block:: cpp
+
+ #include "adbc.h"
+
+ // Ignoring error handling
+ struct AdbcDatabase database;
+ AdbcDatabaseNew(&database, nullptr);
+ AdbcDatabaseSetOption(&database, "driver", "PATH/TO/libduckdb.so", nullptr);
+ AdbcDatabaseSetOption(&database, "entrypoint", "duckdb_adbc_init", nullptr);
+ AdbcDatabaseInit(&database, nullptr);
+
+ .. tab-item:: Go
+ :sync: go
+
+ You must have ``libduckdb.so`` on your ``LD_LIBRARY_PATH``, or
+ in the same directory as the executable when you run this. This
+ requires CGO and loads the DuckDB driver.
+
+ .. code-block:: go
+
+ import (
+ "context"
+
+ "github.com/apache/arrow-adbc/go/adbc"
+ "github.com/apache/arrow-adbc/go/adbc/drivermgr"
+ )
+
+ func main() {
+ var drv drivermgr.Driver
+ db, err := drv.NewDatabase(map[string]string{
+ "driver": "libduckdb.so",
+ "entrypoint": "duckdb_adbc_init",
+ })
+ if err != nil {
+ // handle error
+ }
+
+ cnxn, err := db.Open(context.Background())
+ if err != nil {
+ // handle error
+ }
+ defer cnxn.Close()
+ }
+
+ .. tab-item:: Python
+ :sync: python
+
+ See :ref:`recipe-driver-manager-duckdb`.
+
+
+Supported Features
+==================
+
+ADBC support in DuckDB is still in progress. See `duckdb/duckdb#7141
+`_ for details.
diff --git a/docs/source/driver/postgresql.rst b/docs/source/driver/postgresql.rst
index 4b3c2050fd..7ec5b7f589 100644
--- a/docs/source/driver/postgresql.rst
+++ b/docs/source/driver/postgresql.rst
@@ -100,31 +100,6 @@ the :cpp:class:`AdbcDatabase`. This should be a `connection URI
AdbcDatabaseSetOption(&database, "uri", "postgresql://localhost:5433", nullptr);
AdbcDatabaseInit(&database, nullptr);
- .. tab-item:: Python
- :sync: python
-
- .. code-block:: python
-
- import adbc_driver_postgresql.dbapi
-
- uri = "postgresql://user:pass@localhost:5433/postgres"
- with adbc_driver_postgresql.dbapi.connect(uri) as conn:
- pass
-
- For more examples, see :doc:`../python/recipe/postgresql`.
-
- .. tab-item:: R
- :sync: r
-
- .. code-block:: r
-
- library(adbcdrivermanager)
-
- # Use the driver manager to connect to a database
- uri <- Sys.getenv("ADBC_POSTGRESQL_TEST_URI")
- db <- adbc_database_init(adbcpostgresql::adbcpostgresql(), uri = uri)
- con <- adbc_connection_init(db)
-
.. tab-item:: Go
:sync: go
@@ -158,6 +133,31 @@ the :cpp:class:`AdbcDatabase`. This should be a `connection URI
defer cnxn.Close()
}
+ .. tab-item:: Python
+ :sync: python
+
+ .. code-block:: python
+
+ import adbc_driver_postgresql.dbapi
+
+ uri = "postgresql://user:pass@localhost:5433/postgres"
+ with adbc_driver_postgresql.dbapi.connect(uri) as conn:
+ pass
+
+ For more examples, see :doc:`../python/recipe/postgresql`.
+
+ .. tab-item:: R
+ :sync: r
+
+ .. code-block:: r
+
+ library(adbcdrivermanager)
+
+ # Use the driver manager to connect to a database
+ uri <- Sys.getenv("ADBC_POSTGRESQL_TEST_URI")
+ db <- adbc_database_init(adbcpostgresql::adbcpostgresql(), uri = uri)
+ con <- adbc_connection_init(db)
+
Supported Features
==================
diff --git a/docs/source/driver/sqlite.rst b/docs/source/driver/sqlite.rst
index ff4397084d..513dd939f5 100644
--- a/docs/source/driver/sqlite.rst
+++ b/docs/source/driver/sqlite.rst
@@ -41,6 +41,16 @@ Installation
mamba install libadbc-driver-sqlite
+ .. tab-item:: Go
+ :sync: go
+
+ Install the C/C++ package and use the Go driver manager.
+ Requires CGO.
+
+ .. code-block:: shell
+
+ go get github.com/apache/arrow-adbc/go/adbc/drivermgr
+
.. tab-item:: Python
:sync: python
@@ -60,17 +70,6 @@ Installation
# install.packages("pak")
pak::pak("apache/arrow-adbc/r/adbcsqlite")
- .. tab-item:: Go
- :sync: go
-
- Install the C/C++ package and use the Go driver manager.
- Requires CGO.
-
- .. code-block:: shell
-
- go get github.com/apache/arrow-adbc/go/adbc/drivermgr
-
-
Usage
=====
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a5540e64bc..76c4ebf338 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -44,6 +44,7 @@ To learn more about ADBC, see the `introductory blog post
driver/installation
driver/status
+ driver/duckdb
driver/flight_sql
driver/jdbc
driver/postgresql
diff --git a/docs/source/python/recipe/driver_manager.rst b/docs/source/python/recipe/driver_manager.rst
index 349d549046..71f0dc7538 100644
--- a/docs/source/python/recipe/driver_manager.rst
+++ b/docs/source/python/recipe/driver_manager.rst
@@ -19,6 +19,8 @@
Driver Manager Recipes
======================
+.. _recipe-driver-manager-duckdb:
+
Load a driver from a shared library (DuckDB)
============================================