pg8000: Pure-Python PostgreSQL Driver

1.31.5 verified Tue May 12 auth: no python install: verified quickstart: verified

pg8000 is a pure-Python PostgreSQL driver that fully complies with the DB-API 2.0 specification. It distinguishes itself by being written entirely in Python, eliminating the need for external C libraries like `libpq`, which enhances portability and simplifies installation. The library provides both a standard DB-API 2.0 interface and a native API for streamlined usage. Currently at version 1.31.5, it is actively maintained with regular updates.

pip install pg8000

Common errors

error AttributeError: module 'pg8000' has no attribute 'connect' ↓

cause Developers often attempt to call `connect()` directly on the `pg8000` module, but the `connect` function is located within the `pg8000.dbapi` (for DB-API 2.0 interface) or `pg8000.native` (for the native API) submodules.

fix

Use import pg8000.dbapi and then call pg8000.dbapi.connect(), or import pg8000.native and use pg8000.native.Connection() or pg8000.native.connect() (for newer versions).

error pg8000.errors.InterfaceError: Authentication method X not recognized by pg8000 ↓

cause This error occurs when the PostgreSQL server is configured to use an authentication method (e.g., SCRAM-SHA-256, represented by method '10') that the installed version of `pg8000` does not support. Older versions of `pg8000` might not support newer authentication methods.

fix

Upgrade pg8000 to the latest version (e.g., pip install --upgrade pg8000). If upgrading is not an option, configure your PostgreSQL server to use a supported authentication method like md5 or password in pg_hba.conf.

error pg8000.errors.OperationalError: SSL SYSCALL error: EOF detected ↓

cause This error indicates an abrupt termination of the SSL connection between the client and the PostgreSQL server, often due to network instability, misconfigured SSL settings on either the client or server, or long-idle connections being dropped by firewalls or proxies.

fix

Ensure stable network connectivity, verify SSL configurations on both client and server, and if using an ORM with connection pooling (like SQLAlchemy), enable connection pre-ping (e.g., pool_pre_ping=True) to validate connections before use. Also consider setting TCP keepalives.

error psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory ↓

cause While not a `pg8000` specific error, this indicates that the PostgreSQL server is either not running or not listening on the expected Unix domain socket path, which `pg8000` might attempt to use by default or when `host` is not specified.

fix

Ensure the PostgreSQL service is running (sudo service postgresql start or brew services restart postgresql), and verify the correct socket path or connect using TCP/IP by specifying the host parameter (e.g., host='localhost').

Warnings

breaking A SQL injection vulnerability (CVE-2025-61385) was found in `pg8000.native.literal` that allowed remote attackers to execute arbitrary SQL commands via a specially crafted Python list input. ↓

fix Upgrade to pg8000 version 1.31.5 or newer.

deprecated The `pg8000.DBAPI` module and types like `pg8000.types.Bytea` were deprecated in favor of direct `pg8000.connect` and Python's native `bytes` type. ↓

fix Use `import pg8000.dbapi; pg8000.dbapi.connect()` for DB-API 2.0 or `pg8000.native.Connection()` for the native API. Use Python's `bytes` type directly for binary data.

gotcha In autocommit mode, `cursor.fetchall()` might fail with 'portal does not exist' for result sets larger than the internal cache (default 100 rows) because the database portal is closed prematurely. ↓

fix Explicitly manage transactions by calling `conn.commit()` or `conn.rollback()` as per DB-API 2.0, or use server-side cursors for very large result sets. Avoid relying solely on autocommit for large fetches.

gotcha Older versions of pg8000 could suffer from memory leaks due to an unbounded cache of prepared statements, especially when executing many unique queries or frequent DDL operations. ↓

fix Upgrade to recent versions of pg8000. Avoid constructing SQL queries by directly embedding arguments; always use parameterized queries. Close connections when no longer needed.

gotcha DB-API 2.0 mandates implicit transactions for DML/DDL statements. Changes will not persist until `conn.commit()` is explicitly called, unless the `autocommit` connection parameter is set to `True`. ↓

