feat(exports): wire postcodes table into all export formats (#1039)

[dr5hn]

Summary

Completes the deferred export-pipeline work from #1398. With the postcodes table landed and #1401/#1402 starting to populate it, every export command and the export workflow itself now emit postcode data alongside the existing 5 tables.

Files changed (9)

PHP commands (bin/Commands/)

File	Change
ExportJson.php	SELECT from postcodes (graceful skip if table missing); emit /json/postcodes.json
ExportCsv.php	Add postcodes to FILES; guard empty arrays so empty source files no longer crash on $csc[0] access
ExportXml.php	Add postcodes to FILES; replace fragile ?: throw on empty arrays with explicit is_array() check
ExportYaml.php	Same as XML
ExportSqlServer.php	Add postcodes to TABLES with full CREATE TABLE schema (FKs to countries/states/cities, nullable state_id/city_id)
ExportMongoDB.php	Add postcodes to COLLECTIONS plus new processPostcodes() method with country/state DBRef refs and GeoJSON Point location

Python helpers (bin/scripts/)

File	Change
export/export_plist.py	Include postcodes.csv with missing-file guard so the script no-ops cleanly when no postcodes have landed yet
sync/sync_mysql_to_json.py	New sync_postcodes() per-country file writer (mirrors sync_cities); export_schema() includes postcodes when present

Workflow (.github/workflows/export.yml)

• postcode_count env var with graceful fallback to 0 if table absent
• mysqldump postcodes → sql/postcodes.sql
• pg_dump postcodes → psql/postcodes.sql
• mysql2sqlite postcodes → sqlite/postcodes.sqlite3
• mongoimport gated on non-empty postcodes.json (uses jq)
• gzip postcodes.sql in sql/ and psql/ when present
• POSTCODE_COUNT exposed to Release body and PR body
• DROP order updated: postcodes drops first (FKs to countries/states/cities)

Behaviour with empty postcodes table

This PR is designed to ship cleanly even if postcodes is empty:

• Importer/JSON/XML/YAML produce empty postcodes.json / .xml / .yml files without erroring
• CSV writes an empty file and emits a "no records" note
• mongoimport skipped via jq length check
• mysqldump still emits the (empty) DDL — so consumers can rely on the table existing in every export format
• sync_postcodes skips writing files when no rows exist (no spurious empty LI.json etc.)

Why bundle 9 files in one PR

Each file's change is small (1–60 lines), but they're functionally interdependent: ExportJson produces postcodes.json, which ExportCsv/Xml/Yaml consume; the workflow expects all formats to exist. Splitting would create CI-broken intermediate states.

Test plan

• All 6 PHP files lint clean (php -l)
• Both Python scripts compile (python3 -m py_compile)
• Workflow YAML is valid (yaml.safe_load)
• DROP TABLE order respects FK dependencies (postcodes → cities → states → countries → subregions → regions)
• Reviewer runs php console export:json against a world DB with postcodes table populated
• Reviewer runs php console export:json against a world DB without postcodes table — should not crash
• Reviewer triggers the workflow once feat(postcodes/LI): add Liechtenstein postcodes (#1039) #1401 / feat(postcodes/MC): add Monaco postcode (#1039) #1402 country data has merged

Out of scope / follow-ups

• GeoJSON / Toon converters (bin/scripts/export/json_to_geojson.py, json_to_toon.py) — these have hardcoded ["cities", "states", "countries"] lists. Postcode geo-coordinates are sparse (most rows null) and Toon serialisation of postcode arrays would benefit from a separate review. Tracked for a follow-up PR.
• PostgreSQL schema dump (psql/schema.sql) — auto-generated by pg_dump --schema-only in the workflow, so picks up postcodes automatically once the table exists in PostgreSQL via NMIG.

Refs: #1039
Builds on: #1398

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Wires the new postcodes table into the export pipeline so that all export formats (and the export workflow) emit postcode data alongside existing tables.

Changes:

• Added postcodes to JSON/CSV/XML/YAML/MongoDB/SQL Server exporters and to the export workflow artifacts.
• Added MySQL→contributions reverse-sync support for per-country contributions/postcodes/<ISO2>.json output when the table exists.
• Updated plist export helper to include postcodes.csv and skip cleanly when the source file is missing.

Reviewed changes

Copilot reviewed 1 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
bin/scripts/sync/sync_mysql_to_json.py	Adds sync_postcodes() and conditionally includes postcodes in schema export when present.
bin/scripts/export/export_plist.py	Includes postcodes.csv and adds missing-file guard.
bin/Commands/ExportYaml.php	Adds YAML export for /json/postcodes.json and hardens JSON decode handling for empty arrays.
bin/Commands/ExportXml.php	Adds XML export for /json/postcodes.json and hardens JSON decode handling for empty arrays.
bin/Commands/ExportSqlServer.php	Adds postcodes table DDL and includes it in SQL Server export set.
bin/Commands/ExportMongoDB.php	Adds postcodes collection export with DBRefs and optional GeoJSON location.
bin/Commands/ExportJson.php	Emits /json/postcodes.json, skipping gracefully if the DB table is missing.
bin/Commands/ExportCsv.php	Adds postcodes to CSV exports and avoids crashing on empty datasets.
.github/workflows/export.yml	Exports/archives postcodes across SQL/SQLite/MongoDB and exposes POSTCODE_COUNT in release/PR metadata.