Install & Compatibility
Where this runs
tested against v? · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.052s · 77.4MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 1.9s · import 0.044s · 152MB
115MB installed
● package 115MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
psycopg2 connection
✓ import psycopg2
import os
# Pooled connection (default from Neon Console)
# hostname includes -pooler
conn = psycopg2.connect(
os.environ['DATABASE_URL'] # must include sslmode=require
)
# DATABASE_URL format:
# postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/dbname?sslmode=require
✗ import psycopg2
# Missing sslmode — raises SSL connection required error
conn = psycopg2.connect('postgresql://user:pass@ep-xxx.neon.tech/dbname')
Always include sslmode=require in Neon connection strings. Omitting it raises: 'SSL connection has been closed unexpectedly' or connection refused.
asyncpg with Neon pooler
✓ import asyncpg
import os
async def get_pool():
# Neon pooler uses PgBouncer in transaction mode
# Must disable prepared statement cache
pool = await asyncpg.create_pool(
os.environ['DATABASE_URL'],
statement_cache_size=0 # required for Neon pooler
)
return pool
✗ import asyncpg
# Using pooled URL without statement_cache_size=0
pool = await asyncpg.create_pool(os.environ['DATABASE_URL'])
# Raises: prepared statement 'asyncpg_stmt_X' does not exist
Neon pooler uses PgBouncer in transaction mode. asyncpg's prepared statement cache breaks with PgBouncer transaction mode. Always set statement_cache_size=0 when using the pooled connection string.
direct vs pooled URL
✓ # Pooled — for app traffic (up to 10k concurrent connections)
DATABASE_URL = 'postgresql://user:pass@ep-cool-rain-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require'
# Direct — for migrations only (alembic, django migrate)
DATABASE_URL_UNPOOLED = 'postgresql://user:pass@ep-cool-rain-123456.us-east-2.aws.neon.tech/neondb?sslmode=require'
✗ # Using pooled URL for Alembic migrations
# Raises: prepared statement errors or transaction issues
alembic.ini: sqlalchemy.url = postgresql://...pooler.../neondb?sslmode=require
Use DIRECT (non-pooler) connection string for schema migrations. PgBouncer transaction mode breaks migration tools. Neon Console provides both — pooled has -pooler in hostname.
Minimal Neon PostgreSQL connection with psycopg2.
# pip install psycopg2-binary python-dotenv
import psycopg2
from dotenv import load_dotenv
import os
load_dotenv()
# Use pooled URL from Neon Console (includes -pooler in hostname)
conn = psycopg2.connect(os.environ['DATABASE_URL'])
# DATABASE_URL=postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require
cur = conn.cursor()
cur.execute('SELECT version()')
print(cur.fetchone())
cur.execute(
'SELECT * FROM users WHERE id = %s',
(1,)
)
rows = cur.fetchall()
cur.close()
conn.close()
Errors
Common errors & fixes
ERROR: The endpoint ID is not specified.
This error occurs when an older PostgreSQL client library (libpq) or application does not support the Server Name Indication (SNI) mechanism in TLS, which Neon uses to route incoming connections based on compute IDs.
fixUpgrade your PostgreSQL client library to version 14 or higher (which supports SNI), or explicitly pass the endpoint ID as a parameter in the connection string, for example, '&options=endpoint%3D[endpoint_id]' or by specifying it in the password field as 'endpoint=[endpoint_id];[password]'.
FATAL: password authentication failed for user "your_user"
This is a general PostgreSQL authentication error, which in Neon often arises from incorrect database credentials (username, password, or database name) or by not including `sslmode=require` in the connection string, as Neon requires all connections to use SSL/TLS encryption.
fixVerify that the username, password, and database name in your connection string are correct. Ensure that `sslmode=require` (or `sslmode=verify-full` for stronger security) is explicitly included in your connection string.
SSL connection has been closed unexpectedly
This error, often seen as `SSL SYSCALL error: EOF detected`, typically occurs when an application tries to reuse a database connection after the Neon compute instance has scaled down to zero due to inactivity, causing the connection to become stale.
fixFor SQLAlchemy, upgrade to version 2.0.33 or later, set `pool_recycle` to a value less than or equal to your Neon compute's scale-to-zero setting, and enable `pool_pre_ping=True` to ensure connections are alive before use. Alternatively, avoid pooled connections for long-lived applications by using `NullPool` with external pooling.
asyncpg.exceptions.InvalidSQLStatementNameError: unnamed prepared statement does not exist HINT: NOTE: pgbouncer with pool_mode set to "transaction" or "statement" does not support prepared statements properly.
This error occurs when using `asyncpg` with Neon's pooled connections (which use PgBouncer in transaction mode), because PgBouncer in this mode does not properly support PostgreSQL's prepared statements that `asyncpg` might attempt to use.
fixDisable `asyncpg`'s prepared statement cache by setting `statement_cache_size=0` when creating the `asyncpg` connection pool. If using SQLAlchemy with asyncpg, also ensure `prepared_statement_name_func` is set to generate unique names for statements.
Upgrade
Version history
0.1.2latest on PyPI · released Dec 10, 2011
Audit
Dependencies
No dependency data recorded yet.