{"canonical_url":"https://engineer.company/glossary/postgis/","content_markdown":"# PostGIS\n\n## What it is\n\nPostGIS is an open-source add-on for the PostgreSQL database server that lets a\ncolumn hold a shape, such as a delivery address, a river or a property boundary,\nand lets ordinary SQL ask where those shapes sit in relation to one another. It\nbegan as a research project at Refractions Research, a GIS and database\nconsultancy, and is now developed and released as an open-source project of its\nown.\n\nIt is installed per database with one statement, `CREATE EXTENSION postgis;`,\nand three things arrive with it.\n\n- **Spatial types.** `geometry` describes shapes on a flat plane in whatever\n  coordinate system the data was captured in. `geography` describes them on the\n  curved surface of the Earth and measures in metres.\n- **Spatial functions.** A large family of functions whose names start with\n  `ST_`: `ST_Intersects` and `ST_Contains` for relationships, `ST_Area` and\n  `ST_Length` for measurement, `ST_Transform` for moving between coordinate\n  systems, `ST_AsGeoJSON` for handing results to a web map.\n- **Spatial indexes.** PostGIS builds an R-tree on top of PostgreSQL's GiST\n  framework, and also supports SP-GiST and block-range indexes for particular\n  shapes of data.\n\nThe shapes follow the Simple Features model published by the Open Geospatial\nConsortium and adopted as ISO 19125: points, line strings and polygons, their\nmulti-part versions, and collections of mixed types. Every stored value carries\nan SRID, a number that points to a row in the `spatial_ref_sys` table and says\nwhat the coordinates mean. SRID 4326 means longitude and latitude in degrees on\nthe WGS 84 datum, the system GPS reports in. A projected system, by contrast,\nmeasures in metres east and north of a fixed origin and is accurate only within\nthe region it was designed for.\n\nRaster data, topology and some 3D operations come as separate extensions,\n`postgis_raster`, `postgis_topology` and `postgis_sfcgal`, so a database carries\nonly the parts it uses.\n\n## Why it matters\n\nThe decision PostGIS forces is where location data should live. Without it,\ncoordinates tend to sit in two numeric columns while the actual spatial work\nhappens somewhere else: in application code that loops over rows to compute\ndistances, in a desktop GIS that someone exports to every Monday, or in a\nseparate geographic service with its own copy of the data. Each of those copies\ndrifts. With PostGIS, “which customers are within two kilometres of a depot that\nhas stock” is one query that joins stock levels, customer records and shapes,\ninside one transaction, under the same backups and the same permissions as\neverything else in the database.\n\nThat also means spatial data gets the guarantees the rest of the schema already\nhas. A check constraint can reject an invalid polygon at insert time. Row-level\nsecurity can limit a regional team to the parcels in its own region. A failed\nimport rolls back instead of leaving half a layer behind.\n\nThe second decision is geometry or geography, and the PostGIS manual is direct\nabout it. Data that stays within a city or a country is usually best stored as\n`geometry` in a projection chosen for that area, because the full function set\nis available and the arithmetic is fast. Data that spans continents, or whose\nusers ask for distances in metres between points anywhere on Earth, is easier to\nget right as `geography`, which does the curved-surface maths itself at the cost\nof a smaller set of functions.\n\nAnd sometimes the answer is that PostGIS is more than the job needs. An app that\nonly stores a latitude and longitude per shop and drops pins on a map can live\nwith two numeric columns. PostGIS earns its place once the questions are about\ndistance, containment or overlap, or once the data includes lines and polygons\nrather than single points.\n\n## What it looks like in practice\n\nA map application serving real-time spatial queries to many users ran on a\nMicrosoft SQL Server database, and latency was hurting both the map and the\nservices behind it.\n[The fix was a move to PostgreSQL with PostGIS](/portfolio/improved-gis-map-performance-10x-on-postgresql/),\nwith a schema designed for spatial data, GiST and SP-GiST indexes on the\ngeometry and geography columns, and constraints on the spatial coordinates. More\nthan 50 million spatial records went through ETL pipelines that transformed them\nto EPSG:4326 on the way in. Average response time, 2.5 seconds on the old\ndatabase, dropped below 250 milliseconds once PostGIS answered the queries, a\ntenfold improvement, and backend CPU load fell by 65%. That is PostGIS as the\nreason for a migration.\n\nIt also works as the engine of a clean-up that began with data rather than\nspeed. A large geospatial\nanalytics effort turned up more than 1,000 inconsistencies across geographic and\ntime-series datasets. GDAL, QGIS and ArcGIS were used to find and correct the\nspatial errors, while\n[PostGIS ran the spatial queries and the spatial indexing](/portfolio/resolved-1000-issues-in-geographical-data/),\nwith PL/pgSQL procedures transforming the data inside PostgreSQL and the cleaned\nresult shown in Mapbox. Spatial query run times fell by 35%.\n\n## Where it goes wrong\n\n**Distances come back as tiny decimals.** A query asks how far apart two towns\nare and gets `0.08`. The column is `geometry` in SRID 4326, so the answer is in\ndegrees, and a degree of longitude shrinks from about 111 kilometres at the\nequator to nothing at the poles. Cast to `geography` for an answer in metres, or\nuse `ST_Transform` to move the data into a projected system suited to the area\nbefore measuring.\n\n**A radius search reads every row.** The table has a spatial index, yet the plan\nshows a sequential scan. The usual cause is a filter written as `ST_Distance(a,\nb) \u003c 500`. `ST_Distance` is absent from the manual's list of functions that use\nthe index on their own, while `ST_DWithin` is on it. Wrapping the indexed column\nin a cast or a transform has the same effect, because an index on `geom` says\nnothing about `geom::geography`.\n\n```sql\n-- a geography column, indexed as stored, measured in metres\nCREATE INDEX depots_geog_idx ON depots USING GIST (geog);\n\nSELECT id FROM depots\nWHERE ST_DWithin(geog, ST_MakePoint(12.57, 55.68)::geography, 500);\n```\n\nIf the data has to stay in a 4326 `geometry` column, either add a `geography`\ncolumn like this one and index it, or create the index on the same expression\nthe query uses. Run `ANALYZE` after a bulk load so the planner knows the index\nis worth taking.\n\n**Points land in the sea.** Every shape keeps its pattern but sits in the wrong\nplace, often on another continent. Two mistakes produce this. `ST_SetSRID` only\nrelabels a geometry and leaves its numbers alone, so using it where\n`ST_Transform` was meant stamps metres as degrees. And longitude and latitude\nwere swapped somewhere upstream: PostGIS, like GeoJSON, expects x before y,\nlongitude before latitude. Use `ST_SetSRID` only to declare what the numbers\nalready are, `ST_Transform` to convert them, and test every import with one\npoint whose location you know.\n\n**Area and overlap calculations throw errors.** An import from a shapefile\nsucceeds, and later `ST_Intersection` fails with a topology exception. PostGIS\nstores invalid geometry on purpose, so it can be found and repaired, and a\npolygon whose boundary crosses itself is invalid. Check with `ST_IsValid`,\nrepair with `ST_MakeValid`, which keeps every input vertex, and add a check\nconstraint so that a bad shape is refused at the door instead of discovered in a\nreport.\n\n## Further reading\n\n- [PostGIS Documentation](https://postgis.net/documentation/) — the project's\n  own index to the manual, the FAQ and its training material.\n- [Data Management](https://postgis.net/docs/using_postgis_dbmanagement.html) —\n  geometry and geography, SRIDs, validity rules and the three index types, as\n  the manual defines them.\n- [Spatial Indexing](https://postgis.net/workshops/postgis-intro/indexing.html)\n  — the workshop chapter on bounding boxes and the functions that use an index\n  without being told.\n- [ST_DWithin](https://postgis.net/docs/ST_DWithin.html) — the reference page\n  for the distance test, with its units for each type.\n- [Simple Feature Access – Part 1](https://www.ogc.org/standards/sfa/) — the OGC\n  standard behind the geometry types PostGIS stores.\n\n\u003chttps://engineer.company/glossary/postgis/\u003e\n","date_modified":"2026-11-08T11:12:58Z","description":"How PostGIS turns PostgreSQL into a spatial database, when to pick geometry over geography, and the four mistakes that make map queries slow or wrong.","formats":{"gemtext":"https://engineer.company/glossary/postgis/index.gmi","gopher":"https://engineer.company/glossary/postgis/gophermap","html":"https://engineer.company/glossary/postgis/","json":"https://engineer.company/glossary/postgis/index.json","markdown":"https://engineer.company/glossary/postgis/index.md","pdf":"https://engineer.company/glossary/postgis/index.pdf"},"kind":"page","language":"en","title":"What is PostGIS?","url":"https://engineer.company/glossary/postgis/","version":1}