fix Always call `conn.commit()` after operations that modify the database, or configure `autocommit=True` during connection if that behavior is desired.

gotcha Network-related connection issues will raise an `InterfaceError` with the message 'network error', rather than exposing the underlying socket/OS exception. ↓

fix Catch `pg8000.dbapi.InterfaceError` specifically when handling potential network connectivity problems.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.20s 20.1M

3.10 alpine (musl) - - 0.22s 20.1M

3.10 slim (glibc) wheel 1.9s 0.15s 21M

3.10 slim (glibc) - - 0.16s 21M

3.11 alpine (musl) wheel - 0.30s 22.3M

3.11 alpine (musl) - - 0.36s 22.3M

3.11 slim (glibc) wheel 2.2s 0.26s 23M

3.11 slim (glibc) - - 0.25s 23M

3.12 alpine (musl) wheel - 0.23s 14.1M

3.12 alpine (musl) - - 0.26s 14.1M

3.12 slim (glibc) wheel 1.9s 0.25s 15M

3.12 slim (glibc) - - 0.27s 15M

3.13 alpine (musl) wheel - 0.24s 13.8M

3.13 alpine (musl) - - 0.29s 13.7M

3.13 slim (glibc) wheel 1.9s 0.23s 14M

3.13 slim (glibc) - - 0.24s 14M

3.9 alpine (musl) wheel - 0.18s 19.6M

3.9 alpine (musl) - - 0.21s 19.6M

3.9 slim (glibc) wheel 2.3s 0.16s 20M

3.9 slim (glibc) - - 0.16s 20M

Imports

connect
wrong
```
import pg8000
conn = pg8000.DBAPI.connect()
```
correct
```
import pg8000.dbapi
conn = pg8000.dbapi.connect(...)
```
The `DBAPI` submodule was deprecated in v1.9.0; `pg8000.dbapi.connect` is the standard DB-API 2.0 entry point.
Connection (Native API)
```
import pg8000.native
conn = pg8000.native.Connection(...)
```
For using pg8000's native API, which offers a more streamlined interface.
Bytea (type)
wrong
```
from pg8000.types import Bytea
```
correct
```
value = b'binary_data'
```
The `pg8000.types.Bytea` type was deprecated in v1.9.0 in favor of Python's built-in `bytes` type.

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to establish a connection using the DB-API 2.0 compliant interface, perform DDL and DML operations with parameterized queries, and fetch results. It also includes basic error handling and uses environment variables for secure credential management.

import pg8000.dbapi
import os

# Database connection details from environment variables
DB_USER = os.environ.get("PG_USER", "postgres")
DB_PASSWORD = os.environ.get("PG_PASSWORD", "password")
DB_HOST = os.environ.get("PG_HOST", "localhost")
DB_PORT = int(os.environ.get("PG_PORT", "5432"))
DB_DATABASE = os.environ.get("PG_DATABASE", "testdb")

conn = None
try:
    # Establish a DB-API 2.0 compliant connection
    conn = pg8000.dbapi.connect(
        user=DB_USER,
        password=DB_PASSWORD,
        host=DB_HOST,
        port=DB_PORT,
        database=DB_DATABASE
    )
    cursor = conn.cursor()

    # Create a table (if it doesn't exist)
    cursor.execute("CREATE TABLE IF NOT EXISTS mytable (id SERIAL PRIMARY KEY, name VARCHAR(100))")
    conn.commit() # Commit the DDL operation

    # Insert data using a parameterized query
    cursor.execute("INSERT INTO mytable (name) VALUES (%s)", ("pg8000_test",))
    conn.commit() # Commit the DML operation

    # Query data
    cursor.execute("SELECT id, name FROM mytable WHERE name = %s", ("pg8000_test",))
    result = cursor.fetchone()
    print(f"Fetched: {result}")

except pg8000.dbapi.Error as e:
    print(f"Database error: {e}")
    if conn:
        conn.rollback() # Rollback on database errors
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    if conn:
        conn.close() # Ensure connection is closed