@nspot/geo-engine 0.4.0 → 0.5.0

package/sql/009_localities.sql

@@ -0,0 +1,665 @@
+-- ============================================================================
+-- 009 — localities: named points beside regions
+--
+-- A locality is a place with a name and a code but no boundary: Romania's
+-- villages and the component localities of its towns. It has a label point
+-- (where its name goes on a map) or, when its source has none, a reason in
+-- point_gap. Its identity is (country, code), the target of host foreign keys,
+-- so a host's rows can name a locality the same way in every database.
+-- Localities have no membership: a host row declares its locality.
+-- ============================================================================
+
+-- Lower case ASCII for search: the Latin diacritics of the region folded, in
+-- both cases (lower() leaves them alone under lc_ctype C), ß as ss, runs of
+-- whitespace and hyphens as one space, trimmed.
+CREATE OR REPLACE FUNCTION geo.fold(p text) RETURNS text
+LANGUAGE sql IMMUTABLE PARALLEL SAFE STRICT AS $$
+  SELECT btrim(regexp_replace(lower(translate(replace(replace(p, 'ß', 'ss'), 'ẞ', 'ss'),
+    'șşțţăâîáàäãåéèëêíìïóòöőôõúùüűûýÿçčćñňšśžźżłđďťř'
+    || 'ȘŞȚŢĂÂÎÁÀÄÃÅÉÈËÊÍÌÏÓÒÖŐÔÕÚÙÜŰÛÝŸÇČĆÑŇŠŚŽŹŻŁĐĎŤŘ',
+    'ssttaaiaaaaaeeeeiiioooooouuuuuyycccnnsszzzlddtr'
+    || 'ssttaaiaaaaaeeeeiiioooooouuuuuyycccnnsszzzlddtr')), '[\s-]+', ' ', 'g'))
+$$;
+
+CREATE TABLE geo.localities (
+  id                      serial PRIMARY KEY,
+  country                 char(2) NOT NULL REFERENCES geo.countries(code) ON DELETE CASCADE,
+  code                    text    NOT NULL,
+  name                    text    NOT NULL,
+  name_key                text    GENERATED ALWAYS AS (geo.fold(name)) STORED,
+  parent_id               int     REFERENCES geo.regions(id) ON DELETE SET NULL,
+  declared_parent         text,
+  declared_parent_country char(2),
+  point                   geometry(Point, 4326),
+  point_gap               text,
+  tags                    text[]  NOT NULL DEFAULT '{}',
+  properties              jsonb   NOT NULL DEFAULT '{}',
+  pack_id                 int     REFERENCES geo.packs(id) ON DELETE SET NULL,
+  created_at              timestamptz NOT NULL DEFAULT now(),
+  updated_at              timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (country, code),
+  CHECK (code <> '' AND name <> ''),
+  CHECK ((point IS NULL) = (point_gap IS NOT NULL))
+);
+CREATE INDEX localities_point_gix      ON geo.localities USING GIST (point);
+CREATE INDEX localities_point_geog_gix ON geo.localities USING GIST ((point::geography));
+CREATE INDEX localities_parent_idx     ON geo.localities (parent_id);
+CREATE INDEX localities_pack_idx       ON geo.localities (pack_id);
+CREATE TRIGGER localities_updated_at_trg BEFORE UPDATE ON geo.localities
+  FOR EACH ROW EXECUTE FUNCTION geo.set_updated_at();
+
+COMMENT ON TABLE geo.localities IS
+  'Named points: a code, a name, a parent region, a label point or a gap reason. Hosts reference (country, code).';
+
+-- A GeoJSON Point as a 4326 point, NULL for NULL; p_where names the locality in errors.
+CREATE OR REPLACE FUNCTION geo.locality_point(p_geojson jsonb, p_where text) RETURNS geometry
+LANGUAGE plpgsql IMMUTABLE AS $$
+DECLARE
+  g geometry;
+BEGIN
+  IF p_geojson IS NULL OR jsonb_typeof(p_geojson) = 'null' THEN
+    RETURN NULL;
+  END IF;
+  IF jsonb_typeof(p_geojson) <> 'object' OR p_geojson->>'type' IS DISTINCT FROM 'Point' THEN
+    RAISE EXCEPTION '%: a locality''s point must be a GeoJSON Point or null', p_where
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF jsonb_typeof(p_geojson->'coordinates') IS DISTINCT FROM 'array'
+     OR jsonb_array_length(p_geojson->'coordinates') NOT IN (2, 3)
+     OR EXISTS (SELECT 1 FROM jsonb_array_elements(p_geojson->'coordinates') c
+                WHERE jsonb_typeof(c) <> 'number') THEN
+    RAISE EXCEPTION '%: a Point''s coordinates must be [lng, lat], got %', p_where, p_geojson->'coordinates'
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  g := ST_SetSRID(ST_GeomFromGeoJSON(p_geojson), 4326);
+  IF ST_X(g) NOT BETWEEN -180 AND 180 OR ST_Y(g) NOT BETWEEN -90 AND 90 THEN
+    RAISE EXCEPTION '%: point [%, %] is outside -180..180, -90..90', p_where, ST_X(g), ST_Y(g)
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  RETURN ST_Force2D(g);
+END $$;
+
+-- What every read returns. distance_m, rounded to 0.1 m, is added last when given.
+CREATE OR REPLACE FUNCTION geo.locality_summary(l geo.localities, p_distance_m float8 DEFAULT NULL) RETURNS json
+LANGUAGE sql STABLE AS $$
+  -- Both branches build the same object and must stay in step; the second only
+  -- appends distance_m last, which one json_build_object cannot leave out.
+  SELECT CASE WHEN p_distance_m IS NULL THEN
+    json_build_object(
+      'country', l.country, 'code', l.code, 'name', l.name,
+      'point', CASE WHEN l.point IS NULL THEN NULL ELSE json_build_array(ST_X(l.point), ST_Y(l.point)) END,
+      'point_gap', l.point_gap,
+      'parent', (SELECT json_build_object('slug', r.slug, 'name', r.name) FROM geo.regions r WHERE r.id = l.parent_id),
+      'tags', to_json(l.tags), 'properties', l.properties,
+      'pack', (SELECT p.slug FROM geo.packs p WHERE p.id = l.pack_id))
+  ELSE
+    json_build_object(
+      'country', l.country, 'code', l.code, 'name', l.name,
+      'point', CASE WHEN l.point IS NULL THEN NULL ELSE json_build_array(ST_X(l.point), ST_Y(l.point)) END,
+      'point_gap', l.point_gap,
+      'parent', (SELECT json_build_object('slug', r.slug, 'name', r.name) FROM geo.regions r WHERE r.id = l.parent_id),
+      'tags', to_json(l.tags), 'properties', l.properties,
+      'pack', (SELECT p.slug FROM geo.packs p WHERE p.id = l.pack_id),
+      'distance_m', round(p_distance_m::numeric, 1))
+  END
+$$;
+
+-- Link every pack locality to the pack region its pack declared, in any pack,
+-- never a local region (as geo.link_pack_parents does for regions). Returns how
+-- many links changed.
+CREATE OR REPLACE FUNCTION geo.link_pack_locality_parents() RETURNS int
+LANGUAGE sql AS $$
+  WITH target AS (
+    SELECT l.id, (
+      SELECT r.id FROM geo.regions r JOIN geo.countries c ON c.id = r.country_id
+      WHERE r.pack_id IS NOT NULL AND r.slug = l.declared_parent AND c.code = l.declared_parent_country) AS parent
+    FROM geo.localities l
+    WHERE l.pack_id IS NOT NULL
+  ), changed AS (
+    UPDATE geo.localities l SET parent_id = t.parent
+    FROM target t
+    WHERE l.id = t.id AND l.parent_id IS DISTINCT FROM t.parent
+    RETURNING 1
+  )
+  SELECT count(*)::int FROM changed
+$$;
+
+-- "XA 1, XA 2, … and 5 more": the first 20 of a list of codes.
+CREATE OR REPLACE FUNCTION geo.locality_list(p_codes text[]) RETURNS text
+LANGUAGE sql IMMUTABLE AS $$
+  SELECT array_to_string(p_codes[1:20], ', ')
+    || CASE WHEN cardinality(p_codes) > 20 THEN format(' and %s more', cardinality(p_codes) - 20) ELSE '' END
+$$;
+
+-- Delete the given pack's localities that p_keep does not name (NULL keeps none).
+-- A host foreign key that still references one aborts with 23503, naming the
+-- pack (p_label) and the localities leaving, Postgres's own DETAIL kept. Set-based
+-- (an anti-join and a join on ids), since a pack may hold 13,749 of them.
+CREATE OR REPLACE FUNCTION geo.delete_pack_localities(p_pack_id int, p_keep jsonb, p_label text) RETURNS int
+LANGUAGE plpgsql AS $$
+DECLARE
+  ids     int[];
+  leaving text[];
+  n       int;
+  d       text;
+BEGIN
+  SELECT array_agg(l.id), array_agg(l.country || ' ' || l.code ORDER BY l.country, l.code) INTO ids, leaving
+  FROM geo.localities l
+  LEFT JOIN (
+    SELECT upper(f->'properties'->>'country') AS country, f->'properties'->>'code' AS code
+    FROM jsonb_array_elements(coalesce(p_keep, '[]'::jsonb)) f
+  ) k ON k.country = l.country::text AND k.code = l.code
+  WHERE l.pack_id = p_pack_id AND k.code IS NULL;
+  IF ids IS NULL THEN
+    RETURN 0;
+  END IF;
+  BEGIN
+    DELETE FROM geo.localities l USING unnest(ids) AS gone(id) WHERE l.id = gone.id;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  EXCEPTION WHEN foreign_key_violation THEN
+    GET STACKED DIAGNOSTICS d = PG_EXCEPTION_DETAIL;
+    RAISE EXCEPTION '% would remove localities a host still references; leaving: %', p_label, geo.locality_list(leaving)
+      USING ERRCODE = 'foreign_key_violation', DETAIL = d;
+  END;
+  RETURN n;
+END $$;
+
+-- The localities section of a pack, after its regions: check every feature,
+-- refuse codes another owner holds, upsert, delete the ones that left, record
+-- declared parents. Returns how many the pack has.
+CREATE OR REPLACE FUNCTION geo.install_pack_localities(p_pack_id int, p_feats jsonb, p_label text) RETURNS int
+LANGUAGE plpgsql AS $$
+DECLARE
+  v     jsonb;
+  i     int := 0;
+  where_ text;
+  held  text[];
+  written int;
+BEGIN
+  FOR v IN SELECT * FROM jsonb_array_elements(p_feats) LOOP
+    where_ := format('locality %s (%s %s)', i, upper(v->'properties'->>'country'), v->'properties'->>'code');
+    IF coalesce(v->'properties'->>'country', '') = '' OR coalesce(v->'properties'->>'code', '') = ''
+       OR coalesce(v->'properties'->>'name', '') = '' THEN
+      RAISE EXCEPTION 'locality %: country, code and name are required', i USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM geo.countries c WHERE c.code = upper(v->'properties'->>'country')) THEN
+      RAISE EXCEPTION '%: unknown country %', where_, upper(v->'properties'->>'country')
+        USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    IF (coalesce(jsonb_typeof(v->'geometry'), 'null') = 'object') = (coalesce(v->'properties'->>'point_gap', '') <> '') THEN
+      RAISE EXCEPTION '%: give a point or a point_gap, not both and not neither', where_
+        USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    PERFORM geo.locality_point(v->'geometry', where_);
+    i := i + 1;
+  END LOOP;
+
+  -- a code twice in one country: the second occurrence, set-based
+  SELECT format('locality %s (%s %s): code given twice', g.n - 1, g.country, g.code) INTO where_
+  FROM (
+    SELECT t.n, upper(t.feat->'properties'->>'country') AS country, t.feat->'properties'->>'code' AS code,
+           row_number() OVER (PARTITION BY upper(t.feat->'properties'->>'country'), t.feat->'properties'->>'code'
+                              ORDER BY t.n) AS k
+    FROM jsonb_array_elements(p_feats) WITH ORDINALITY AS t(feat, n)
+  ) g
+  WHERE g.k = 2
+  ORDER BY g.n
+  LIMIT 1;
+  IF FOUND THEN
+    RAISE EXCEPTION '%', where_ USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+
+  SELECT array_agg(l.country || ' ' || l.code ORDER BY l.country, l.code) INTO held
+  FROM jsonb_array_elements(p_feats) f
+  JOIN geo.localities l ON l.country = upper(f->'properties'->>'country') AND l.code = f->'properties'->>'code'
+  WHERE l.pack_id IS DISTINCT FROM p_pack_id;
+  IF held IS NOT NULL THEN
+    RAISE EXCEPTION '% has localities another owner holds: %', p_label, geo.locality_list(held)
+      USING ERRCODE = 'unique_violation';
+  END IF;
+
+  INSERT INTO geo.localities AS l
+    (country, code, name, declared_parent, declared_parent_country, point, point_gap, tags, properties, pack_id)
+  SELECT upper(f->'properties'->>'country'), f->'properties'->>'code', f->'properties'->>'name',
+         nullif(f->'properties'->>'parent', ''),
+         CASE WHEN nullif(f->'properties'->>'parent', '') IS NULL THEN NULL
+              ELSE upper(coalesce(f->'properties'->>'parent_country', f->'properties'->>'country')) END,
+         geo.locality_point(f->'geometry', 'locality'),
+         nullif(f->'properties'->>'point_gap', ''),
+         ARRAY(SELECT jsonb_array_elements_text(coalesce(f->'properties'->'tags', '[]'::jsonb))),
+         coalesce(f->'properties'->'properties', '{}'::jsonb),
+         p_pack_id
+  FROM jsonb_array_elements(p_feats) f
+  ON CONFLICT (country, code) DO UPDATE SET
+    name = EXCLUDED.name, declared_parent = EXCLUDED.declared_parent,
+    declared_parent_country = EXCLUDED.declared_parent_country, point = EXCLUDED.point,
+    point_gap = EXCLUDED.point_gap, tags = EXCLUDED.tags, properties = EXCLUDED.properties
+  WHERE l.pack_id = p_pack_id;
+  -- a code another owner took since the check above is skipped by the WHERE: refuse it
+  GET DIAGNOSTICS written = ROW_COUNT;
+  IF written < i THEN
+    RAISE EXCEPTION '% has localities another owner holds', p_label USING ERRCODE = 'unique_violation';
+  END IF;
+
+  PERFORM geo.delete_pack_localities(p_pack_id, p_feats, p_label);
+  RETURN i;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.install_pack(p_pack jsonb) RETURNS jsonb
+LANGUAGE plpgsql AS $$
+DECLARE
+  hdr         jsonb := p_pack->'pack';
+  feats       jsonb := coalesce(p_pack->'regions'->'features', '[]'::jsonb);
+  pid         int;
+  f           jsonb;
+  n_countries int := 0;
+  n_regions   int := 0;
+  n_localities int;
+  n_members   bigint;
+  code        text;
+BEGIN
+  IF hdr IS NULL OR coalesce(hdr->>'slug', '') = '' OR coalesce(hdr->>'version', '') = '' THEN
+    RAISE EXCEPTION 'Pack header must have slug and version' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF coalesce((hdr->>'schema_version')::int, 0) > geo.schema_version() THEN
+    RAISE EXCEPTION 'Pack "%" needs schema version % but this database has %',
+      hdr->>'slug', hdr->>'schema_version', geo.schema_version()
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  -- no key leaves the pack's localities alone; a key must be a usable section,
+  -- since an empty one removes them all
+  IF p_pack ? 'localities' AND (jsonb_typeof(p_pack->'localities') IS DISTINCT FROM 'object'
+     OR jsonb_typeof(p_pack->'localities'->'features') IS DISTINCT FROM 'array') THEN
+    RAISE EXCEPTION 'localities must be a FeatureCollection with a features array'
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+
+  INSERT INTO geo.packs (slug, version, schema_version)
+  VALUES (hdr->>'slug', hdr->>'version', coalesce((hdr->>'schema_version')::int, geo.schema_version()))
+  ON CONFLICT (slug) DO UPDATE
+    SET version = EXCLUDED.version, schema_version = EXCLUDED.schema_version, installed_at = now()
+  RETURNING id INTO pid;
+
+  PERFORM set_config('geo.skip_membership_triggers', 'on', true);
+
+  FOR f IN SELECT * FROM jsonb_array_elements(coalesce(p_pack->'countries', '[]'::jsonb)) LOOP
+    PERFORM geo.upsert_country(f->>'code', f->>'name',
+      CASE WHEN jsonb_typeof(f->'geometry') = 'object' THEN f->'geometry' END);
+    n_countries := n_countries + 1;
+  END LOOP;
+
+  FOR f IN SELECT * FROM jsonb_array_elements(feats) LOOP
+    PERFORM geo.upsert_region(
+      f->'properties'->>'country',
+      f->'properties'->>'slug',
+      f->'properties'->>'name',
+      (f->'properties'->>'type')::geo.region_type,
+      (f->'properties'->>'level')::int,
+      NULL,
+      f->'properties'->>'code',
+      ARRAY(SELECT jsonb_array_elements_text(coalesce(f->'properties'->'tags', '[]'::jsonb))),
+      coalesce(f->'properties'->'properties', '{}'::jsonb),
+      f->'geometry',
+      true,
+      pid);
+    n_regions := n_regions + 1;
+  END LOOP;
+
+  -- regions that left the pack
+  DELETE FROM geo.regions r
+  USING geo.countries c
+  WHERE r.pack_id = pid AND c.id = r.country_id
+    AND NOT EXISTS (
+      SELECT 1 FROM jsonb_array_elements(feats) ff
+      WHERE upper(ff->'properties'->>'country') = c.code AND ff->'properties'->>'slug' = r.slug);
+
+  -- the parent each region declares (a slug, in its parent_country or its own)
+  UPDATE geo.regions r
+  SET declared_parent = nullif(ff->'properties'->>'parent', ''),
+      declared_parent_country = CASE WHEN nullif(ff->'properties'->>'parent', '') IS NULL THEN NULL
+        ELSE upper(coalesce(ff->'properties'->>'parent_country', ff->'properties'->>'country')) END
+  FROM jsonb_array_elements(feats) ff
+  JOIN geo.countries c ON c.code = upper(ff->'properties'->>'country')
+  WHERE r.pack_id = pid AND r.country_id = c.id AND r.slug = ff->'properties'->>'slug';
+
+  -- parents among pack regions, this pack's and every other's
+  PERFORM geo.link_pack_parents();
+
+  IF p_pack ? 'localities' THEN
+    n_localities := geo.install_pack_localities(pid, p_pack->'localities'->'features',
+      format('Pack "%s" %s', hdr->>'slug', hdr->>'version'));
+  END IF;
+  PERFORM geo.link_pack_locality_parents();
+
+  FOR code IN SELECT c.code FROM geo.countries c WHERE c.geom IS NULL LOOP
+    PERFORM geo.derive_country_geom(code);
+  END LOOP;
+
+  n_members := geo.rebuild_all_memberships();
+  PERFORM set_config('geo.skip_membership_triggers', 'off', true);
+  RETURN jsonb_build_object(
+    'pack', hdr->>'slug', 'version', hdr->>'version',
+    'countries', n_countries, 'regions', n_regions, 'memberships', n_members)
+    || CASE WHEN n_localities IS NULL THEN '{}'::jsonb ELSE jsonb_build_object('localities', n_localities) END;
+END $$;
+
+
+CREATE OR REPLACE FUNCTION geo.uninstall_pack(p_slug text) RETURNS int
+LANGUAGE plpgsql AS $$
+DECLARE
+  pid int;
+  n   int;
+BEGIN
+  SELECT id INTO pid FROM geo.packs WHERE slug = p_slug;
+  IF pid IS NULL THEN
+    RAISE EXCEPTION 'Unknown pack "%"', p_slug USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  PERFORM geo.delete_pack_localities(pid, NULL,
+    format('Pack "%s" %s', p_slug, (SELECT version FROM geo.packs WHERE id = pid)));
+  DELETE FROM geo.regions WHERE pack_id = pid;   -- memberships cascade
+  GET DIAGNOSTICS n = ROW_COUNT;
+  DELETE FROM geo.packs WHERE id = pid;
+  RETURN n;
+END $$;
+
+
+CREATE OR REPLACE FUNCTION geo.localities_by_code(p_codes text[], p_country text DEFAULT NULL) RETURNS SETOF json
+LANGUAGE sql STABLE AS $$
+  -- a code given twice answers once, at its first position
+  SELECT geo.locality_summary(l)
+  FROM (SELECT u.code, min(u.ord) AS ord FROM unnest(p_codes) WITH ORDINALITY AS u(code, ord) GROUP BY u.code) c
+  JOIN geo.localities l ON l.code = c.code AND (p_country IS NULL OR l.country = upper(p_country))
+  ORDER BY c.ord, l.country
+$$;
+
+-- The region ids and every region below them.
+CREATE OR REPLACE FUNCTION geo.region_tree(p_ids int[]) RETURNS SETOF int
+LANGUAGE sql STABLE AS $$
+  WITH RECURSIVE tree AS (
+    SELECT unnest(p_ids) AS id
+    UNION
+    SELECT r.id FROM geo.regions r JOIN tree t ON r.parent_id = t.id
+  )
+  SELECT id FROM tree
+$$;
+
+CREATE OR REPLACE FUNCTION geo.localities_in(p_regions text[], p_via text DEFAULT 'parent') RETURNS SETOF json
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  ids int[];
+BEGIN
+  IF p_via IS NULL OR p_via NOT IN ('parent', 'point') THEN
+    RAISE EXCEPTION 'via must be parent or point, got %', p_via USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF p_regions IS NULL OR cardinality(p_regions) = 0 THEN
+    RAISE EXCEPTION 'name at least one region' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  ids := geo.resolve_regions(p_regions);
+  IF p_via = 'parent' THEN
+    RETURN QUERY
+      SELECT geo.locality_summary(l) FROM geo.localities l
+      WHERE l.parent_id IN (SELECT geo.region_tree(ids))
+      ORDER BY l.name_key, l.name, l.country, l.code;
+  ELSE
+    RETURN QUERY
+      SELECT geo.locality_summary(l) FROM geo.localities l
+      WHERE l.point IS NOT NULL
+        AND EXISTS (SELECT 1 FROM geo.regions r WHERE r.id = ANY (ids) AND ST_Intersects(r.geom, l.point))
+      ORDER BY l.name_key, l.name, l.country, l.code;
+  END IF;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.check_limit(p_limit int) RETURNS void
+LANGUAGE plpgsql IMMUTABLE AS $$
+BEGIN
+  IF p_limit IS NULL OR p_limit < 1 OR p_limit > 1000 THEN
+    RAISE EXCEPTION 'limit must be 1 to 1000, got %', coalesce(p_limit::text, 'null')
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.search_localities(p_query text, p_within text[] DEFAULT NULL, p_limit int DEFAULT 20)
+RETURNS SETOF json
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  q      text := coalesce(geo.fold(p_query), '');
+  within int[];
+BEGIN
+  IF q = '' THEN
+    RAISE EXCEPTION 'query must not be empty' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF p_within IS NOT NULL AND cardinality(p_within) = 0 THEN
+    RAISE EXCEPTION 'within must name at least one region, or be null' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  PERFORM geo.check_limit(p_limit);
+  IF p_within IS NOT NULL THEN
+    within := ARRAY(SELECT geo.region_tree(geo.resolve_regions(p_within)));
+  END IF;
+  RETURN QUERY
+    SELECT geo.locality_summary(l) FROM geo.localities l
+    WHERE strpos(l.name_key, q) > 0
+      AND (within IS NULL OR l.parent_id = ANY (within))
+    ORDER BY CASE WHEN l.name_key = q THEN 0 WHEN starts_with(l.name_key, q) THEN 1 ELSE 2 END,
+             l.name_key, l.name, l.country, l.code
+    LIMIT p_limit;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.localities_near(p_lng float8, p_lat float8, p_limit int DEFAULT 10, p_max_m float8 DEFAULT NULL)
+RETURNS SETOF json
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  here geography;
+BEGIN
+  IF p_lng IS NULL OR p_lat IS NULL OR p_lng NOT BETWEEN -180 AND 180 OR p_lat NOT BETWEEN -90 AND 90 THEN
+    RAISE EXCEPTION 'lng must be -180..180 and lat -90..90, got %, %', p_lng, p_lat
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  PERFORM geo.check_limit(p_limit);
+  IF p_max_m IS NOT NULL AND p_max_m < 0 THEN
+    RAISE EXCEPTION 'max_m must be 0 or more, got %', p_max_m USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  here := ST_SetSRID(ST_MakePoint(p_lng, p_lat), 4326)::geography;
+  RETURN QUERY
+    SELECT geo.locality_summary(n.l, n.m)
+    FROM (
+      SELECT l, ST_Distance(l.point::geography, here) AS m
+      FROM geo.localities l
+      WHERE l.point IS NOT NULL
+        AND (p_max_m IS NULL OR ST_DWithin(l.point::geography, here, p_max_m))
+      ORDER BY l.point::geography <-> here
+      LIMIT p_limit
+    ) n
+    ORDER BY n.m, (n.l).country, (n.l).code;
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.upsert_locality(
+  p_country        text,
+  p_code           text,
+  p_name           text,
+  p_parent         text  DEFAULT NULL,
+  p_parent_country text  DEFAULT NULL,
+  p_point          jsonb DEFAULT NULL,
+  p_point_gap      text  DEFAULT NULL,
+  p_tags           text[] DEFAULT '{}',
+  p_properties     jsonb DEFAULT '{}'
+) RETURNS json
+LANGUAGE plpgsql AS $$
+DECLARE
+  cc     text := upper(p_country);
+  owner_ text;
+  parent int;
+  saved  geo.localities;
+BEGIN
+  IF coalesce(p_code, '') = '' OR coalesce(p_name, '') = '' THEN
+    RAISE EXCEPTION 'A locality needs a code and a name' USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  SELECT p.slug INTO owner_ FROM geo.localities l JOIN geo.packs p ON p.id = l.pack_id
+  WHERE l.country = cc AND l.code = p_code;
+  IF owner_ IS NOT NULL THEN
+    RAISE EXCEPTION 'Locality % % belongs to pack "%"; update or uninstall the pack instead', cc, p_code, owner_
+      USING ERRCODE = 'unique_violation';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM geo.countries WHERE code = cc) THEN
+    RAISE EXCEPTION 'Unknown country "%"', cc USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF (p_point IS NOT NULL AND jsonb_typeof(p_point) <> 'null') = (coalesce(p_point_gap, '') <> '') THEN
+    RAISE EXCEPTION 'locality % %: give a point or a point_gap, not both and not neither', cc, p_code
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  p_parent := nullif(p_parent, '');   -- '' is no parent
+  IF p_parent IS NOT NULL THEN
+    SELECT r.id INTO parent FROM geo.regions r JOIN geo.countries c ON c.id = r.country_id
+    WHERE r.slug = p_parent AND c.code = upper(coalesce(p_parent_country, cc));
+    IF parent IS NULL THEN
+      RAISE EXCEPTION 'Unknown parent region "%" in %', p_parent, upper(coalesce(p_parent_country, cc))
+        USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+  END IF;
+  INSERT INTO geo.localities AS l (country, code, name, parent_id, point, point_gap, tags, properties)
+  VALUES (cc, p_code, p_name, parent, geo.locality_point(p_point, format('locality %s %s', cc, p_code)),
+          nullif(p_point_gap, ''), coalesce(p_tags, '{}'), coalesce(p_properties, '{}'))
+  ON CONFLICT (country, code) DO UPDATE SET
+    name = EXCLUDED.name, parent_id = EXCLUDED.parent_id, point = EXCLUDED.point,
+    point_gap = EXCLUDED.point_gap, tags = EXCLUDED.tags, properties = EXCLUDED.properties
+  WHERE l.pack_id IS NULL
+  RETURNING * INTO saved;
+  -- a pack installed it since the check above: the WHERE skipped the update
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Locality % % belongs to a pack; update or uninstall the pack instead', cc, p_code
+      USING ERRCODE = 'unique_violation';
+  END IF;
+  RETURN geo.locality_summary(saved);
+END $$;
+
+CREATE OR REPLACE FUNCTION geo.delete_locality(p_country text, p_code text) RETURNS boolean
+LANGUAGE plpgsql AS $$
+DECLARE
+  owner_ text;
+  n      int;
+  d      text;
+BEGIN
+  SELECT p.slug INTO owner_ FROM geo.localities l JOIN geo.packs p ON p.id = l.pack_id
+  WHERE l.country = upper(p_country) AND l.code = p_code;
+  IF owner_ IS NOT NULL THEN
+    RAISE EXCEPTION 'Locality % % belongs to pack "%"; update or uninstall the pack instead', upper(p_country), p_code, owner_
+      USING ERRCODE = 'unique_violation';
+  END IF;
+  BEGIN
+    DELETE FROM geo.localities WHERE country = upper(p_country) AND code = p_code AND pack_id IS NULL;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  EXCEPTION WHEN foreign_key_violation THEN
+    GET STACKED DIAGNOSTICS d = PG_EXCEPTION_DETAIL;
+    RAISE EXCEPTION 'Locality % % is still referenced: a host still references it', upper(p_country), p_code
+      USING ERRCODE = 'foreign_key_violation', DETAIL = d;
+  END;
+  RETURN n > 0;
+END $$;
+
+-- export_pack as in 007, plus p_include: 'all' (the default), 'regions' or
+-- 'localities'. Under 'all' a localities section is written only when there are
+-- localities to write, so a pack without them exports exactly as before; under
+-- 'localities' it is always written, so installing an empty one empties the pack.
+-- A slug prefix also selects the localities whose parent region it selects.
+DROP FUNCTION geo.export_pack(text, text, text, text);
+CREATE OR REPLACE FUNCTION geo.export_pack(
+  p_slug        text,
+  p_version     text,
+  p_owner       text DEFAULT NULL,
+  p_slug_prefix text DEFAULT NULL,
+  p_include     text DEFAULT 'all'
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  owner_id int;
+  scoped   boolean := p_owner IS NOT NULL OR p_slug_prefix IS NOT NULL OR p_include <> 'all';
+BEGIN
+  IF p_include IS NULL OR p_include NOT IN ('all', 'regions', 'localities') THEN
+    RAISE EXCEPTION 'include must be all, regions or localities, got %', p_include
+      USING ERRCODE = 'invalid_parameter_value';
+  END IF;
+  IF p_owner IS NOT NULL AND p_owner <> 'local' THEN
+    SELECT id INTO owner_id FROM geo.packs WHERE slug = p_owner;
+    IF owner_id IS NULL THEN
+      RAISE EXCEPTION 'Unknown pack "%"', p_owner USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+  END IF;
+
+  RETURN (
+    WITH sel AS (
+      SELECT r.*
+      FROM geo.regions r
+      WHERE (p_owner IS NULL
+             OR (p_owner = 'local' AND r.pack_id IS NULL)
+             OR r.pack_id = owner_id)
+        AND (p_slug_prefix IS NULL OR starts_with(r.slug, p_slug_prefix))
+        AND p_include <> 'localities'
+    ),
+    feats AS (
+      SELECT c.code AS country, r.slug, jsonb_build_object(
+        'type', 'Feature',
+        'geometry', ST_AsGeoJSON(r.geom, 6)::jsonb,
+        'properties', jsonb_build_object(
+          'country', c.code, 'slug', r.slug, 'name', r.name, 'type', r.type, 'level', r.level,
+          'parent', coalesce(p.slug, r.declared_parent),
+          'parent_country', CASE WHEN p.id IS NOT NULL THEN pc.code ELSE r.declared_parent_country END,
+          'code', r.code, 'tags', to_jsonb(r.tags), 'properties', r.properties)) AS feature,
+        coalesce(pc.code, r.declared_parent_country) AS parent_country
+      FROM sel r
+      JOIN geo.countries c ON c.id = r.country_id
+      LEFT JOIN geo.regions p ON p.id = r.parent_id
+      LEFT JOIN geo.countries pc ON pc.id = p.country_id
+    ),
+    -- with a slug prefix, only the localities whose parent region the prefix selects
+    lsel AS (
+      SELECT l.* FROM geo.localities l
+      WHERE p_include <> 'regions'
+        AND (p_owner IS NULL OR (p_owner = 'local' AND l.pack_id IS NULL) OR l.pack_id = owner_id)
+        AND (p_slug_prefix IS NULL OR l.parent_id IN (
+              SELECT r.id FROM geo.regions r WHERE starts_with(r.slug, p_slug_prefix)))
+    ),
+    lfeats AS (
+      SELECT l.country, l.code, jsonb_build_object(
+        'type', 'Feature',
+        'geometry', CASE WHEN l.point IS NULL THEN NULL ELSE ST_AsGeoJSON(l.point, 6)::jsonb END,
+        'properties', jsonb_build_object(
+          'country', l.country, 'code', l.code, 'name', l.name,
+          'parent', coalesce(p.slug, l.declared_parent),
+          'parent_country', CASE WHEN p.id IS NOT NULL THEN pc.code ELSE l.declared_parent_country END,
+          'point_gap', l.point_gap, 'tags', to_jsonb(l.tags), 'properties', l.properties)) AS feature,
+        coalesce(pc.code, l.declared_parent_country) AS parent_country
+      FROM lsel l
+      LEFT JOIN geo.regions p ON p.id = l.parent_id
+      LEFT JOIN geo.countries pc ON pc.id = p.country_id
+    ),
+    needed AS (
+      SELECT country AS code FROM feats
+      UNION
+      SELECT parent_country FROM feats WHERE parent_country IS NOT NULL
+      UNION
+      SELECT country FROM lfeats
+      UNION
+      SELECT parent_country FROM lfeats WHERE parent_country IS NOT NULL
+    )
+    SELECT jsonb_build_object(
+      'pack', jsonb_build_object(
+        'slug', p_slug, 'version', p_version, 'schema_version', geo.schema_version(),
+        'published_at', to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"')),
+      'countries', coalesce((
+        SELECT jsonb_agg(jsonb_build_object(
+          'code', c.code, 'name', c.name,
+          'geometry', CASE WHEN scoped OR c.geom IS NULL THEN NULL ELSE ST_AsGeoJSON(c.geom, 6)::jsonb END
+        ) ORDER BY c.code)
+        FROM geo.countries c
+        WHERE NOT scoped OR c.code IN (SELECT code FROM needed)), '[]'::jsonb),
+      'regions', jsonb_build_object(
+        'type', 'FeatureCollection',
+        'features', coalesce((SELECT jsonb_agg(feature ORDER BY country, slug) FROM feats), '[]'::jsonb)))
+    || CASE WHEN p_include = 'localities' OR EXISTS (SELECT 1 FROM lfeats) THEN
+         jsonb_build_object('localities', jsonb_build_object(
+           'type', 'FeatureCollection',
+           'features', coalesce((SELECT jsonb_agg(feature ORDER BY country, code) FROM lfeats), '[]'::jsonb)))
+       ELSE '{}'::jsonb END
+  );
+END $$;
+
+SELECT geo.pin_search_path();