deftest_users(pglite_session):user=User(name="Alice")pglite_session.add(user)pglite_session.commit()assertuser.id==1# It's real PostgreSQL!

Why py-pglite?

# ❌ Traditional testingdeftest_old_way():# 1. Install PostgreSQL# 2. Configure connection# 3. Manage test databases# 4. Handle cleanup# 5. Docker containers...pass# ✅ py-pglite waydeftest_new_way(pglite_session):User.objects.create(name="Alice")# Just works!

Install

# Core (framework-agnostic)pip install py-pglite# With your stackpip install py-pglite[sqlalchemy]# SQLAlchemy + SQLModelpip install py-pglite[django]# Django + pytest-djangopip install py-pglite[asyncpg]# Pure async clientpip install py-pglite[all]# Everything# Extra Featurespip install py-pglite[extensions]# pglite extensions, like pgvector, fuzzystrmatch etc.

Quick Start

SQLAlchemy (Zero imports needed)

deftest_sqlalchemy_just_works(pglite_session):user=User(name="Alice",email="alice@test.com")pglite_session.add(user)pglite_session.commit()assertuser.idisnotNoneassertUser.query.count()==1# Real PostgreSQL!

Django

deftest_django_socket_pattern(configured_django):Post.objects.create(title="Hello",content="World")assertPost.objects.count()==1# Real PostgreSQL via socket!

deftest_django_backend_pattern(django_pglite_db):Post.objects.create(title="Hello",content="World",metadata={"tags": ["test"]})assertPost.objects.count()==1# Custom backend with JSON support!

Any PostgreSQL client

deftest_any_client_works(pglite_manager):# Extract connection detailsengine=pglite_manager.get_engine()host,port,database=str(engine.url.host),engine.url.port,engine.url.database# Use with any PostgreSQL client# conn = psycopg.connect(host=host, port=port, dbname=database)# engine = create_async_engine(f"postgresql+asyncpg://{host}:{port}/{database}")# For asyncpg specifically, use TCP mode with proper configuration:asyncdeftest_asyncpg_works(pglite_tcp_manager):config=pglite_tcp_manager.configconn=awaitasyncpg.connect(host=config.tcp_host,port=config.tcp_port,user="postgres",password="postgres",database="postgres",ssl=False,server_settings={}# CRITICAL: Required for PGlite compatibility    )result=awaitconn.fetchval("SELECT 1")awaitconn.close()

Examples

FastAPI + SQLModel

fromfastapi.testclientimportTestClientdeftest_api_endpoint(client:TestClient):response=client.post("/users/",json={"name":"Alice"})assertresponse.status_code==201response=client.get("/users/")assertlen(response.json())==1

PostgreSQL Features

deftest_postgresql_power(pglite_session):pglite_session.execute(text("""        CREATE TABLE analytics (            data JSONB,            tags TEXT[],            created TIMESTAMP DEFAULT NOW()        )    """))pglite_session.execute(text("""        INSERT INTO analytics (data, tags) VALUES        ('{"clicks": 100}', ARRAY['web', 'mobile'])    """))result=pglite_session.execute(text("""        SELECT data->>'clicks' as clicks,               array_length(tags, 1) as tag_count        FROM analytics        WHERE data->>'clicks' > '50'    """)).fetchone()assertresult.clicks=='100'

PostgreSQL Extensions

🚀pgvector for RAG Applications

pip install'py-pglite[extensions]'

frompy_pgliteimportPGliteConfig,PGliteManagerfrompgvector.psycopgimportregister_vectorimportpsycopgimportnumpyasnp# Enable the extensionconfig=PGliteConfig(extensions=["pgvector"])withPGliteManager(config=config)asdb:withpsycopg.connect(db.get_dsn(),autocommit=True)asconn:# Create the extension and register the typeconn.execute("CREATE EXTENSION IF NOT EXISTS vector")register_vector(conn)# Create a table and insert a vectorconn.execute("CREATE TABLE items (embedding vector(3))")conn.execute("INSERT INTO items (embedding) VALUES (%s)", (np.array([1,2,3]),))# Perform a similarity searchresult=conn.execute("SELECT * FROM items ORDER BY embedding <-> %s LIMIT 1", (np.array([1,1,1]),)).fetchone()assertnp.array_equal(result[0],np.array([1,2,3]))

Advanced