Noções Básicas de PostGIS

O PostGIS adiciona tipos de geometria e geografia, funções espaciais e índices ao PostgreSQL. Mantenha dados geoespaciais transacionais no Postgres; envie a renderização de mapas e cálculos pesados de tiles para servidores de tiles ou bibliotecas do lado do cliente.

Receita

CREATE EXTENSION IF NOT EXISTS postgis WITH SCHEMA extensions VERSION '3.5.2';
 
CREATE TABLE stores (
  id        serial PRIMARY KEY,
  name      text NOT NULL,
  geom      extensions.geometry(Point, 4326) NOT NULL
);
 
INSERT INTO stores (name, geom) VALUES
  ('NYC Flagship', extensions.ST_SetSRID(extensions.ST_MakePoint(-73.9857, 40.7484), 4326)),
  ('LA Branch',    extensions.ST_SetSRID(extensions.ST_MakePoint(-118.2437, 34.0522), 4326));
 
-- Lojas próximas a até 5 km de um ponto (geography para distâncias em metros)
SELECT name,
       extensions.ST_Distance(
         geom::extensions.geography,
         extensions.ST_SetSRID(extensions.ST_MakePoint(-73.99, 40.75), 4326)::extensions.geography
       ) AS meters
FROM stores
ORDER BY meters
LIMIT 10;

Quando usar isso: Zonas de entrega, rastreamento de ativos, geofencing e junções espaciais onde os dados já residem em seu banco de dados OLTP.

Exemplo de Trabalho

CREATE INDEX stores_geom_gist ON stores USING gist (geom);
 
EXPLAIN (ANALYZE, BUFFERS)
SELECT id, name
FROM stores
WHERE extensions.ST_DWithin(
  geom::extensions.geography,
  extensions.ST_SetSRID(extensions.ST_MakePoint(-73.99, 40.75), 4326)::extensions.geography,
  5000
);
 
SELECT extensions.PostGIS_Version();
SELECT extensions.ST_AsGeoJSON(geom) FROM stores WHERE id = 1;

O que isso demonstra:

• geometry(Point, 4326) armazena lat/lon WGS84
• Cast para geography para distâncias geodésicas em metros
• Índice GiST suporta pré-filtragem de caixa delimitadora ST_DWithin
• ST_AsGeoJSON alimenta mapas web sem um pipeline de exportação separado

Mergulho Profundo

Postgres vs. Servidor de Tiles

Padrão: PostGIS é o sistema de registro. O servidor de tiles gera tiles vetoriais para mapas base e sobreposições. O aplicativo consulta o Postgres para pesquisa, entradas de roteamento e lógica de negócios.

Tipos Principais

• geometry - Matemática planar em um sistema de coordenadas projetado; rápido para áreas locais com SRID correto.
• geography - Cálculos de esferoide; distâncias em metros em WGS84.
• SRID 4326 - Padrão de lat/lon GPS para mapas web.

Ordem de Instalação

CREATE EXTENSION postgis;
-- add-ons opcionais após o núcleo
CREATE EXTENSION postgis_topology;
CREATE EXTENSION postgis_raster;  -- se cargas de trabalho raster forem aprovadas

Fixe versões na lista de permissões do ADR. Atualize com ALTER EXTENSION postgis UPDATE e postgis_extensions_upgrade() quando as notas de lançamento exigirem.

Saída da API

-- GeoJSON para APIs
SELECT json_build_object(
  'type', 'FeatureCollection',
  'features', json_agg(extensions.ST_AsGeoJSON(s.*)::json)
) FROM stores s;

Armadilhas

• Lat/lon invertidos - ST_MakePoint(lon, lat) e não (lat, lon). Correção: Convenção de revisão de código; testes de sanidade ST_Y/ST_X.
• SRID ausente - Geometrias SRID 0 quebram a semântica de distância. Correção: Restrição NOT NULL com geometry(Point, 4326) e ST_SetSRID na inserção.
• Geometria para distância global - Unidades incorretas na geometria 4326. Correção: Converter para geography para metros ou projetar para UTM local.
• Servir tiles de SQL bruto - ST_AsMVT pesado em tabelas não indexadas derrete a CPU. Correção: Camada de tiles dedicada com geom simplificada e GiST.
• WKT não validado - Polígonos inválidos de uploads de usuários. Correção: Restrição de verificação ST_IsValid ou ST_MakeValid na ingestão com auditoria.
• PostGIS no esquema público - Polui o search_path. Correção: WITH SCHEMA extensions em novas instalações.

Alternativas

FAQs

Relacionados

• Geometria vs Geografia - tipos e distância
• Índices Espaciais - padrões GiST
• Desempenho do PostGIS - simplificar e pré-filtrar
• Noções Básicas de Extensões - instalar e fixar
• Melhores Práticas do PostGIS - SRID e validação

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PostGIS 3.5+, pgbouncer 1.x e Patroni 3.x.