picopyn 0.2.0

Async connector for working with the distributed Picodata database.

Picopyn - Picodata python driver

Picopyn is a Python package for working with the distributed Picodata database. It's built on top of the asyncpg package.

Features

• Connection pooling with configurable pool size
• Optional automatic node discovery
• Pluggable load-balancing strategies
• Fully asynchronous API

Navigation

• Installation
• Quickstart
• Development
• Benchmark

Install

Install from source:

git clone https://git.picodata.io/solution/picopyn.git
cd picopyn
make install

Quickstart

import asyncio
from picopyn 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 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())

Development

Install development dependencies

pip install -r requirements-dev.txt

Documentation

To update documentation:

make gen-doc

To view documentation:

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

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 run 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/picodata-1-1/admin.sock

Benchmark

Benchmark instructions and usage examples are available here.