Picopyn - Picodata Python driver

Picopyn is a Python package for working with the distributed Picodata database.

Version compatibility:

Picodata version	Picopyn version
>=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.2.x	⚠️ Unreleased yet

Features

• Connection pooling with configurable pool size
• Optional automatic node discovery
• Pluggable load-balancing strategies
• Asynchronous API based on asyncpg
  • (async only) Shard-aware routing
  • (async only) Automatic pool membership reconciliation
• Synchronous DPAPI-compatible API based on psycopg

Navigation

• Installation
• Quickstart
• Development
  • Docs
  • Lint
  • Test
  • Debug
• Benchmark

Installation

pip install picopyn

Or from source:

git clone https://git.picodata.io/core/drivers/picopyn.git
cd picopyn
pip install -e .

Quickstart

Async:

import asyncio
from picopyn.asynchronous import Client

async def main():
    # create and connect client to the picodata cluster
    client = Client(dsn="postgresql://admin:pass@localhost:5432")
    await client.connect()

    # execute DDL operations
    await client.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"')
    print(rows)

    await client.close()

asyncio.run(main())

Sync:

from picopyn.synchronous import connect

# create and connect to the picodata cluster
with connect("postgresql://admin:pass@localhost:5432") as conn:
    cur = conn.cursor()

    # execute DDL operations
    cur.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
    cur.execute('INSERT INTO "warehouse" VALUES (%s, %s)', (1, "test"))
    cur.execute('SELECT * FROM "warehouse"')
    print(cur.fetchall())

Development

For development we use uv as package manager and docker compose for test environment.

To install development dependencies:

uv sync --extra test

Inside the test container, run the same command to keep dependencies up to date if the image is outdated:

make shell
# inside the container:
make install

Documentation

The documentation is written in Markdown and built with MkDocs using the Material theme. API reference is generated automatically from docstrings via mkdocstrings.

Published documentation is available at picopyn.readthedocs.io.

Source files are located in the docs/ directory. To work on docs locally, install the docs dependencies and start the live-reload server:

uv sync --extra docs
make doc

How to write code

We use several tools to ensure code style and type safety.

• ruff — code style, lint checks and automatic lint fixing
• mypy — static type checking
• black — code formatting

To check code style and static types:

make lint

To automatically fix formatting and style issues:

make fmt

How to test

We use docker compose for test environment.

Run the general test suite:

make test

or run SSL tests:

make test-ssl

This will:

1. Start required test containers (Picodata cluster and test-runner) using Docker Compose

2. Execute tests using pytest

How to debug

Do not forget to run the environment via make env

For debugging purposes:

1. Open a bash shell in the test container:

make shell

2. For interactive Python (with asyncio support) run inside of container:

python -m asyncio

3. To connect directly to Picodata:

picodata admin tmp/data/picodata-1-1/admin.sock

Benchmark

Benchmark instructions and usage examples are available here.