lidavidm commented on code in PR #4525: URL: https://github.com/apache/arrow-adbc/pull/4525#discussion_r3583698374
########## docs/source/client_libraries.rst: ########## @@ -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. + +================ +Client Libraries +================ + +ADBC client libraries let you connect to databases and execute queries from your language or languages of choice. +Because all ADBC :doc:`drivers <driver/index>` expose the same :doc:`standard C ABI <format/specification>`, a single client library can generally use drivers written any language using the same client API. + +The client libraries in a particular language always provide bindings to the ADBC API and most also offer a driver manager. + +Quick Start +=========== + +Get started with ADBC in your language of choice: + +.. tab-set:: + + .. tab-item:: Python + + .. code-block:: bash + + pip install adbc-driver-manager + + See the :doc:`Python Quickstart <python/quickstart>` for usage instructions. + + .. tab-item:: C/C++ + + See the :doc:`C/C++ Quickstart <cpp/quickstart>` for installation and usage instructions. + + .. tab-item:: C# + + .. code-block:: bash + + dotnet add package Apache.Arrow.Adbc.Client + + See the :doc:`C# Quickstart <csharp/quickstart>` for usage instructions. + + .. tab-item:: Go + + .. code-block:: bash + + go get github.com/apache/arrow-adbc/go/adbc + + See the `Go Documentation <https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc>`_ for usage instructions. + + .. tab-item:: Java + + .. code-block:: xml + + <dependency> + <groupId>org.apache.arrow.adbc</groupId> + <artifactId>adbc-driver-manager</artifactId> + </dependency> + + See the :doc:`Java Quickstart <java/quickstart>` for usage instructions. + + .. tab-item:: JavaScript + + .. code-block:: bash + + npm install @apache-arrow/adbc-driver-manager + + See the :doc:`JavaScript Quickstart <javascript/quickstart>` for usage instructions. + + .. tab-item:: R + + .. code-block:: r + + install.packages("adbcdrivermanager") + + See the :doc:`R Quickstart <r/quickstart>` for usage instructions. + + .. tab-item:: Ruby + + .. code-block:: bash + + bundle add red-adbc + + See the :doc:`Ruby Quickstart <ruby/quickstart>` for usage instructions. + + .. tab-item:: Rust + + .. code-block:: bash + + cargo add arrow-adbc Review Comment: Shouldn't this be `adbc_core`? ########## docs/source/integrations.rst: ########## @@ -0,0 +1,278 @@ +.. 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. + +==================== +Tools & Integrations +==================== + +ADBC works alongside many popular data tools and frameworks. This page describes how ADBC fits into each ecosystem. + +---- + +.. _dbc: + +dbc +=== Review Comment: There's some CSS rule that's making h2 headings smaller than they should be...that might be why we're lacking some visual separation between sections here ########## docs/source/driver/alt1.rst: ########## Review Comment: I think I like this one best Maybe language could also be a badge? Docs/source could be footer links? ########## docs/source/integrations.rst: ########## Review Comment: How is this page sorted? ########## docs/source/index.rst: ########## @@ -40,190 +40,264 @@ Apache Arrow ADBC **Cross-language**, **Arrow-native** database access. ADBC is a set of APIs and libraries for Arrow-native access to databases. -Execute SQL and Substrait_ queries, query database catalogs, and more, all +Execute SQL queries, insert bulk data, query database catalogs, and more, all using Arrow data to eliminate unnecessary data copies, speed up access, and make it more convenient to build analytical applications. +Getting Started +--------------- + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`plug` Available Drivers + :link: driver/index + :link-type: doc + + Connect to a growing list of databases using ADBC drivers. + + .. grid-item-card:: :octicon:`code` Client Libraries + :link: client_libraries + :link-type: doc + + Use ADBC from C/C++, C#, Go, Java, JavaScript, Python, R, Ruby, and Rust. + + .. grid-item-card:: :octicon:`tools` Building Drivers + :link: driver/authoring + :link-type: doc + + Build your own ADBC driver using the driver SDKs available in multiple languages. + + +.. _dbc: https://docs.columnar.tech/dbc .. _Substrait: https://substrait.io/ -.. div:: +Why ADBC? +--------- - .. grid:: - :margin: 4 4 0 0 - :gutter: 1 +.. grid:: 1 2 2 2 + :margin: 4 4 0 0 + :gutter: 1 - .. grid-item-card:: - :columns: 12 12 4 4 + .. grid-item-card:: Arrow-native + :link: https://arrow.apache.org/ - Quickstart - ^^^ + Execute queries and get back results in Arrow format, eliminating extra + data copies for Arrow-native backends. - Get started with simple examples in your language of choice. + +++ + Learn about Apache Arrow - +++ + .. grid-item-card:: Backend-agnostic + :link: driver/status + :link-type: doc - .. button-ref:: cpp/quickstart - :ref-type: doc - :color: secondary - :expand: + Connect to all kinds of databases, even ones that aren't Arrow-native. + ADBC drivers optimize conversion to/from Arrow where required, saving + work for developers. + + +++ + See Supported Drivers - C/C++ + .. grid-item-card:: Cross-language - .. button-link:: https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc - :color: secondary - :expand: + Work in C/C++, C#, Go, Java, Python, R, Ruby, Rust, and more. - Go + .. grid-item-card:: Full-featured - .. button-ref:: java/quickstart - :ref-type: doc - :color: secondary - :expand: + Execute SQL and Substrait, query database catalogs, inspect table + schemas, and more. ADBC handles common tasks without having to pull in + another database client. - Java + .. grid-item-card:: Language-native - .. button-ref:: javascript/index - :ref-type: doc - :color: secondary - :expand: + Use language-native APIs that you're already familiar with, like DBAPI + in Python, ``database/sql`` in Go, or DBI in R. - JavaScript +More Resources +-------------- - .. button-ref:: python/quickstart - :ref-type: doc - :color: secondary - :expand: +.. grid:: 1 2 2 2 + :margin: 4 4 0 0 + :gutter: 1 - Python + .. grid-item-card:: Examples & Tutorials + :link: https://github.com/columnar-tech/adbc-quickstarts - .. button-ref:: r/index - :ref-type: doc - :color: secondary - :expand: + Working examples and tutorials for multiple languages and databases in the `adbc-quickstarts repository <https://github.com/columnar-tech/adbc-quickstarts>`_. - R + +++ + :octicon:`cross-reference` View on GitHub - .. button-ref:: rust/quickstart - :ref-type: doc - :color: secondary - :expand: + .. grid-item-card:: Tools & Integrations Review Comment: Ideally these would all be "full card" links ########## docs/source/driver/alt1.rst: ########## Review Comment: Or language could be omitted, and the language-specific drivers for Flight SQL could be banished to a separate section. ########## docs/source/driver/index.rst: ########## Review Comment: Do we even need this page? Or the drivers table should instead be replaced by alt1.rst ########## docs/source/integrations.rst: ########## @@ -0,0 +1,278 @@ +.. 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. + +==================== +Tools & Integrations +==================== + +ADBC works alongside many popular data tools and frameworks. This page describes how ADBC fits into each ecosystem. + +---- + +.. _dbc: + +dbc +=== + +`dbc <https://docs.columnar.tech/dbc>`_ is a command-line tool from `Columnar <https://columnar.tech>`_ for installing and managing ADBC drivers on your system. It handles downloading driver binaries, placing them in standard locations, and keeping them up to date — so you don't have to build drivers from source or manage shared libraries by hand. + +Installation +------------ + +.. tab-set:: + + .. tab-item:: macOS / Linux (shell) + + .. code-block:: bash + + curl -LsSf https://dbc.columnar.tech/install.sh | sh + + .. tab-item:: Homebrew + + .. code-block:: bash + + brew install columnar-tech/tap/dbc + + .. tab-item:: uv + + .. code-block:: bash + + uv tool install dbc + + .. tab-item:: pipx + + .. code-block:: bash + + pipx install dbc + + .. tab-item:: Windows (PowerShell) + + .. code-block:: powershell + + powershell -ExecutionPolicy ByPass -c "irm https://dbc.columnar.tech/install.ps1 | iex" + + .. tab-item:: Windows (winget) + + .. code-block:: bash + + winget install dbc + +Usage +----- + +Once installed, use ``dbc install`` to add a driver, and ``dbc list`` to see what is available: + +.. code-block:: bash + + # Install a driver for a specific database + dbc install postgresql + dbc install snowflake + dbc install sqlite + + # List available and installed drivers + dbc list + +After a driver is installed, ADBC client libraries (and tools like DuckDB's ``adbc`` extension) can load it automatically by name. + +See the `dbc documentation <https://docs.columnar.tech/dbc>`_ for the full list of available drivers and advanced usage. + +---- + +DuckDB +====== + +`DuckDB <https://duckdb.org>`_ integrates with ADBC in two ways: + +1. **DuckDB itself is an ADBC driver** — DuckDB (technically libduckdb) exposes an ADBC interface so you can connect to a DuckDB database from any ADBC client library. See :doc:`driver/duckdb` for details on using DuckDB as an ADBC driver. +2. **DuckDB extensions** — Two DuckDB community extensions, `adbc <https://duckdb.org/community_extensions/extensions/adbc.html>`_ and `adbc_scanner <https://duckdb.org/community_extensions/extensions/adbc_scanner>`_, let you query *other* databases from DuckDB using ADBC drivers. + +---- + +databow +======= + +`databow <https://docs.columnar.tech/databow/>`_ is a command-line tool for querying databases via ADBC. It provides an interactive SQL shell with syntax highlighting, formatted output, and support for exporting results to JSON, CSV, or Arrow IPC files. + +**Highlights:** + +- Interactive SQL shell with command history and navigation +- Syntax highlighting for SQL queries +- Formatted table output with dynamic column widths +- Export results to JSON, CSV, or Arrow IPC formats +- Fast and lightweight (built in Rust) + +**Installation:** + +.. code-block:: bash + + # Install with uv + uv tool install databow + + # Install with Cargo + cargo install databow + +**Usage:** + +.. code-block:: bash + + # Interactive mode + databow --driver duckdb + + # Execute a query and exit + databow --driver duckdb --query "SELECT 42 AS the_answer" + + # Export results to a file + databow --driver duckdb --query "SELECT * FROM orders" --output results.json + +See the `databow documentation <https://docs.columnar.tech/databow/>`_ for more details. + +---- Review Comment: Hmm, looking at the rendered page, it does seem useful. But we should fix the CSS rule making h2 smaller than it should be. ########## docs/source/index.rst: ########## @@ -40,190 +40,264 @@ Apache Arrow ADBC **Cross-language**, **Arrow-native** database access. ADBC is a set of APIs and libraries for Arrow-native access to databases. -Execute SQL and Substrait_ queries, query database catalogs, and more, all +Execute SQL queries, insert bulk data, query database catalogs, and more, all using Arrow data to eliminate unnecessary data copies, speed up access, and make it more convenient to build analytical applications. +Getting Started +--------------- + +.. grid:: 1 1 2 3 + :gutter: 3 + + .. grid-item-card:: :octicon:`plug` Available Drivers + :link: driver/index + :link-type: doc + + Connect to a growing list of databases using ADBC drivers. Review Comment: Maybe these need some bottom text to make it clear that they're links? That said the cards below have the same problem IMO. The theme doesn't color the links which I think should/could be rectified ########## docs/source/index.rst: ########## @@ -40,190 +40,264 @@ Apache Arrow ADBC **Cross-language**, **Arrow-native** database access. ADBC is a set of APIs and libraries for Arrow-native access to databases. -Execute SQL and Substrait_ queries, query database catalogs, and more, all +Execute SQL queries, insert bulk data, query database catalogs, and more, all using Arrow data to eliminate unnecessary data copies, speed up access, and make it more convenient to build analytical applications. +Getting Started +--------------- Review Comment: I don't know if we even need this heading, TBH -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
