{"id":4695,"library":"psycogreen","title":"psycogreen","description":"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.","status":"maintenance","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/psycopg/psycogreen/","tags":["database","postgresql","psycopg2","gevent","eventlet","async","green-threads","monkey-patch"],"install":[{"cmd":"pip install psycogreen","lang":"bash","label":"Install psycogreen"}],"dependencies":[{"reason":"psycogreen patches psycopg2 for coroutine support.","package":"psycopg2","optional":false},{"reason":"Required for gevent integration.","package":"gevent","optional":true},{"reason":"Required for eventlet integration.","package":"eventlet","optional":true}],"imports":[{"note":"The API for patching Gevent changed in older versions; `patch_psycopg` is the current method.","wrong":"from psycogreen.gevent import psyco_gevent; psyco_gevent.make_psycopg_green()","symbol":"patch_psycopg (gevent)","correct":"from psycogreen.gevent import patch_psycopg"},{"note":"Standard import for Eventlet patching.","symbol":"patch_psycopg (eventlet)","correct":"from psycogreen.eventlet import patch_psycopg"}],"quickstart":{"code":"import os\nimport gevent.monkey\nimport psycopg2\n\n# Apply gevent monkey patching for standard library modules\ngevent.monkey.patch_all()\n\n# Apply psycogreen patching for psycopg2\nfrom psycogreen.gevent import patch_psycopg\npatch_psycopg()\n\n# Now psycopg2 operations will yield to gevent\ntry:\n    # Use os.environ.get for database connection details for runnable example\n    conn = psycopg2.connect(\n        host=os.environ.get('PGHOST', 'localhost'),\n        database=os.environ.get('PGDATABASE', 'testdb'),\n        user=os.environ.get('PGUSER', 'postgres'),\n        password=os.environ.get('PGPASSWORD', 'password'),\n        port=os.environ.get('PGPORT', '5432')\n    )\n    cur = conn.cursor()\n    cur.execute(\"SELECT 1 + 1 AS result;\")\n    result = cur.fetchone()[0]\n    print(f\"PostgreSQL query result (green): {result}\")\n    cur.close()\n    conn.close()\nexcept psycopg2.OperationalError as e:\n    print(f\"Could not connect to PostgreSQL. Please ensure a PostgreSQL instance is running and accessible. Error: {e}\")\nexcept ImportError as e:\n    print(f\"Required modules (gevent, psycogreen, psycopg2) not installed. Error: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"For `psycopg3` with Gevent, ensure `psycopg` version 3.1.14+ is used; `psycogreen` should not be imported or used.","message":"`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.","severity":"breaking","affected_versions":"psycopg3 (all versions)"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All `psycogreen` versions with `psycopg2`"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All `psycogreen` versions with `psycopg2`"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All `psycogreen` versions with `psycopg2`"},{"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.","message":"Eventlet's monkey-patching often provides `psycopg2` compatibility out-of-the-box, making `psycogreen.eventlet.patch_psycopg()` redundant or unnecessary in many cases.","severity":"gotcha","affected_versions":"All `psycogreen` versions with `eventlet`"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}