Install & Compatibility
Where this runs
tested against v1.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
patch_psycopg
✓ from psycogreen.gevent import patch_psycopg
✗ from psycogreen.gevent import patch_psycopg
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}")
Debug
Known issues
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.fixFor `psycopg3` with Gevent, ensure `psycopg` version 3.1.14+ is used; `psycogreen` should not be imported or used.
affects: psycopg3 (all versions)
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.fixImplement a connection pool (e.g., `psycopg2.pool`) or use explicit greenlet-friendly locks to synchronize access to `psycopg2` connections when shared across green threads.
affects: All `psycogreen` versions with `psycopg2`
gotchaWhen `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.fixThe 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`).
affects: All `psycogreen` versions with `psycopg2`
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.fixAvoid 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.
affects: All `psycogreen` versions with `psycopg2`
gotchaEventlet's monkey-patching often provides `psycopg2` compatibility out-of-the-box, making `psycogreen.eventlet.patch_psycopg()` redundant or unnecessary in many cases.fixTest 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.
affects: All `psycogreen` versions with `eventlet`
Upgrade
Version history
1.0.2latest on PyPI · released Feb 22, 2020
Audit
Dependencies
psycopg2requiredpsycogreen patches psycopg2 for coroutine support.
geventoptionalRequired for gevent integration.
eventletoptionalRequired for eventlet integration.