docs(crdb): add crdb module docs

diff --git a/docs/api/crdb.rst b/docs/api/crdb.rst
new file mode 100644 (file)
index 0000000..4d11614
--- /dev/null
+++ b/docs/api/crdb.rst
@@ -0,0 +1,112 @@
+`crdb` -- CockroachDB support
+=============================
+
+.. module:: psycopg.crdb
+
+.. versionadded:: 3.1
+
+CockroachDB_ is a distributed database using the same fronted-backend protocol
+of PostgreSQL. As such, Psycopg can be used to write Python programs
+interacting with CockroachDB.
+
+.. _CockroachDB: https://www.cockroachlabs.com/
+
+Opening a connection to a CRDB database using `psycopg.connect()` provides a
+largely working object. However, using the `psycopg.crdb.connect()` function
+instead, Psycopg will create more specialised objects and provide a types
+mapping tweaked on the CockroachDB data model.
+
+
+.. _crdb-differences:
+
+Main differences from PostgreSQL
+--------------------------------
+
+CockroachDB behaviour is `different from PostgreSQL`__: please refer to the
+database documentation for details. These are some of the main differences
+affecting Psycopg behaviour:
+
+.. __: https://www.cockroachlabs.com/docs/stable/postgresql-compatibility.html
+
+
+- `~psycopg.Connection.cancel()` doesn't work. You can use `CANCEL QUERY`_
+  instead (from a different connection). TODOCRDB: possibly supported in 22.1.
+- `~psycopg.ConnectionInfo.backend_pid` doesn't return useful info. You can
+  use `SHOW SESSIONS`_ to find a session id which you may use with `CANCEL
+  SESSION`_ in lieu of PostgreSQL's :sql:`pg_terminate_backend()`.
+- Several data types are missing or slightly different from PostgreSQL (see
+  `adapters` for an overview of the differences).
+- The :ref:`two-phase commit protocol <two-phase-commit>` is not supported.
+- :sql:`LISTEN` and :sql:`NOTIFY` are not supported. However the `CHANGEFEED`_
+  command, in conjunction with `~psycopg.Cursor.stream()`, can provide push
+  notifications.
+
+.. _CANCEL QUERY: https://www.cockroachlabs.com/docs/stable/cancel-query.html
+.. _SHOW SESSIONS: https://www.cockroachlabs.com/docs/stable/show-sessions.html
+.. _CANCEL SESSION: https://www.cockroachlabs.com/docs/stable/cancel-session.html
+.. _CHANGEFEED: https://www.cockroachlabs.com/docs/stable/changefeed-for.html
+
+
+.. _crdb-objects:
+
+CockroachDB-specific objects
+----------------------------
+
+.. autofunction:: connect
+
+   This is an alias of the class method `CrdbConnection.connect`.
+
+   If you need an asynchronous connection use the `AsyncCrdbConnection.connect()`
+   method instead.
+
+
+.. autoclass:: CrdbConnection
+
+    `psycopg.Connection` subclass.
+
+
+.. autoclass:: AsyncCrdbConnection
+
+    `psycopg.AsyncConnection` subclass.
+
+
+.. autoclass:: CrdbConnectionInfo
+
+    The object is returned by the `!info` attribute of `CrdbConnection` and
+    `AsyncCrdbConnection`.
+
+    The object behaves like the `!ConnectionInfo`, with the following
+    differences:
+
+    .. autoattribute:: vendor
+
+        The `CockroachDB` string.
+
+    .. autoattribute:: server_version
+
+    .. attribute:: backend_pid
+
+        Always 0 as not reported by CockroachDB.
+
+
+.. data:: adapters
+
+    The default adapters map establishing how Python and CockroachDB types are
+    converted into each other.
+ 
+    The map is used as a template when new connections are created, using
+    `psycopg.crdb.connect()`.
+
+    This registry contains only the types and adapters supported by
+    CockroachDB. Several PostgreSQL types and adapters are missing or
+    different from PostgreSQL, among which:
+
+    - Composite types
+    - :sql:`range`, :sql:`multirange` types
+    - The :sql:`hstore` type
+    - Geometric types
+    - Nested arrays
+    - Arrays of :sql:`jsonb`
+    - The :sql:`cidr` data type
+    - The :sql:`json` type is an alias for :sql:`jsonb`
+    - The :sql:`int` type is an alias for :sql:`int8`, not `int4`.

