picopyn 2.0.0.dev1__tar.gz → 2.1.0__tar.gz

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/AUTHORS.md

@@ -2,4 +2,5 @@
 
 - Asya Lomakina <a.lomakina@picodata.io>
 - Igor Kuznetsov <i.kuznetsov@picodata.io>
-- Dmitriy Koltsov <dkoltsov@picodata.io>
+- Dmitriy Koltsov <dkoltsov@picodata.io>
+- Daniil Gorlyakov <d.gorlyakov@picodata.io>

{picopyn-2.0.0.dev1/picopyn.egg-info → picopyn-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: picopyn
-Version: 2.0.0.dev1
+Version: 2.1.0
 Summary: Python connector for working with the distributed Picodata database.
 Author-email: Asya Lomakina <a.lomakina@picodata.io>, Igor Kuznetsov <i.kuznetsov@picodata.io>, Dmitriy Koltsov <dkoltsov@picodata.io>, Daniil Gorlyakov <d.gorlyakov@picodata.io>
 License-Expression: BSD-2-Clause
@@ -55,7 +55,7 @@ Dynamic: license-file
 | >=25.2.1, <25.4.4 | 0.1.1             |
 | >=25.4.4, <25.5.1 | 0.2.0             |
 | >=25.5.1, <26.1.x | 1.0.0             |
-| >=26.1.1, <26.2.x | 2.0.0             |
+| >=26.1.1, <26.2.x | 2.0.0, 2.1.0      |
 | 26.2.x            | ⚠️ Unreleased yet |
 
 ## Features
@@ -64,8 +64,9 @@ Dynamic: license-file
 * Pluggable load-balancing strategies
 * Asynchronous API based on [asyncpg](https://github.com/MagicStack/asyncpg)
     * (async only) Shard-aware routing
-    * (async only) Automatic pool membership reconciliation
-* Synchronous [DPAPI-compatible](https://peps.python.org/pep-0249/) API based on [psycopg](https://www.psycopg.org/)
+    * (async only) Automatic pool membership reconciliation, including rebalancing a
+      full pool across the nodes
+* Synchronous [DB-API 2.0-compatible](https://peps.python.org/pep-0249/) API based on [psycopg](https://www.psycopg.org/)
 
 ## Navigation
 * [Installation](#installation)
@@ -97,24 +98,24 @@ Async:
 
 ```python
 import asyncio
-from picopyn.asynchronous import Client
+from picopyn.asynchronous import Pool
 
 async def main():
-    # create and connect client to the picodata cluster
-    client = Client(dsn="postgresql://admin:pass@localhost:5432")
-    await client.connect()
+    # create and open pool to the picodata cluster
+    pool = Pool(dsn="postgresql://admin:pass@localhost:5432", enable_discovery=True)
+    await pool.open()
 
     # execute DDL operations
-    await client.execute('''
+    await pool.execute('''
         CREATE TABLE "warehouse" (id INTEGER NOT NULL, item TEXT NOT NULL, PRIMARY KEY (id)) USING memtx DISTRIBUTED BY (id) OPTION (TIMEOUT = 3.0);
     ''')
 
     # execute DML/DQL operations
-    await client.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
-    rows = await client.fetch('SELECT * FROM "warehouse"')
+    await pool.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
+    rows = await pool.fetch('SELECT * FROM "warehouse"')
     print(rows)
 
-    await client.close()
+    await pool.close()
 
 asyncio.run(main())
 ```

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/README.md

@@ -12,7 +12,7 @@
 | >=25.2.1, <25.4.4 | 0.1.1             |
 | >=25.4.4, <25.5.1 | 0.2.0             |
 | >=25.5.1, <26.1.x | 1.0.0             |
-| >=26.1.1, <26.2.x | 2.0.0             |
+| >=26.1.1, <26.2.x | 2.0.0, 2.1.0      |
 | 26.2.x            | ⚠️ Unreleased yet |
 
 ## Features
@@ -21,8 +21,9 @@
 * Pluggable load-balancing strategies
 * Asynchronous API based on [asyncpg](https://github.com/MagicStack/asyncpg)
     * (async only) Shard-aware routing
-    * (async only) Automatic pool membership reconciliation
-* Synchronous [DPAPI-compatible](https://peps.python.org/pep-0249/) API based on [psycopg](https://www.psycopg.org/)
+    * (async only) Automatic pool membership reconciliation, including rebalancing a
+      full pool across the nodes
+* Synchronous [DB-API 2.0-compatible](https://peps.python.org/pep-0249/) API based on [psycopg](https://www.psycopg.org/)
 
 ## Navigation
 * [Installation](#installation)
@@ -54,24 +55,24 @@ Async:
 
 ```python
 import asyncio
-from picopyn.asynchronous import Client
+from picopyn.asynchronous import Pool
 
 async def main():
-    # create and connect client to the picodata cluster
-    client = Client(dsn="postgresql://admin:pass@localhost:5432")
-    await client.connect()
+    # create and open pool to the picodata cluster
+    pool = Pool(dsn="postgresql://admin:pass@localhost:5432", enable_discovery=True)
+    await pool.open()
 
     # execute DDL operations
-    await client.execute('''
+    await pool.execute('''
         CREATE TABLE "warehouse" (id INTEGER NOT NULL, item TEXT NOT NULL, PRIMARY KEY (id)) USING memtx DISTRIBUTED BY (id) OPTION (TIMEOUT = 3.0);
     ''')
 
     # execute DML/DQL operations
-    await client.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
-    rows = await client.fetch('SELECT * FROM "warehouse"')
+    await pool.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
+    rows = await pool.fetch('SELECT * FROM "warehouse"')
     print(rows)
 
-    await client.close()
+    await pool.close()
 
 asyncio.run(main())
 ```

picopyn-2.1.0/docs/css/deprecated.css

@@ -0,0 +1,21 @@
+/* mkdocstrings renders a docstring "Deprecated:" section as <details class="deprecated">.
+   That class is not part of Material's admonition set, so it falls back to the neutral
+   blue "note" look and deprecations read like ordinary remarks. Paint it as a warning. */
+
+.md-typeset details.deprecated {
+  border-color: #ff9100;
+}
+
+.md-typeset details.deprecated:focus-within {
+  box-shadow: 0 0 0 0.2rem #ff91001a;
+}
+
+.md-typeset details.deprecated > summary {
+  background-color: #ff91001a;
+}
+
+.md-typeset details.deprecated > summary::before {
+  background-color: #ff9100;
+  -webkit-mask-image: var(--md-admonition-icon--warning);
+  mask-image: var(--md-admonition-icon--warning);
+}

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/diagrams/_pool_init_discovery_disabled.md

@@ -17,7 +17,7 @@ ERROR([Initialization failed]):::error
 CFG[/"Pool settings<br>· DSN string<br>· pool size<br>· forbidden tiers<br>· cluster discovery disabled"/]
 
 GENERAL_DETAILS_NOTE>"Return to general algorithm"]:::note
-click GENERAL_DETAILS_NOTE "#picopyn.asynchronous.Pool.connect" "Return to general algorithm"
+click GENERAL_DETAILS_NOTE "#picopyn.asynchronous.Pool.open" "Return to general algorithm"
 
 %% === Data objects ===
 B_DSN[[DSN node list]]

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/diagrams/_pool_init_discovery_enabled.md

@@ -18,7 +18,7 @@ ERROR([Initialization failed]):::error
 CFG[/"Pool settings<br>· DSN string<br>· pool_size<br>· forbidden tiers<br>· cluster discovery enabled"/]
 
 GENERAL_DETAILS_NOTE>"Return to general algorithm"]:::note
-click GENERAL_DETAILS_NOTE "#picopyn.asynchronous.Pool.connect" "Return to general algorithm"
+click GENERAL_DETAILS_NOTE "#picopyn.asynchronous.Pool.open" "Return to general algorithm"
 
 %% === Data objects ===
 D_DSN[[DSN node list]]

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/diagrams/_pool_lifecycle.md

@@ -17,14 +17,14 @@ DONE([Pool closed]):::neutral
 
 CFG[/"Pool settings<br>· DSN<br>· pool size<br>· forbidden tiers<br>· cluster discovery mode"/]
 
-START --> CFG --> CREATE["Pool.__init__"] --> CONNECT["pool.connect()"] --> UsePool
+START --> CFG --> CREATE["Pool.__init__"] --> CONNECT["pool.open()"] --> UsePool
 CONNECT <-. write .-> POOL
 
-CONNECT_DETAILS_NOTE>"Connect algorithm details"]:::note
-click CONNECT_DETAILS_NOTE "#picopyn.asynchronous.Pool.connect" "Connect algorithm details"
+CONNECT_DETAILS_NOTE>"Open algorithm details"]:::note
+click CONNECT_DETAILS_NOTE "#picopyn.asynchronous.Pool.open" "Open algorithm details"
 CONNECT_DETAILS_NOTE -.-> CONNECT
 
-RECONCILE_NOTE>"(discovery mode only):<br>pool membership changes<br>in the background:<br>connections are opened/closed<br>to match topology changes"]:::note
+RECONCILE_NOTE>"pool membership changes<br>in the background:<br>connections are opened/closed<br>to match topology changes<br>(discovery mode: any cluster node,<br>bootstrap mode: DSN nodes only)"]:::note
 click RECONCILE_NOTE "#picopyn.asynchronous.Pool.topology" "Reconcile algorithm details"
 RECONCILE_NOTE -.-> POOL
 

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/diagrams/_query_metadata_pool_init.md

@@ -15,8 +15,8 @@ INIT --> CACHE_EMPTY["Create empty query meta cache"] --> CONNECT["Fill the pool
 NOTE_CONN>"connection options require<br>statement invalidation signal only"]:::note
 NOTE_CONN -.-> CONNECT
 
-CONNECT_DETAILS_NOTE>"Connect algorithm details"]:::note
-click CONNECT_DETAILS_NOTE "#picopyn.asynchronous.Pool.connect" "Connect algorithm details"
+CONNECT_DETAILS_NOTE>"Open algorithm details"]:::note
+click CONNECT_DETAILS_NOTE "#picopyn.asynchronous.Pool.open" "Open algorithm details"
 CONNECT_DETAILS_NOTE -.-> CONNECT
 
 subgraph Pool1["Pool"]

picopyn-2.1.0/docs/diagrams/_rebalance_pool_after_reconcile.md

@@ -0,0 +1,50 @@
+```mermaid
+---
+title: Rebalance pool after reconcile
+---
+flowchart TD
+
+classDef neutral fill:#f5f5f5,stroke:#9e9e9e,color:#424242
+classDef note fill:#fffde7,stroke:#f9a825,stroke-dasharray:4,color:#555
+classDef success fill:#e8f5e9,stroke:#4caf50,color:#1b5e20
+
+START(["START"]):::neutral --> COUNT
+
+COUNT_DETAILS_NOTE>"connections already marked<br>to evict are not counted:<br>they are closed on<br>release and refilled elsewhere"]:::note
+COUNT_DETAILS_NOTE -.-> COUNT
+
+COUNT_DETAILS_NOTE2>"candidate nodes are<br>online Picodata nodes<br>from allowed tiers"]:::note
+COUNT_DETAILS_NOTE2 -.-> COUNT
+
+COUNT["count free and in-use pool<br>connections per candidate uuid"] --> GAP
+
+GAP_DETAILS_NOTE>"a gap of one<br>is not an imbalance"]:::note
+GAP_DETAILS_NOTE -.-> GAP
+
+GAP{"gap between<br>max count and min count<br>(most overloaded and<br>most underloaded nodes)<br>>= 2?"}
+GAP -->|no| POOL_OK(["pool is balanced<br>(exit)"]):::success
+GAP -->|yes| FREE{"is there a free connection<br>to the overloaded uuid?"}
+
+FREE -->|no| EVICT_USED["mark one in-use connection<br>to the overloaded uuid to evict"]
+FREE -->|yes| MIGRATE["migrate one connection:<br>take the free one out, connect<br>to the underloaded uuid,<br>close the old one"]
+
+EVICT_DETAILS_NOTE>"release closes it, and the next<br>refresh refills the free slot to<br>the underloaded uuid"]:::note
+EVICT_DETAILS_NOTE -.-> EVICT_USED
+
+EVICT_USED --> POOL_OK3(["(exit)"]):::success
+
+MIGRATE -->|migrated| LIMIT
+MIGRATE -->|"could not connect to<br>the underloaded uuid"| EXCLUDE["put the connection back and<br>exclude the underloaded uuid<br>from the candidate list<br>in this reconcile"]
+EXCLUDE --> LIMIT
+
+LIMIT{"migration limit for<br>this reconcile reached?"}
+LIMIT -->|no| GAP
+LIMIT -->|yes| POOL_OK4(["(exit)"]):::success
+
+LIMIT_DETAILS_NOTE>"the limit is proportional to<br>the pool size, see<br>Pool.rebalance_pool_divisor"]:::note
+click LIMIT_DETAILS_NOTE "#picopyn.asynchronous.Pool" "Pool.rebalance_pool_divisor"
+LIMIT_DETAILS_NOTE -.-> LIMIT
+
+LIMIT_DETAILS_NOTE2>"the rest is left to<br>the next refresh"]:::note
+LIMIT_DETAILS_NOTE2 -.-> POOL_OK4
+```

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/diagrams/_reconcile_pool_with_topology.md

@@ -10,7 +10,6 @@ classDef success fill:#e8f5e9,stroke:#4caf50,color:#1b5e20
 classDef error fill:#ffebee,stroke:#f44336,color:#b71c1c
 
 subgraph Pool["Pool"]
-    Settings[/"forbidden tiers=[...]<br>max size=N"/]
     FreeConns["free conns=[...]"]
     UsedConns["used conns=[...]"]
     Topology[/"Topology"/]
@@ -25,14 +24,16 @@ TOPOLOGY_DETAILS_NOTE>"Topology details"]:::note
 click TOPOLOGY_DETAILS_NOTE "../topology/#picopyn.topology.Topology" "Topology details"
 TOPOLOGY_DETAILS_NOTE -.-> TOPOLOGY_APPLY
 
