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) ============================================