diff --git a/docs/api/index.rst b/docs/api/index.rst
index a487c10b6669c64315c3adf9be3f41adb947caec..a53fed6e0f11f8eb4122816abb17addfde4aaf51 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -24,4 +24,5 @@ This sections is a reference for all the public objects exposed by the
     types
     abc
     pq
+    crdb
     dns

diff --git a/docs/api/objects.rst b/docs/api/objects.rst
index 14a4b08f25cca479ecb5d5805fc13f1489192457..62090558114944570d4a7d7c3fd8657d72229352 100644 (file)
--- a/docs/api/objects.rst
+++ b/docs/api/objects.rst
@@ -37,6 +37,13 @@ Connection information
     .. autoattribute:: pipeline_status
 
     .. autoattribute:: backend_pid
+    .. autoattribute:: vendor
+
+        Normally it is `PostgreSQL`; it may be different if connected to
+        a different database.
+
+        .. versionadded:: 3.1
+
     .. autoattribute:: server_version
 
         The number is formed by converting the major, minor, and revision

diff --git a/docs/news.rst b/docs/news.rst
index c6d00304eb017d5226a12cbe31fa201313934386..74eea147d1ec469881e6c62e0ceee285b90f359b 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -15,6 +15,8 @@ Psycopg 3.1 (unreleased)
 
 - Add :ref:`Pipeline mode <pipeline-mode>` (:ticket:`#74`).
 - Add :ref:`client-side-binding-cursors` (:ticket:`#101`).
+- Add `CockroachDB <https://www.cockroachlabs.com/>`__ support in `psycopg.crdb`
+  (:ticket:`#313`).
 - Add :ref:`Two-Phase Commit <two-phase-commit>` support (:ticket:`#72`).
 - Add :ref:`adapt-enum` (:ticket:`#274`).
 - Add ``returning`` parameter to `~Cursor.executemany()` to retrieve query

diff --git a/psycopg/psycopg/conninfo.py b/psycopg/psycopg/conninfo.py
index f845e825565bbc70ceeea6bf61f8bda9c17cb089..273b78a2c90a7b4b75d34c8c7bcf597f5d5b6376 100644 (file)
--- a/psycopg/psycopg/conninfo.py
+++ b/psycopg/psycopg/conninfo.py
@@ -126,6 +126,7 @@ class ConnectionInfo:
 
     @property
     def vendor(self) -> str:
+        """A string representing the database vendor connected to."""
         return "PostgreSQL"
 
     @property

diff --git a/psycopg/psycopg/crdb/connection.py b/psycopg/psycopg/crdb/connection.py
index fa5936e3a8a920334a9df9463e7ed9a851d3907d..bde15fa173fa53580da2cc017a868aae38268507 100644 (file)
--- a/psycopg/psycopg/crdb/connection.py
+++ b/psycopg/psycopg/crdb/connection.py
@@ -151,7 +151,7 @@ class AsyncCrdbConnection(_CrdbConnectionMixin, AsyncConnection[Row]):
 
 class CrdbConnectionInfo(ConnectionInfo):
     """
-    `~psycopg.ConnectionInfo` subclass to get info about a CockroachDB database.
+    `~psycopg.ConnectionInfo` subclass to get specific info on a CockroachDB database.
     """
 
     __module__ = "psycopg.crdb"
@@ -165,7 +165,7 @@ class CrdbConnectionInfo(ConnectionInfo):
         """
         Return the CockroachDB server version connected.
 
-        Return a number in the PostgreSQL format (e.g. 21.2.10 -> 200210)
+        Return a number in the PostgreSQL format (e.g. 21.2.10 -> 210210)
         """
         sver = self.parameter_status("crdb_version")
         if not sver: