py-pglite

0.5.3 verified Fri May 01 auth: no python

Python testing library for PGlite - an in-memory PostgreSQL for tests. Provides a lightweight, in-process PostgreSQL via WebAssembly (pglite-manager). Current version 0.5.3, requires Python >=3.10. Active development with monthly releases.

pip install py-pglite

Common errors

error ModuleNotFoundError: No module named 'pglite' ↓

cause Incorrect import or package not installed.

fix

Run: pip install py-pglite

error AttributeError: module 'pglite' has no attribute 'PGlite' ↓

cause Old version (<0.2.0) where API was different, or wrong import path.

fix

Upgrade to latest: pip install --upgrade py-pglite

error Connection refused Is the server running on host "localhost" (::1) and accepting TCP/IP connections on port 5432? ↓

cause PGlite uses a random port, not default 5432. You must use the connection string from get_connection_string().

fix

Use db.get_connection_string() instead of hardcoding localhost:5432.

error OperationalError: server closed the connection unexpectedly ↓

cause PGlite Node process crashed or was terminated (e.g., due to resource limits).

fix

Ensure Node.js is installed. Set PGLITE_NODE_PATH if needed. Restart the database.

error django.core.exceptions.ImproperlyConfigured: settings.DATABASES is improperly configured. ↓

cause misconfiguration when using pytest-django with py-pglite.

fix

Set DATABASES = {'default': db.get_connection_dict()} in django settings or use @pytest.mark.django_db.

Warnings

breaking In v0.5.0, the API changed from sync-only to support async via SQLAlchemy async engine. The synchronous connection string methods still work, but async users must use get_engine(driver='asyncpg'). ↓

fix For async SQLAlchemy: engine = db.get_engine(driver='asyncpg')

gotcha PGlite launches a Node.js child process (pglite_manager.js). If your Python process exits uncleanly, orphaned processes may remain. Since v0.5.3, cleanup is improved, but always call db.close() or use the context manager. ↓

fix Use context manager: with pglite.PGlite() as db: ...

gotcha The database is ephemeral and lives only as long as the PGlite instance. Data is lost when the Python process ends or PGlite is garbage collected. ↓

fix Do not use for production data. Designed for tests only.

gotcha Extensions like pgvector require opt-in via the 'extensions' parameter. They are not enabled by default. ↓

fix db = pglite.PGlite(extensions=['vector'])

Imports

PGlite
wrong
```
from py_pglite import PGlite
```
correct
```
from pglite import PGlite
```
Package name is pglite, not py_pglite or py-pglite
pglite
```
import pglite
```
No alias or hyphen

Quickstart

Basic usage: spin up ephemeral PostgreSQL and run a query.

import pglite

# Start an in-memory PostgreSQL instance
db = pglite.PGlite()

# Get a psycopg2 connection string
conn_str = db.get_connection_string()
print(conn_str)

# Connect using psycopg2
import psycopg2
conn = psycopg2.connect(conn_str)
cur = conn.cursor()
cur.execute("SELECT version();")
print(cur.fetchone()[0])
cur.close()
conn.close()