From: Daniele Varrazzo Date: Tue, 7 Jun 2022 06:13:07 +0000 (+0200) Subject: docs(crdb): add crdb module docs X-Git-Tag: 3.1~49^2~19 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=15d35abd6408306a6484bcbf73679516081030f7;p=thirdparty%2Fpsycopg.git docs(crdb): add crdb module docs --- diff --git a/docs/api/crdb.rst b/docs/api/crdb.rst new file mode 100644 index 000000000..4d11614e0 --- /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 ` 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 a487c10b6..a53fed6e0 100644 --- 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 14a4b08f2..620905581 100644 --- 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 c6d00304e..74eea147d 100644 --- a/docs/news.rst +++ b/docs/news.rst @@ -15,6 +15,8 @@ Psycopg 3.1 (unreleased) - Add :ref:`Pipeline mode ` (:ticket:`#74`). - Add :ref:`client-side-binding-cursors` (:ticket:`#101`). +- Add `CockroachDB `__ support in `psycopg.crdb` + (:ticket:`#313`). - Add :ref:`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 f845e8255..273b78a2c 100644 --- 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 fa5936e3a..bde15fa17 100644 --- 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: