From 8d935b0be053134993f4b4d98602d2b5def1d83f Mon Sep 17 00:00:00 2001
From: David Li
Date: Tue, 30 Apr 2024 23:56:05 +0900
Subject: [PATCH] docs: update driver status table (#1797)
Fixes #1786.
---
docs/source/driver/postgresql.rst | 9 +++++++++
docs/source/driver/status.rst | 22 ++++++++++++++--------
2 files changed, 23 insertions(+), 8 deletions(-)
diff --git a/docs/source/driver/postgresql.rst b/docs/source/driver/postgresql.rst
index c76534d202..8ba54a0134 100644
--- a/docs/source/driver/postgresql.rst
+++ b/docs/source/driver/postgresql.rst
@@ -165,6 +165,15 @@ The PostgreSQL driver mostly supports features defined in the ADBC API
specification 1.0.0, but not all cases are fully implemented
(particularly around bind parameters and prepared statements).
+Bind Parameters and Prepared Statements
+---------------------------------------
+
+The PostgreSQL driver only supports executing prepared statements with
+parameters that do not return result sets (basically, an INSERT with
+parameters). Queries that return result sets are difficult with prepared
+statements because the driver is built around using COPY for best
+performance, which is not supported in this context.
+
Bulk Ingestion
--------------
diff --git a/docs/source/driver/status.rst b/docs/source/driver/status.rst
index 7337dd4e82..b25f2f492a 100644
--- a/docs/source/driver/status.rst
+++ b/docs/source/driver/status.rst
@@ -24,7 +24,7 @@ Implementation Status
**Experimental** drivers are not feature-complete and the implementation is still progressing.
**Beta** drivers are (mostly) feature-complete but have only been available for a short time.
-**Stable** drivers are feature-complete (as much as possible for the underlying database) and have been available/tested for a while.
+**Stable** drivers are (mostly) feature-complete (as much as possible for the underlying database) and have been available/tested for a while.
.. list-table::
:header-rows: 1
@@ -42,7 +42,7 @@ Implementation Status
* - Flight SQL (Go)
- C, Go
- Go
- - Beta
+ - Stable
* - Flight SQL (Java)
- Java
@@ -57,17 +57,17 @@ Implementation Status
* - PostgreSQL
- C
- C++
- - Beta
+ - Stable
* - SQLite
- C
- C
- - Beta
+ - Stable
* - Snowflake
- C, Go
- Go
- - Experimental
+ - Stable
.. [#supported-languages] C drivers are usable from Go, Python, and Ruby as well.
@@ -183,7 +183,7 @@ Update Queries
* - PostgreSQL
- N/A
- N/A
- - Y
+ - Y [#postgresql-prepared]_
- Y
- Y
- Y
@@ -196,6 +196,12 @@ Update Queries
- Y
- Y
+.. [#postgresql-prepared] The PostgreSQL driver only supports executing
+ prepared statements with parameters that do not return result sets
+ (basically, an INSERT with parameters). Queries that return result sets
+ are difficult with prepared statements because the driver is built around
+ using COPY for best performance, which is not supported in this context.
+
.. list-table:: Connection/database-level features
:header-rows: 1
@@ -207,7 +213,7 @@ Update Queries
* - Flight SQL (Go)
- N
- Y
- - N
+ - Y
* - Flight SQL (Java)
- Y
@@ -222,7 +228,7 @@ Update Queries
* - PostgreSQL
- Y
- Y
- - N
+ - Y
* - SQLite
- Y