postgis-patterns

name	postgis-patterns
description	PostGIS spatial database patterns covering geometry types, spatial queries, indexing, GeoDjango, and GeoAlchemy2. Use when working on projects with django.contrib.gis or geoalchemy2 in their dependencies.
model	haiku

PostGIS Patterns

Patterns and conventions for building spatial applications with PostGIS. Covers geometry and geography types, spatial indexing, common spatial queries, GeoDjango integration, and GeoAlchemy2 for SQLAlchemy-based projects.

Core Principles

• Geography for global distance -- Use geography type for distance calculations on the Earth's surface; use geometry for planar operations within a known projection
• Index everything spatial -- Always create GiST indexes on spatial columns; without them, spatial queries perform full table scans
• ST_DWithin over ST_Distance -- Prefer ST_DWithin for proximity queries because it uses spatial indexes, while ST_Distance < X does not
• SRID consistency -- Keep all data in a consistent SRID (typically 4326 for lat/lng); transform only when needed for calculations

When to Use

Apply these patterns when working on any project that uses spatial data. Detect this by checking pyproject.toml, requirements.txt, or Pipfile for django.contrib.gis, geoalchemy2, or psycopg2/PostGIS references. Also applies when SQL files or migrations reference geometry or geography column types.

Reference Documents

• spatial-queries.md -- PostGIS SQL patterns: geometry vs geography types, spatial indexes, ST_ functions, distance queries, GeoJSON, spatial joins, nearest neighbor, and performance considerations
• geodjango.md -- GeoDjango setup, spatial model fields, spatial lookups, distance queries, serialization, admin integration, forms, GeoAlchemy2 alternative, and testing spatial queries