-TOPOLOGY_APPLY --> GET_LIST["build candidate_list from Topology:<br>- uuids with allowed tiers<br>- online uuids"]
+TOPOLOGY_APPLY --> COMPLETE{"topology has both<br>instances and replicasets?"}
+COMPLETE -->|no| NOT_TRUSTED(["snapshot is not trustworthy:<br>pool is left as is<br>(exit)"]):::error
+COMPLETE -->|yes| GET_LIST["build candidate_list from Topology:<br>- uuids with allowed tiers<br>- online uuids<br>- (bootstrap mode) only<br>DSN node addresses"]
 GET_LIST --> REMOVE["close all connections whose<br>uuid not in candidate_list"] --> CHECK_SIZE_START
 
 REMOVE -.-> FreeConns
 REMOVE -.-> UsedConns
 
 CHECK_SIZE_START{"current pool size < max size?"}
-CHECK_SIZE_START -->|no| POOL_OK(["Pool okay<br>(exit)"]):::success
+CHECK_SIZE_START -->|no| REBALANCE
 CHECK_SIZE_START -->|yes| MIN["choose uuid from candidate_list<br>with min connections count"]
 
 MIN -->|got candidate| ADD_CONN["try to connect to candidate<br>and add connection to pool..."]
@@ -41,6 +42,13 @@ MIN -->|no candidate| NO_CANDIDATE2(["pool is temporarily not<br>full until next
 ADD_CONN -->|connection failed| EXCLUDE["exclude the candidate uuid<br/>from list in this loop"] --> CHECK_SIZE_LOOP
 ADD_CONN-->|connected| CHECK_SIZE_LOOP{"current size < max size?"}
 
-CHECK_SIZE_LOOP -->|no| POOL_OK2(["Pool okay<br>(exit)"]):::success
+CHECK_SIZE_LOOP -->|no| REBALANCE
 CHECK_SIZE_LOOP -->|yes| MIN
+
+REBALANCE["rebalance the pool:<br>move connections from overloaded<br>nodes to underloaded ones"]
+REBALANCE --> POOL_OK(["Pool okay<br>(exit)"]):::success
+
+REBALANCE_DETAILS_NOTE>"Rebalance details"]:::note
+click REBALANCE_DETAILS_NOTE "#picopyn.asynchronous.Pool.topology--rebalance" "Rebalance details"
+REBALANCE_DETAILS_NOTE -.-> REBALANCE
 ```

picopyn-2.1.0/docs/diagrams/_reconcile_rebalance.md

@@ -0,0 +1,45 @@
+```mermaid
+---
+title: (Rebalance) a pooled node returned to Online (pool is already full)
+---
+
+flowchart TD
+
+classDef offline fill:#ffebee,stroke:#f44336,color:#b71c1c
+classDef online fill:#e8f5e9,stroke:#4caf50,color:#1b5e20
+classDef neutral fill:#f5f5f5,stroke:#9e9e9e,color:#424242
+
+classDef note fill:#fffde7,stroke:#f9a825,stroke-dasharray:4,color:#555
+
+subgraph before["Before"]
+    subgraph Picodata_before["Picodata"]
+        p1[("ins 1")]:::online
+        p2[("ins 2")]:::online
+        p3[("ins 3")]:::offline
+    end
+
+    subgraph Pool_before["Pool: max_size=6"]
+        c1["conn x3"] --> p1
+        c2["conn x3"] --> p2
+    end
+end
+EVENT1[/"Event<br>Instance 3 back Online"/]:::neutral -.-> REBALANCE{{"reconcile pool"}}
+before -.-> REBALANCE
+NOTE>"Pool is full, so refill<br>does nothing.<br>Initial connection counts:<br>[3/3/0], gap=3<br>=> migrate: [2/3/1], gap=2<br>=> migrate: [2/2/2], gap=0<br>Pool rebalanced in 2 refreshes"]:::note
+NOTE -.-> REBALANCE
+REBALANCE --> after
+
+subgraph after["After (2 refreshes)"]
+    subgraph Picodata_after["Picodata"]
+        p21[("ins 1")]:::online
+        p22[("ins 2")]:::online
+        p23[("ins 3")]:::online
+    end
+
+    subgraph Pool_after["Pool: max_size=6"]
+        c21["conn x2"] --> p21
+        c22["conn x2"] --> p22
+        c23["conn x2"] --> p23
+    end
+end
+```

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/diagrams/_topology_tracking.md

@@ -12,7 +12,7 @@ click ADR_DETAILS_NOTE "https://git.picodata.io/core/picodata/-/blob/master/doc/
 
 TOPOLOGY[[Topology<br>·instances<br>·replicasets<br>·buckets<br>·tiers]]
 
-CONNECT["Pool.connect()"] --> CFG[/"Topology tracker settings<br>· update interval"/] --> START["start topology tracker"] --> INITIAL["initial refresh<br>(sync, imitate ReadyForQuery)"] --> WAIT
+CONNECT["Pool.open()"] --> CFG[/"Topology tracker settings<br>· update interval"/] --> START["start topology tracker"] --> INITIAL["initial refresh<br>(sync, imitate ReadyForQuery)"] --> WAIT
 INITAL_DETAILS_NOTE>"Picodata doesn't send it yet,<br>but it's planned: Picodata will send<br>ReadyForQuery once the initial snapshot<br>is fully delivered -- meaning our<br>topology view is consistent"]:::note
 
 INITAL_DETAILS_NOTE -.-> INITIAL

picopyn-2.1.0/docs/explain.md

@@ -0,0 +1,21 @@
+# Explain
+
+::: picopyn.explain
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      heading_level: 1
+      members: []
+
+## API Reference
+
+::: picopyn.explain
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+      heading_level: 3
+      members_order: source
+      extra:
+        hide_docstring: true
+      filters:
+        - "!^_"

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/index.md

@@ -1,3 +1,6 @@
+[![Version](https://img.shields.io/pypi/v/picopyn.svg?maxAge=86400)](https://pypi.org/project/picopyn/)
+[![Supported Versions](https://img.shields.io/pypi/pyversions/picopyn.svg)](https://pypi.org/project/picopyn)
+
 # picopyn
 
 **picopyn** is a Python connector for working with the distributed [Picodata](https://picodata.io/en/) database.
@@ -9,7 +12,7 @@
 | >=25.2.1, <25.4.4 | 0.1.1             |
 | >=25.4.4, <25.5.1 | 0.2.0             |
 | >=25.5.1, <26.1.x | 1.0.0             |
-| >=26.1.1, <26.2.x | 2.0.0             |
+| >=26.1.1, <26.2.x | 2.0.0, 2.1.0      |
 | 26.2.x            | ⚠️ Unreleased yet |
 
 ## Features
@@ -19,8 +22,8 @@
 * Pluggable load-balancing strategies
 * Asynchronous API based on [asyncpg](https://github.com/MagicStack/asyncpg)
     * (async only) [Shard-aware routing][picopyn.asynchronous.pool.Pool.execute]
-    * (async only) Automatic [pool membership reconciliation][picopyn.asynchronous.pool.Pool.topology] according to picodata topology
-* Synchronous [DPAPI-compatible](https://peps.python.org/pep-0249/) API based on [psycopg](https://www.psycopg.org/)
+    * (async only) Automatic [pool membership reconciliation][picopyn.asynchronous.pool.Pool.topology] according to picodata topology, including rebalancing a full pool across the nodes
+* Synchronous [DB-API 2.0-compatible](https://peps.python.org/pep-0249/) API based on [psycopg](https://www.psycopg.org/)
 
 ## Quick start
 
@@ -32,22 +35,22 @@ Async:
 
 ```python
 import asyncio
