WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

PlaygreSQL is a Docker-based development environment for testing PostgreSQL extensions (PostGIS, TimescaleDB, pgVector) using Django ORM with Python 3.14 and the uv package manager. This is a development environment only and is not production-ready.

Architecture

Multi-Container Setup

The project uses Docker Compose with three services:

1. db (PostgreSQL 16): Custom-built container with PostGIS 3.4, TimescaleDB, and pgVector extensions pre-installed and enabled via init.sql
2. web (Django 5.2+): Python 3.14 container running Django with hot-reload for development
3. ollama: LLM inference service for local AI experiments

Django Configuration

• Settings: playgresql/settings.py conditionally loads PostGIS support based on ENABLE_GIS environment variable
• Database Backend: Automatically switches between django.contrib.gis.db.backends.postgis (when ENABLE_GIS=true) and django.db.backends.postgresql
• Sample Apps: series/ and vectors/ are empty Django apps for TimescaleDB and pgVector experimentation
• Demo Models: extensions_demo.py contains commented example models for all three extensions with usage patterns

Extension-Specific Patterns

PostGIS Models:

• Use from django.contrib.gis.db import models as gis_models
• Fields: PointField(), LineStringField(), PolygonField()
• Requires ENABLE_GIS=true environment variable

TimescaleDB Models:

• Use regular Django models with DateTimeField as primary key
• Convert to hypertables via migration using migrations.RunSQL("SELECT create_hypertable('table_name', 'time', if_not_exists => TRUE);")
• Time-based queries leverage TimescaleDB's automatic optimizations

pgVector Models:

• Store embeddings using ArrayField(models.FloatField(), size=DIMENSIONS)
• Or use pgvector.django.VectorField(dimensions=DIMENSIONS) (as seen in vectors/models.py)
• Query with raw SQL using distance operators: <=> (cosine), <-> (L2), <#> (inner product)

Common Commands

Container Management

Start all services:

./start.sh  # Automated with health checks and migrations

Or manually:

docker compose up --build

Stop and remove volumes (full reset):

docker compose down -v

Django Operations

All Django commands must be prefixed with docker compose exec web uv run:

Migrations:

docker compose exec web uv run python manage.py makemigrations
docker compose exec web uv run python manage.py migrate

Django Shell:

docker compose exec web uv run python manage.py shell

Create Superuser:

docker compose exec web uv run python manage.py createsuperuser

Create New App:

docker compose exec web uv run python manage.py startapp <app_name>

Then add to playgresql/settings.py INSTALLED_APPS.

Database Access

From host machine:

psql postgresql://postgres:postgres@localhost:5432/playgresql

Django dbshell:

docker compose exec web uv run python manage.py dbshell

Direct psql:

docker compose exec db psql -U postgres -d playgresql

Verification Commands

Check database health:

docker compose exec db pg_isready -U postgres

Verify extensions:

docker compose exec db psql -U postgres -d playgresql -c "SELECT extname, extversion FROM pg_extension;"

View logs:

docker compose logs -f
docker compose logs -f web  # Django only
docker compose logs -f db   # PostgreSQL only

Local Development (Optional)

Install dependencies locally without Docker:

uv sync

Run Django commands locally (requires local PostgreSQL):

uv run python manage.py migrate

Linting (ruff is in dev dependencies):

uv run ruff check .

Ollama Usage

Pull model:

docker compose exec ollama ollama pull llama2

Interactive session:

docker compose exec ollama ollama run llama2

From Django (OLLAMA_HOST is pre-configured to http://ollama:11434):

import os
print(os.getenv('OLLAMA_HOST'))

Development Workflow

Adding New Extension Features

1. Copy relevant model examples from extensions_demo.py to your app's models.py
2. Create migrations: docker compose exec web uv run python manage.py makemigrations
3. For TimescaleDB, add a second migration with RunSQL to create hypertables
4. For pgVector, add indexes via raw SQL migrations for optimal performance
5. Apply migrations: docker compose exec web uv run python manage.py migrate

Working with TimescaleDB

After creating a time-series model, convert it to a hypertable in a migration:

from django.db import migrations

class Migration(migrations.Migration):
    dependencies = [('app_name', 'XXXX_previous_migration')]
    
    operations = [
        migrations.RunSQL(
            "SELECT create_hypertable('table_name', 'time', if_not_exists => TRUE);",
            reverse_sql="SELECT 1;"
        ),
    ]

Working with pgVector

Create vector indexes after initial table creation:

migrations.RunSQL(
    "CREATE INDEX ON table_name USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);",
    reverse_sql="DROP INDEX IF EXISTS table_name_embedding_idx;"
)

For similarity search, use raw SQL with distance operators in Django shell.

Important Notes

• The web container has hot-reload enabled; code changes reflect immediately without restart
• Database and Ollama data persist in Docker volumes between restarts
• Ollama is mapped to port 11435 (not 11434) to avoid conflicts with local instances
• Use ENABLE_GIS=true environment variable to enable PostGIS features
• All credentials default to postgres:postgres for development convenience
• Never commit .env file (use .env.example as template)