Install & Compatibility
Where this runs
tested against v1.31.5 · 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.230s · 20.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.208s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Connection
✓ from pg8000 import Connection
✗ import pg8000.dbapi
Cursor
✓ from pg8000 import Cursor
connect
✓ from pg8000 import connect
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
Debug
Known issues
breakingA 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.fixUpgrade to pg8000 version 1.31.5 or newer.
affects: <= 1.31.4
deprecatedThe `pg8000.DBAPI` module and types like `pg8000.types.Bytea` were deprecated in favor of direct `pg8000.connect` and Python's native `bytes` type.fixUse `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.
affects: <1.9.0
gotchaIn 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.fixExplicitly 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.
affects: All versions (behavioral)
gotchaOlder 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.fixUpgrade to recent versions of pg8000. Avoid constructing SQL queries by directly embedding arguments; always use parameterized queries. Close connections when no longer needed.
affects: <1.9.11 (and subsequent minor fixes)
gotchaDB-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`.fixAlways call `conn.commit()` after operations that modify the database, or configure `autocommit=True` during connection if that behavior is desired.
affects: All versions (DB-API 2.0 compliance)
gotchaNetwork-related connection issues will raise an `InterfaceError` with the message 'network error', rather than exposing the underlying socket/OS exception.fixCatch `pg8000.dbapi.InterfaceError` specifically when handling potential network connectivity problems.
affects: >=1.26.0
Upgrade
Version history
1.31.5latest on PyPI · released Sep 14, 2025
Audit
Dependencies
python-dateutilrequiredUsed for date/time handling and conversions.
scramprequiredUsed for SCRAM-SHA-256 authentication.