py-pglite 0.2.1

Python testing library for PGlite - in-memory PostgreSQL for tests

Py-PGlite

Instant PostgreSQL for Python testing ⚡

pip install py-pglite

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

That's it. No Docker, no setup, no config files. Real PostgreSQL, instant testing.

---

⚡ Zero-Config Quick Start

SQLAlchemy (Zero imports needed)

def test_sqlalchemy_just_works(pglite_session):
    # Tables created automatically
    user = User(name="Alice", email="[e-mail]")  
    pglite_session.add(user)
    pglite_session.commit()
    
    assert user.id is not None
    assert User.query.count() == 1  # Real PostgreSQL!

Django (Auto-configured)

def test_django_just_works(db):
    # Models ready automatically
    Post.objects.create(title="Hello", content="World")
    assert Post.objects.count() == 1  # Real PostgreSQL!

Raw SQL (Pure speed)

def test_raw_sql_power(pglite_engine):
    with pglite_engine.connect() as conn:
        # Full PostgreSQL features
        result = conn.execute(text("""
            SELECT '{"users": [{"name": "Alice"}]}'::json ->> 'users'
        """)).scalar()
        assert '"name": "Alice"' in result  # JSON queries work!

---

🚀 Why py-pglite?

# ❌ Traditional testing
def test_old_way():
    # 1. Install PostgreSQL
    # 2. Configure connection  
    # 3. Manage test databases
    # 4. Handle cleanup
    # 5. Docker containers...
    pass

# ✅ py-pglite way  
def test_new_way(pglite_session):
    User.objects.create(name="Alice")  # Just works!

The magic:

• 🎯 Zero config - No setup, no Docker, no servers
• ⚡ Sweet spot - PostgreSQL power + near-SQLite convenience
• 🔄 Isolated - Fresh database per test
• 🎪 Full featured - JSON, arrays, window functions, etc.
• 🧪 Framework ready - SQLAlchemy, Django, FastAPI
• 🚀 Fast setup - 2-3s vs 30-60s Docker PostgreSQL startup

---

📦 Installation

# Core (framework-agnostic)
pip install py-pglite

# With your favorite framework
pip install py-pglite[sqlalchemy]  # SQLAlchemy + SQLModel
pip install py-pglite[django]      # Django + pytest-django  
pip install py-pglite[all]         # Everything

---

🎯 Real Examples

SQLAlchemy + FastAPI (Production ready)

from fastapi.testclient import TestClient

def test_api_endpoint(client: TestClient):
    # Auto-configured FastAPI + SQLAlchemy + PostgreSQL
    response = client.post("/users/", json={"name": "Alice"})
    assert response.status_code == 201
    
    response = client.get("/users/")
    assert len(response.json()) == 1

Django Models (Zero setup)

def test_django_models(db):
    # Django auto-configured with real PostgreSQL
    user = User.objects.create_user("alice", "[e-mail]") 
    blog = Blog.objects.create(title="Hello", author=user)
    
    assert Blog.objects.filter(author__username="alice").count() == 1

PostgreSQL Features (Full power)

def test_postgresql_features(pglite_session):
    pglite_session.execute(text("""
        CREATE TABLE analytics (
            id SERIAL PRIMARY KEY,
            data JSONB,
            tags TEXT[],
            created TIMESTAMP DEFAULT NOW()
        )
    """))
    
    # JSON operations
    pglite_session.execute(text("""
        INSERT INTO analytics (data, tags) VALUES 
        ('{"clicks": 100, "views": 1000}', ARRAY['web', 'mobile'])
    """))
    
    # Complex PostgreSQL query
    result = pglite_session.execute(text("""
        SELECT data->>'clicks' as clicks,
               array_length(tags, 1) as tag_count,
               extract(hour from created) as hour
        FROM analytics 
        WHERE data->>'clicks' > '50'
    """)).fetchone()
    
    assert result.clicks == '100'
    assert result.tag_count == 2

---

🏗️ Architecture

py_pglite/
├── 📦 Core (no dependencies)
├── 🔧 SQLAlchemy integration  
├── 🌟 Django integration
└── ⚡ Auto-discovery pytest plugin

Design principles:

• Framework agnostic core - Use with anything
• Optional integrations - Only load what you need
• Zero configuration - Intelligent defaults
• Perfect isolation - No framework interference

---

🎪 Advanced Features

🔧 Custom Configuration

@pytest.fixture(scope="session")
def custom_pglite():
    config = PGliteConfig(
        port_range=(5500, 5600),
        timeout=30,
        cleanup_on_exit=True
    )
    with PGliteManager(config) as manager:
        yield manager

🚀 Performance Testing

def test_bulk_insert_performance(pglite_session):
    users = [User(name=f"user_{i}") for i in range(1000)]
    pglite_session.add_all(users)
    pglite_session.commit()
    
    assert pglite_session.query(User).count() == 1000
    # Blazing fast with real PostgreSQL!

🎯 Framework Isolation

# Pure SQLAlchemy tests
pytest -m sqlalchemy -p no:django

# Pure Django tests
pytest -m django

# Directory isolation
pytest tests/sqlalchemy/  # Auto-isolated
pytest tests/django/       # Auto-isolated

---

💝 Community

"Finally, PostgreSQL testing that just works!" - Happy Developer

"From 30 minutes of setup to 30 seconds. Game changer." - Django User

"Vite for databases. This is the future." - FastAPI Enthusiast

---

Built for developers who want PostgreSQL testing without the complexity.

🎯 View Examples • 📚 Contributing • 🐛 Issues

---

py-pglite: Because testing should be simple. ⚡