Skip to content

Changelog

[2.0.0] - 12.08.2026

⚠ BREAKING CHANGES

  • [GL-63] GL-63: deps!: bump minimum supported picodata version to 25.5.1

We're adding bucket map collection to the topology, which relies on the _pico_bucket function, supported starting with Picodata 25.5.1: https://docs.picodata.io/picodata/devel/reference/sql/system_functions/#_pico_bucket

  • [GL-64] GL-64: deps!: bump minimum supported picodata version to 26.1.1

We implemented the client side of Picodata's query metadata protocol https://git.picodata.io/core/picodata/-/blob/master/doc/adr/2025-09-12-pgproto-query-metadata.md

The protocol is available starting with Picodata 26.1.1.

Features

  • [GL-59] feat(sync): support client.

  • [GL-70] feat(sync): close connections via context manager.

  • [GL-63] feat(async): collect bucket map to topology. Topology now tracks bucket distribution: bucket ranges are polled via Picodata's _pico_bucket(tier) scalar function: https://docs.picodata.io/picodata/devel/reference/sql/system_functions/#_pico_bucket Its result converted into BucketEvents applied the same way as instance/replicaset events, per the topology notifications ADR: https://git.picodata.io/core/picodata/-/blob/master/doc/adr/2025-09-12-pgproto-topology-notifications.md

  • [GL-66] feat: support uuid field in connection.

  • [GL-64] feat(async): cache picodata's insert-query sharding meta. Implements the client side of Picodata's query metadata protocol https://git.picodata.io/core/picodata/-/blob/master/doc/adr/2025-09-12-pgproto-query-metadata.md

A dedicated connection (QueryMetadataService) requests query disctribution meta and keeps a pool-level cache, invalidated on Picodata's stale-plan signal (SQLSTATE 42999). Currently meta is only ever populated for INSERT (https://git.picodata.io/core/picodata/-/issues/2226)

Also adds a public Connection.prepare(), relying on asyncpg's own built-in statement cache -- a separate concern from the meta-cache introduced here.

bucket_id computation/routing based on is future work.

  • [GL-68] feat(async): add to_evict processing.

  • [GL-65] feat: support calculate_bucket_id function. Implement picopyn.bucket.calculate_bucket_id that can calculate query's bucket_id by its metadata (tier name and param-names) and bound parameters (specific values). MessagePack-encode each distribution-key parameter, concatenate, hash with MurmurHash, then reduce mod bucket_count if target tier.

Support the scalar SQL types Picodata (int/double/datetime/etc) and its combinations (composite sharding key) as a distribution key.

New function will allow us to route queries to specific Picodata instance

Based on the Picodata bucket_id calculation algorithm: https://git.picodata.io/core/picodata/-/blob/master/doc/adr/2025-09-12-pgproto-query-metadata.md#алгоритм-вычисления-bucket_id

  • [GL-67] feat(async): support bucket_id to replicaset master mapping.

  • [GL-77] feat(async): support pool graceful shutdown.

  • [GL-42] feat(async): reconcile pool membership with topology changes. When discovery mode enabled, wire Pool reconcil membership as the topology tracker's on_refresh callback, so the pool's connections now follow the cluster instead of being decided once at connect() time.

With discovery disabled, tracking stays purely observational as before.

  • [GL-8] feat(async): route execute by query metadata.

Fixed

  • [GL-71] fix: add missed uv.lock to release commit.

  • [GL-42] fix(async): collect tier names and bucket counts into topology. Previously, we did not collect the tier_name -> bucket_count mapping.

The Picodata notification mechanism would let us calculate this after receiving the ReadyForQuery signal, but Picodata does not send that notification yet. So instead, we simply collect tier info from _pico_tier once and store it in the topology.

  • [GL-79] fix(async): forward pool topology settings to client.

  • [GL-80] fix(sync): support autocommit property.

  • [GL-78] docs: actualize doc for 2.0 release. - move mermaid diagrams from dostring to docs/ as external snippets

  • actualize diagrams/dostring
  • fix outdated repo URL (solution/picopyn -> core/drivers/picopyn)
  • add changelog page and update version compatibility table

