psycogreen

1.0.2 · maintenance · verified Sun Apr 12

Psycogreen is a library that enables the `psycopg2` PostgreSQL adapter to work with coroutine-based libraries like Gevent and Eventlet. It provides "wait callbacks" that integrate `psycopg2`'s asynchronous calls with the event loops of these coroutine libraries, allowing `psycopg2` to operate in a non-blocking manner within a green-thread environment while presenting a synchronous interface to the application. The library is currently at version 1.0.2, with no new releases since 2020, suggesting it is in maintenance mode.

Warnings

breaking `psycogreen` is not required and has no effect with `psycopg3`. `psycopg3` (especially from version 3.1.14 onwards) has native Gevent support. Using `psycogreen` with `psycopg3` is unnecessary and may lead to unexpected behavior.
Fix: For `psycopg3` with Gevent, ensure `psycopg` version 3.1.14+ is used; `psycogreen` should not be imported or used.
gotcha `psycopg2` connections are not green thread-safe and cannot be used concurrently by different green threads. Sharing a single connection across multiple greenlets without proper synchronization (e.g., connection pooling or explicit locks) will lead to errors or deadlocks.
Fix: Implement a connection pool (e.g., `psycopg2.pool`) or use explicit greenlet-friendly locks to synchronize access to `psycopg2` connections when shared across green threads.
gotcha When `psycogreen` is used, the `connect_timeout` option in `psycopg2.connect()` may not function as expected, potentially causing connections to hang indefinitely during connection attempts. This is a known issue with `psycopg2` in async mode.
Fix: The client application must implement its own timeout mechanism for connection attempts, for example, by wrapping the `psycopg2.connect` call with a timeout from the coroutine library (e.g., `gevent.Timeout`).
gotcha `COPY` commands (for bulk data transfer) and large objects are currently not supported when a `psycogreen` wait callback is registered. Attempting to use them will result in errors.
Fix: Avoid using `COPY` commands or large object operations with `psycogreen` patched connections. If these operations are critical, consider using a dedicated, non-patched `psycopg2` connection, or using `psycopg3` which might address these limitations.
gotcha Eventlet's monkey-patching often provides `psycopg2` compatibility out-of-the-box, making `psycogreen.eventlet.patch_psycopg()` redundant or unnecessary in many cases.
Fix: Test your application with `eventlet.monkey.patch_all()` alone before adding `psycogreen.eventlet.patch_psycopg()` to avoid potential conflicts or unnecessary patching. Refer to Eventlet's documentation for specific patching instructions.

Install

pip install psycogreen Install psycogreen

Imports

patch_psycopg (gevent)
```
from psycogreen.gevent import patch_psycopg
```
The API for patching Gevent changed in older versions; `patch_psycopg` is the current method.
patch_psycopg (eventlet)
```
from psycogreen.eventlet import patch_psycopg
```
Standard import for Eventlet patching.

Quickstart

This quickstart demonstrates patching `psycopg2` with `psycogreen` for use with Gevent. It's crucial to call `gevent.monkey.patch_all()` and `psycogreen.gevent.patch_psycopg()` early in your application's lifecycle, typically before any `psycopg2` imports or connections are made. The example connects to a PostgreSQL database using environment variables for credentials and executes a simple query.

import os
import gevent.monkey
import psycopg2

# Apply gevent monkey patching for standard library modules
gevent.monkey.patch_all()

# Apply psycogreen patching for psycopg2
from psycogreen.gevent import patch_psycopg
patch_psycopg()

# Now psycopg2 operations will yield to gevent
try:
    # Use os.environ.get for database connection details for runnable example
    conn = psycopg2.connect(
        host=os.environ.get('PGHOST', 'localhost'),
        database=os.environ.get('PGDATABASE', 'testdb'),
        user=os.environ.get('PGUSER', 'postgres'),
        password=os.environ.get('PGPASSWORD', 'password'),
        port=os.environ.get('PGPORT', '5432')
    )
    cur = conn.cursor()
    cur.execute("SELECT 1 + 1 AS result;")
    result = cur.fetchone()[0]
    print(f"PostgreSQL query result (green): {result}")
    cur.close()
    conn.close()
except psycopg2.OperationalError as e:
    print(f"Could not connect to PostgreSQL. Please ensure a PostgreSQL instance is running and accessible. Error: {e}")
except ImportError as e:
    print(f"Required modules (gevent, psycogreen, psycopg2) not installed. Error: {e}")

view raw JSON →