lidavidm commented on code in PR #4525: URL: https://github.com/apache/arrow-adbc/pull/4525#discussion_r3583408638
########## docs/source/driver/authoring.rst: ########## @@ -19,20 +19,33 @@ Writing New Drivers =================== -Currently, new drivers can be written in C#, C/C++, Go, and Java. A driver -written in C/C++ or Go can be used from either of those languages, as well as -C#, Python, R, and Ruby. (C# can experimentally export drivers to the same -set of languages as well.) The Rust API definitions for ADBC are still under -development, but we plan for them to be on par with C#, C/C++, and Go in this -respect. +ADBC drivers can be written in C/C++, C#, Go, Java, or Rust. +Because drivers expose a :doc:`standard C ABI <../format/specification>`, a driver written in any of these languages can be used from client libraries in any other language — so the implementation language is largely a matter of ecosystem fit and preference. Review Comment: ```suggestion Because drivers expose a :doc:`standard C ABI <../format/specification>`, a driver written in any of these languages can be used from client libraries in any other language, so the implementation language is largely a matter of ecosystem fit and preference. ``` ########## docs/source/csharp/quickstart.rst: ########## @@ -0,0 +1,167 @@ +.. 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. + +========== +Quickstart +========== + +Here we'll briefly tour basic features of ADBC with C# using the PostgreSQL driver. + +Installation +============ + +.. code-block:: shell + + dotnet add package Apache.Arrow.Adbc.Client + +Basic Example +============= + +This example demonstrates connecting to a database, executing a query, and reading results using the ADO.NET-style API. + +.. code-block:: csharp + + using Apache.Arrow.Adbc.Client; + using System; + using System.Data.Common; + + class Program + { + static void Main() + { + // Create a connection string + string connectionString = "Driver=postgresql;uri=postgresql://user:password@localhost:5432/database"; + + using var connection = new AdbcConnection(connectionString); + connection.Open(); + + // Execute a query + using var command = connection.CreateCommand(); + command.CommandText = "SELECT * FROM my_table"; + + using var reader = command.ExecuteReader(); + while (reader.Read()) + { + // Access data using column index or name + Console.WriteLine($"Value: {reader[0]}"); + } + } + } + +Working with Arrow Data +======================= + +ADBC natively works with Apache Arrow data structures: + +.. code-block:: csharp + + using Apache.Arrow; + using Apache.Arrow.Adbc.Client; + + string connectionString = "Driver=postgresql;uri=postgresql://user:password@localhost:5432/database"; + + using var connection = new AdbcConnection(connectionString); + connection.Open(); + + using var command = connection.CreateCommand(); + command.CommandText = "SELECT * FROM my_table"; + + // Get results as Arrow data + using var reader = command.ExecuteReader(); + + // Process Arrow record batches + while (reader.Read()) + { + // Reader provides access to underlying Arrow data + for (int i = 0; i < reader.FieldCount; i++) + { + Console.WriteLine($"{reader.GetName(i)}: {reader.GetValue(i)}"); + } + } + +Executing Non-Query Commands +============================= + +For INSERT, UPDATE, DELETE, or DDL statements: + +.. code-block:: csharp + + using var connection = new AdbcConnection(connectionString); + connection.Open(); + + using var command = connection.CreateCommand(); + command.CommandText = "INSERT INTO my_table (id, name) VALUES (1, 'test')"; + + int rowsAffected = command.ExecuteNonQuery(); + Console.WriteLine($"Rows affected: {rowsAffected}"); + +Parameterized Queries +===================== + +Use parameterized queries for safe SQL execution: + +.. code-block:: csharp + + using var connection = new AdbcConnection(connectionString); + connection.Open(); + + using var command = connection.CreateCommand(); + command.CommandText = "SELECT * FROM my_table WHERE id = @id"; + + var parameter = command.CreateParameter(); + parameter.ParameterName = "@id"; + parameter.Value = 42; + command.Parameters.Add(parameter); + + using var reader = command.ExecuteReader(); + while (reader.Read()) + { + Console.WriteLine(reader[0]); + } + +Installing Drivers +================== + +You'll need to install an ADBC driver for the database you want to connect to. The easiest way is using `dbc <https://docs.columnar.tech/dbc>`_: Review Comment: Since this is repeated a lot, is there a way we can put this in a separate file and include it wherever we use it? ########## docs/source/driver/authoring.rst: ########## @@ -19,20 +19,33 @@ Writing New Drivers =================== -Currently, new drivers can be written in C#, C/C++, Go, and Java. A driver -written in C/C++ or Go can be used from either of those languages, as well as -C#, Python, R, and Ruby. (C# can experimentally export drivers to the same -set of languages as well.) The Rust API definitions for ADBC are still under -development, but we plan for them to be on par with C#, C/C++, and Go in this -respect. +ADBC drivers can be written in C/C++, C#, Go, Java, or Rust. +Because drivers expose a :doc:`standard C ABI <../format/specification>`, a driver written in any of these languages can be used from client libraries in any other language — so the implementation language is largely a matter of ecosystem fit and preference. -It is so far preferable to write new drivers in Go. C/C++ have had issues -with dependencies and in particular some not uncommon dependencies in that -ecosystem tend to cause conflicts when loaded into Python processes and -elsewhere. (For example, the ADBC Flight SQL driver was originally written in -C++ but would have conflicted with the grpcio and pyarrow Python packages.) -It also tends to be easier for us to package and distribute additional Go -libraries than it is for C/C++. +.. list-table:: + :header-rows: 1 + + * - Language + - Documentation + - Notes + * - C/C++ + - :doc:`../cpp/index` + - Drivers are loadable by the Driver Manager and usable from all client languages. + * - C# + - :doc:`../csharp/index` + - Can experimentally export drivers for use from other languages via the C ABI. + * - Go + - `go/adbc <https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc>`__ + - Recommended for new drivers; easiest to package and distribute. Drivers are loadable by the Driver Manager and usable from all client languages. + * - Java + - :doc:`../java/index` + - Drivers are usable from Java client libraries. + * - Rust + - :doc:`../rust/quickstart` + - API definitions are still maturing. Drivers can be compiled to a C ABI shared library for use from other languages. + +Go is generally the recommended choice for new drivers. +C/C++ drivers have historically had dependency conflicts (e.g. with grpcio or pyarrow in Python processes), whereas Go libraries are easier to package and distribute without conflict. Review Comment: ```suggestion C/C++ drivers have historically had dependency conflicts (e.g. with grpcio or pyarrow in Python processes), whereas Go and Rust libraries are easier to package and distribute without conflict. ``` ########## docs/source/python/quickstart.rst: ########## @@ -181,3 +181,26 @@ We can get the Arrow schema of a table: >>> conn.adbc_get_table_schema("sample") ints: int64 strs: string + +Installing Drivers +================== + +You'll need to install an ADBC driver for the database you want to connect to. The easiest way is using `dbc <https://docs.columnar.tech/dbc>`_: Review Comment: We should make it clear that this is a third party, and perhaps mention that drivers developed by us are still distributed on PyPI, with other drivers distributed by the third party ########## docs/source/java/quickstart.rst: ########## @@ -19,7 +19,7 @@ Quickstart ========== -Here we'll briefly tour basic features of ADBC with the PostgreSQL driver for Java. +Here we'll briefly tour basic features of ADBC with Java using the PostgreSQL driver. Review Comment: The current example does appear to use the JDBC adapter; maybe it should be switched to use the JNI adapter? ########## 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 +================ Review Comment: I think I asked this before but what is really the distinction between this and a 'driver manager'? I think it might be best to just call everything a 'driver manager' for consistency ########## 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: nit: are the extra horizontal rules actually useful? -- 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]