Changes

  • [GL-75] refactor: optimize dsn tier lookup.

Docs

  • [GL-63] deps!: bump minimum supported picodata version to 25.5.1. We're adding bucket map collection to the topology, which relies on the _pico_bucket function, supported starting with Picodata 25.5.1: https://docs.picodata.io/picodata/devel/reference/sql/system_functions/#_pico_bucket

More

  • [GL-62] test: move to picodata 26.1.6.

  • [GL-64] deps!: bump minimum supported picodata version to 26.1.1. We implemented the client side of Picodata's query metadata protocol https://git.picodata.io/core/picodata/-/blob/master/doc/adr/2025-09-12-pgproto-query-metadata.md

The protocol is available starting with Picodata 26.1.1.

  • [GL-76] test(async): close client/pool after test.

  • sync deps before test running.

  • set linters target-version same as requires-python (>=3.10). ruff/mypy target-version was set to py311, but the package's declared

    =3.10 minimum so

  • [GL-23] deps: relax dependency constraints. Exact pins (==) on packages like msgpack, mmh3 etc cause resolver conflicts whenever a application needs a different transitive version (e.g. Superset requires msgpack>=1.0.0,<1.1). Switch these to compatible ranges instead.

Also drop the direct async-timeout dependency: it's only needed by asyncpg on Python < 3.11, and asyncpg already declares it conditionally, so pinning it directly here was redundant.

psycopg and asyncpg remain pinned exactly.

[1.0.0] - 17.07.2026

⚠ BREAKING CHANGES

  • fix(async)!: remove API import from picopyn root

Previously from picopyn import Client/Connection/Pool/... implicitly imported the async API, while sync always required an explicit picopyn.synchronous import. Now picopyn/init.py only sets up logging and re-exports nothing -- both APIs must be imported explicitly:

from picopyn.asynchronous import Client
from picopyn.synchronous import Connection

BREAKING CHANGE: from picopyn import Client (and Connection/Pool) no longer works. Use from picopyn.asynchronous import ... instead.

Features

  • [GL-31] feat: move release build to uv.

  • [GL-45] feat: add sync connect/close.

  • [GL-46] feat: add sync cursor.

  • [GL-47] feat(sync): support fetchmany and arraysize to cursor.

  • [GL-48] feat(sync): support execute and executemany.

  • [GL-38] feat(sync): support ssl.

  • [GL-40] feat(sync): support no-op transaction.

  • [GL-55] feat(sync): implement basic pool.

  • [GL-42] feat(async): support topology view. Track cluster topology (instances, replicasets) on the client, modeled after Picodata's topology notifications RFC: https://git.picodata.io/core/picodata/-/blob/master/doc/adr/2025-09-12-pgproto-topology-notifications.md

Picodata doesn't push topology changes as NOTIFY events yet (https://git.picodata.io/core/picodata/-/issues/1306), so for now the client polls Picodata's system tables directly, through a TopologySource abstraction. Once Picodata starts pushing real events, consider to replace topology source with listeting picodata notifications

Currently the pool only reads this topology -- it does not change its connection. Acting on topology changes (refilling pool connections, bucket-aware routing, etc.) is intentionally left for follow-up work.

  • [GL-56] feat(sync): acquire and release connections.

  • [GL-57] feat(sync): support pool execute, fetch, fetchrow.

  • [GL-58] feat(sync): support discovery and forbidden tiers.

Fixed

  • fix unreleased title in changelog.

  • [GL-32] fix: change changelog filename.

  • fixed ssl cert files permissions for local test.

  • clean up connections after pool initialization failure.

  • [GL-50] fix: hide dsn password from logs and errors. Previously, the full DSN, including the user's password, was included in error messages and debug/warning logs. While this was convenient during development, it was unsafe for production logs and error trackers.

Now the password is redacted as ***. For example:

(original) "postgresql://user:pass@host1:5432,host2:5432/db?sslpassword=keypass" (redacted) "postgresql://user:@host1:5432,host2:5432/db?sslpassword="

  • [GL-60] fix: remove closed connections after failed pool connect.

  • remove api import from picopyn root. Previously from picopyn import Client/Connection/Pool/... implicitly imported the async API, while sync always required an explicit picopyn.synchronous import. Now picopyn/init.py only sets up logging and re-exports nothing -- both APIs must be imported explicitly:

    from picopyn.asynchronous import Client from picopyn.synchronous import Connection

  • fix picodata compatibility info.

Changes

  • [GL-35] refactor: move shared code to utils.

  • [GL-37] refactor: extract async implementation into asynchronous package.

  • [GL-44] refactor: replace print statements with logging.

  • [GL-51] refactor(sync): move connect to factory method.

Docs

  • introduce new docs based on mkdocs.

  • [GL-53] docs: publish docs to readthedocs. Docs are published automatically to https://picopyn.readthedocs.io on each release tag via webhook integration with ReadTheDocs. .readthedocs.yaml is configuration file for doc building

  • [GL-53] docs: add missed contributing.md.

  • [GL-43] docs(async): add mermaid diagrams for pool init/usage flow.

  • add db-api docstring references. - link Connection/Cursor to the relevant PEP 249 sections

  • group sync error classes under a dedicated Errors heading instead of listing them alongside Connection/Cursor

  • add a usage example for Cursor.iter

  • add sync examples.

More

  • [GL-49] build: use uv instead of pip.

  • [GL-52] chore: add certs to repository. To simplify testing, SSL certificates have been added to the repository.

Closes GL-52

  • [GL-52] test: set ssl certificate files permissions. We now store SSL certificates in the repository, but Git does not allow us to set their permissions, which are needed to run the tests via Docker. Permission grants are now included in the Makefile.

  • [GL-61] deps: bump picodata version to 25.5.9.

  • add breaking changes section to changelog.

[0.2.0] - 13.04.2026

Features

  • [GL-21] feat: add support of multiple hosts.

  • [GL-18] feat: add forbidden tiers list.

  • [GL-17] feat: add explain api.

  • [GL-20] feat: add ssl support.

Fixed

  • [GL-26] fix: add context manager support for pool.

Docs

  • добавлено больше примеров в документацию.

More

  • setup publish stage.

  • [GL-22] chore: bump python version to 3.10.

  • добавлен stage для тестирования релиза picodata.

  • allow to redefine picodata_image variable for test-picodata job.

[0.1.1] - 03.09.2025

Features

  • [GL-2] feat: implement connection pool.

  • [GL-4] feat: implement node discovery mode to connection pool.

  • [GL-5] feat: implement balance strategy for pool and client. - add client class

  • add custom load balance strategy for client and pool

  • use round-robin as default balance strategy

  • [GL-15] feat: added pool_size parameter for client.

  • [GL-16] feat(lint): introduce code linting and formatting. - added mypy, black, ruff as linters and formatters

  • actualize requirements.txt and requirements-dev.txt
  • applied formatting and type annotations across codebase (library + tests)
  • added separate GitLab CI job for linting

Fixed

  • [GL-14] fix: handle connection errors (e.g. connect, execute sql).

Docs

  • [GL-9] docs: add auto-generated api documentation from docstrings. - Setup pdoc toolchain for auto-documentation
  • Update README.md with new documentation workflow

More

  • [GL-12] test: bench the driver. - added bench scripts
  • added instructions

  • added example

  • [GL-11] драйвер подготовлен для публикации в pypi.

  • add dist files.

  • remove setup.cfg in favor of pyproject.toml.