Neon (Serverless PostgreSQL)

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• psycopg2 connection
  wrong

  import psycopg2
  # Missing sslmode — raises SSL connection required error
  conn = psycopg2.connect('postgresql://user:pass@ep-xxx.neon.tech/dbname')

  correct

  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

  Always include sslmode=require in Neon connection strings. Omitting it raises: 'SSL connection has been closed unexpectedly' or connection refused.

• asyncpg with Neon pooler
  wrong

  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

  correct

  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

  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
  wrong

  # Using pooled URL for Alembic migrations
  # Raises: prepared statement errors or transaction issues
  alembic.ini: sqlalchemy.url = postgresql://...pooler.../neondb?sslmode=require

  correct

  # 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'

  Use DIRECT (non-pooler) connection string for schema migrations. PgBouncer transaction mode breaks migration tools. Neon Console provides both — pooled has -pooler in hostname.

Quickstart stale last tested: 2026-04-23

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()