{"id":160,"library":"psycopg","title":"psycopg (v3)","description":"psycopg v3 — the successor to psycopg2. Completely rewritten. Install is 'psycopg' (no number), import is 'import psycopg'. Supports both sync and native async (AsyncConnection). Current version: 3.3.3 (Mar 2026). NOT backward compatible with psycopg2 — several behavior changes. For new projects use psycopg over psycopg2. Django 4.2+ supports psycopg v3.","status":"active","version":"3.3.3","language":"python","source_language":"en","source_url":"https://github.com/psycopg/psycopg","tags":["psycopg","psycopg3","postgresql","python","async","database"],"install":[{"cmd":"pip install psycopg","lang":"bash","label":"Python (pure Python — no system deps)"},{"cmd":"pip install psycopg[binary]","lang":"bash","label":"Python (with C extension — faster)"},{"cmd":"pip install psycopg[pool]","lang":"bash","label":"Python (with connection pool)"}],"dependencies":[{"reason":"Optional C extension for better performance. Install via psycopg[binary].","package":"psycopg-binary","optional":true}],"imports":[{"wrong":"import psycopg","symbol":"psycopg","correct":"import psycopg"},{"symbol":"AsyncConnection","correct":"from psycopg import AsyncConnection"},{"symbol":"Connection","correct":"from psycopg import Connection"}],"quickstart":{"code":"# pip install psycopg\nimport psycopg\nfrom psycopg.rows import dict_row\n\n# Sync usage\nwith psycopg.connect(\n    'postgresql://user:pass@localhost/mydb',\n    row_factory=dict_row\n) as conn:\n    with conn.cursor() as cur:\n        cur.execute(\n            'SELECT id, name FROM users WHERE active = %s',\n            (True,)\n        )\n        for row in cur.fetchall():\n            print(row['name'])  # dict access\n    conn.commit()","lang":"python","description":"Minimal psycopg v3 sync connection with dict row factory."},"warnings":[{"fix":"Use 'with psycopg.connect(...) as conn:' for connection management. Use 'with conn.transaction():' for transaction blocks.","message":"'with connection' behavior changed from psycopg2. In psycopg2 it manages the transaction. In psycopg v3 it closes the connection. Major silent bug when migrating.","severity":"breaking","affected_versions":"psycopg >= 3.0"},{"fix":"Pass row_factory=psycopg.rows.dict_row to connect() not cursor().","message":"cursor_factory moved from cursor() to connect(). psycopg2 pattern: conn.cursor(cursor_factory=DictCursor). psycopg v3: psycopg.connect(..., row_factory=dict_row).","severity":"breaking","affected_versions":"psycopg >= 3.0"},{"fix":"pip install psycopg; import psycopg","message":"Package name changed. Install: 'psycopg' not 'psycopg3' or 'psycopg2'. Import: 'import psycopg' not 'import psycopg2'. LLMs confuse the package names.","severity":"breaking","affected_versions":"all"},{"fix":"Treat migration as a deliberate refactor. Key differences at psycopg.org/psycopg3/docs/basic/from_pg2.html","message":"psycopg2 and psycopg cannot be used interchangeably in the same codebase — APIs differ. Cannot drop-in replace 'import psycopg2' with 'import psycopg'.","severity":"gotcha","affected_versions":"all"},{"fix":"from psycopg.rows import dict_row — or use psycopg.rows.dict_row","message":"row_factory=dict_row is imported from psycopg.rows, not from psycopg directly. 'from psycopg import dict_row' fails.","severity":"gotcha","affected_versions":"all"},{"fix":"Use conn.copy('COPY table FROM STDIN') context manager pattern.","message":"COPY command API changed. psycopg2 had copy_expert(), copy_from(), copy_to(). psycopg v3 has a single copy() method with unified interface.","severity":"gotcha","affected_versions":"psycopg >= 3.0"},{"fix":"Ensure your PostgreSQL server is running and configured to accept connections on the specified host and port (e.g., 127.0.0.1:5432). Verify network connectivity and firewall settings if connecting to a remote server. Double-check connection parameters in your code.","message":"psycopg.OperationalError: connection failed: Connection refused indicates the PostgreSQL server is not running, is not listening on the specified host/port, or is inaccessible (e.g., due to firewall rules). This is an infrastructure issue, not a psycopg library usage error.","severity":"breaking","affected_versions":"all"},{"fix":"Ensure the PostgreSQL server is running. Verify that the server is configured to listen on the correct host and port (default 5432). Check PostgreSQL's pg_hba.conf and postgresql.conf files to ensure connections are allowed from the client's IP address and for the specified user.","message":"Connection refused: psycopg.OperationalError when connecting to PostgreSQL. This error indicates that the database server is not running, is not accessible at the specified host/port, or is not configured to accept incoming connections from the client.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"search_vec":"'2026':31 '3.3.3':29 '4.2':48 'async':25,56 'asyncconnect':26 'backward':33 'behavior':38 'chang':39 'compat':34 'complet':9 'current':27 'databas':57 'django':47 'import':16,18 'instal':11 'mar':30 'nativ':24 'new':41 'number':15 'postgresql':54 'project':42 'psycopg':1,3,13,19,44,50,52 'psycopg2':8,36,46 'psycopg3':53 'python':55 'rewritten':10 'sever':37 'successor':6 'support':20,49 'sync':22 'use':43 'v3':2,4,51 'version':28","created_at":"2026-03-24T18:48:56.429292+00:00","updated_at":"2026-04-16T18:13:40.859531+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"3.3.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://psycopg.org/","github":"https://github.com/psycopg/psycopg","docs":"https://psycopg.org/psycopg3/docs/","changelog":"https://psycopg.org/psycopg3/docs/news.html","pypi":"https://pypi.org/project/psycopg/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":"verified"}}