picopyn

picopyn is a Python connector 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, <4.0.0
26.2.x	⚠️ Unreleased yet

Features

• Connection pooling with configurable pool size
• Optional automatic node discovery
• Pluggable load-balancing strategies
• Automatic pool membership reconciliation according to picodata topology, including rebalancing a full pool across the nodes
  • async pool reconciliation
  • sync pool reconciliation
• Shard-aware routing
  • See usage details async shard-aware routing
  • See usage details sync shard-aware routing
• Asynchronous API based on asyncpg
• Synchronous DB-API 2.0-compatible API based on psycopg

Quick start

pip install picopyn

Async:

import asyncio
from picopyn.asynchronous import Pool

async def main():
    pool = Pool(dsn="postgresql://admin:pass@localhost:5432", enable_discovery=True)
    await pool.open()

    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 pool.execute('INSERT INTO "warehouse" VALUES ($1::int, $2::varchar)', 1, "test")
    rows = await pool.fetch('SELECT * FROM "warehouse"')
    print(rows)

    await pool.close()

asyncio.run(main())

Sync:

from picopyn.synchronous import connect

with connect("postgresql://admin:pass@localhost:5432") as conn:
    cur = conn.cursor()

    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);
    ''')

    cur.execute('INSERT INTO "warehouse" VALUES (%s, %s)', (1, "test"))
    cur.execute('SELECT * FROM "warehouse"')
    print(cur.fetchall())

See Installation for all install options.