-from picopyn.asynchronous import Client
+from picopyn.asynchronous import Pool
 
 async def main():
-    client = Client(dsn="postgresql://admin:pass@localhost:5432")
-    await client.connect()
+    pool = Pool(dsn="postgresql://admin:pass@localhost:5432", enable_discovery=True)
+    await pool.open()
 
-    await client.execute('''
+    await pool.execute('''
         CREATE TABLE "warehouse" (id INTEGER NOT NULL, item TEXT NOT NULL, PRIMARY KEY (id))
         USING memtx DISTRIBUTED BY (id) OPTION (TIMEOUT = 3.0);
     ''')
 
-    await client.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
-    rows = await client.fetch('SELECT * FROM "warehouse"')
+    await pool.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
+    rows = await pool.fetch('SELECT * FROM "warehouse"')
     print(rows)
 
-    await client.close()
+    await pool.close()
 
 asyncio.run(main())
 ```

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/installation.md

@@ -4,7 +4,7 @@
 
 - Python 3.10+
 
-## Install from PyPI
+## Install from [PyPI](https://pypi.org/project/picopyn/)
 
 ```sh
 pip install picopyn

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/docs/sync.md

@@ -2,10 +2,10 @@
 
 ::: picopyn.synchronous
     options:
-      members:
-        - connect
-        - Connection
-        - Cursor
+      filters:
+        - "!^_[^_]"
+        - "!Error$"
+        - "!^Warning$"
 
 ### Errors
 

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/picopyn/asynchronous/client.py

@@ -2,6 +2,7 @@ from collections.abc import Callable
 from typing import Any
 
 import asyncpg
+from typing_extensions import deprecated
 
 from picopyn.explain import ExplainPlan, ExplainRawPlan
 
@@ -9,9 +10,16 @@ from .connection import Connection
 from .pool import Pool
 
 
+@deprecated(
+    "picopyn.asynchronous.Client is deprecated and will be removed in the next major release, use picopyn.asynchronous.Pool instead"
+)
 class Client:
     """Async client for managing connections to a picodata cluster using a connection pool.
 
+    Deprecated:
+        This class will be removed in the next major release.
+        Use [picopyn.asynchronous.Pool][picopyn.asynchronous.Pool] instead.
+
     This client handles connection pooling, automatic cluster node discovery,
     and supports load balancing strategies for query distribution. See details about [Pool][picopyn.asynchronous.Pool].
 
@@ -94,7 +102,7 @@ class Client:
             await client.connect()
             ```
         """
-        await self._pool.connect()
+        await self._pool.open()
 
     async def execute(self, query: str, *args: Any) -> str:
         """Executes a query that does not return rows (e.g. INSERT, UPDATE, DELETE).

{picopyn-2.0.0.dev1 → picopyn-2.1.0}/picopyn/asynchronous/connection.py

@@ -21,29 +21,54 @@ from picopyn.query_metadata import (
     parse_query_metadata_notice,
 )
 from picopyn.ssl import validate_ssl_source
-from picopyn.utils import _redact_dsn
+from picopyn.utils import _dsn_options, _redact_dsn
 
 
 def _with_picodata_startup_options(
-    connect_kwargs: dict[str, Any], *, request_query_metadata: bool
+    connect_kwargs: dict[str, Any], dsn: str, *, request_query_metadata: bool
 ) -> dict[str, Any]:
     """Append Picodata-specific startup options to `server_settings["options"]`,
-    without discarding options the caller already set.
+    without discarding options the caller already set in `connect_kwargs` or in the DSN.
+
+    Both `connect_kwargs` and the DSN can carry an `options` value. asyncpg merges the
+    DSN query params into `server_settings` and resolves the conflict per key in favor of
+    `connect_kwargs`, so a `server_settings["options"]` passed as a keyword argument
+    replaces the DSN one entirely.
+
+    In the example below `sql_vdbe_opcode_max` never reaches the server -- only the
+    Picodata options do:
+    ```python
+    dsn = "postgresql://user:pass@host1:5432/db?options=sql_vdbe_opcode_max%3D1"
+    asyncpg.connect(dsn, server_settings={"options": picodata_options})
+    ```
+
+    So, to keep the caller's options and the driver functionality:
+
+    - if `connect_kwargs` already sets `server_settings["options"]`, the Picodata options
+      are appended to it -- the DSN `options` would be discarded by asyncpg anyway;
+    - otherwise the value is taken from the DSN, so it survives the keyword argument this
+      function builds;
+    - the Picodata options are appended last on purpose => even if the caller tries to turn
+      it off, the last value of a repeated option is kept.
 
     Args:
-        connect_kwargs: Keyword arguments originally passed to [connect][picopyn.asynchronous.connection.Connection.connect].
+        connect_kwargs: Keyword arguments originally passed to
+            [connect][picopyn.asynchronous.connection.Connection.connect].
+        dsn: The DSN the connection is about to be opened with; only its `options` query
+            parameter is read.
         request_query_metadata: Whether to also [request query metadata][picopyn.query_metadata.QUERY_METADATA_OPTION],
-            in addition to [statements invalidation option][picopyn.query_metadata.STMT_INVALIDATION_OPTION] (always requested).
+            in addition to [statements invalidation option][picopyn.query_metadata.STMT_INVALIDATION_OPTION]
+            (always requested).
 
     Returns:
-        A copy of the original arguments with the merged Picodata pgproto options.
+        A copy of `connect_kwargs` with the merged Picodata pgproto options.
     """
     options = STMT_INVALIDATION_OPTION
     if request_query_metadata:
         options = f"{options},{QUERY_METADATA_OPTION}"
 
     server_settings = dict(connect_kwargs.get("server_settings") or {})
-    existing_options = server_settings.get("options")
+    existing_options = server_settings.get("options") or _dsn_options(dsn)
     server_settings["options"] = f"{existing_options},{options}" if existing_options else options
     return {**connect_kwargs, "server_settings": server_settings}
 
@@ -120,7 +145,9 @@ class Connection:
             await self.close()
 
         connect_kwargs = _with_picodata_startup_options(
-            self._connect_kwargs, request_query_metadata=self._on_query_metadata is not None
+            self._connect_kwargs,
+            self._connect_dsn,
+            request_query_metadata=self._on_query_metadata is not None,
         )
         try:
             self.conn = await asyncpg.connect(self._connect_dsn, **connect_kwargs)
@@ -315,9 +342,18 @@ class Connection:
         Returns:
             ExplainPlan for plain EXPLAIN or ExplainRawPlan for RAW mode.
 
+        Raises:
+            RuntimeError: If executing EXPLAIN fails or its output cannot be parsed. See
+                [`parse_plain_explain_lines()`][picopyn.explain.parse_plain_explain_lines]
+                and [`parse_raw_explain_lines()`][picopyn.explain.parse_raw_explain_lines]
+                for the underlying parsing functions and their errors.
+
         Examples:
             ```python
-            plan = await conn.explain("SELECT * FROM warehouse")
+            plan = await conn.explain(
+                'SELECT * FROM "warehouse" WHERE id = $1',
+                1,
+            )
             raw_plan = await conn.explain("SELECT * FROM warehouse", raw=True)
             ```
         """