From 5caceb535cfe67493b63da8080f0cd8768778a8d Mon Sep 17 00:00:00 2001 From: mkbadeniyi Date: Sun, 11 Oct 2026 00:26:09 +0100 Subject: [PATCH 1/4] feat(sql): stamp a version on both files and report it --- docs/llms-full.txt | 1 + scripts/sql_conformance.py | 12 ++++++++++-- sql/README.md | 1 + sql/duckdb.sql | 4 ++++ sql/postgres.sql | 5 +++++ 5 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 38501e7..7a9fe4d 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -966,5 +966,6 @@ SELECT * FROM customers WHERE postcode >= 'EK01A03' AND postcode < 'EK01A03' || | `ng_postcode_truncate(code, segment)` | The prefix through `state`, `lga`, `district`, `area`, or `unit` | | `ng_postcode_parent(prefix)` | The prefix one segment shorter, or NULL for a state | | `ng_postcode_within(code, prefix)` | Whether the code starts with the prefix | +| `ng_postcode_version()` | The version of the file that was loaded | A well-formed code is not necessarily assigned to a building. Only the NIPOST API can confirm that, through one of the [libraries](../README.md). diff --git a/scripts/sql_conformance.py b/scripts/sql_conformance.py index ee0ff50..c598d1f 100644 --- a/scripts/sql_conformance.py +++ b/scripts/sql_conformance.py @@ -10,6 +10,7 @@ from __future__ import annotations import json +import re import subprocess import sys from pathlib import Path @@ -21,7 +22,7 @@ def text(value: str | None) -> str: return "NULL" if value is None else "'" + value.replace("'", "''") + "'" -def checks() -> list[tuple[str, str]]: +def checks(engine: str) -> list[tuple[str, str]]: """A name and an expression per case, comparing with a NULL-safe test.""" spec = json.loads((ROOT / "spec" / "vectors.json").read_text(encoding="utf-8")) @@ -56,9 +57,16 @@ def same(expression: str, expected: str | None) -> str: for sneaky in ("ek01a03fk0ı", "EK01A03FK01", "EK01A03FK01", "EK01A03FK01\n"): found.append((f"reject {sneaky!r}", same(f"ng_postcode_parse({text(sneaky)})", None))) found.append(("unknown segment", same("ng_postcode_truncate(ng_postcode_parse('EK01A03FK01'), 'zone')", None))) + found.append(("version", same("ng_postcode_version()", version(engine)))) return found +def version(engine: str) -> str: + """The version a SQL file states in its header, which its version function must repeat.""" + header = (ROOT / "sql" / f"{engine}.sql").read_text(encoding="utf-8") + return re.search(r"^-- Version (\S+)$", header, re.MULTILINE)[1] + + def postgres(expressions: list[str]) -> list[bool]: script = (ROOT / "sql" / "postgres.sql").read_text(encoding="utf-8") # In a transaction that is rolled back, so the database is left as it was found. @@ -85,7 +93,7 @@ def duckdb(expressions: list[str]) -> list[bool]: def main() -> None: engine = {"postgres": postgres, "duckdb": duckdb}[sys.argv[1]] - cases = checks() + cases = checks(sys.argv[1]) answers = engine([expression for _, expression in cases]) if len(answers) != len(cases): sys.exit(f"{sys.argv[1]}: {len(answers)} answers for {len(cases)} cases") diff --git a/sql/README.md b/sql/README.md index 111eceb..10f81f1 100644 --- a/sql/README.md +++ b/sql/README.md @@ -50,5 +50,6 @@ SELECT * FROM customers WHERE postcode >= 'EK01A03' AND postcode < 'EK01A03' || | `ng_postcode_truncate(code, segment)` | The prefix through `state`, `lga`, `district`, `area`, or `unit` | | `ng_postcode_parent(prefix)` | The prefix one segment shorter, or NULL for a state | | `ng_postcode_within(code, prefix)` | Whether the code starts with the prefix | +| `ng_postcode_version()` | The version of the file that was loaded | A well-formed code is not necessarily assigned to a building. Only the NIPOST API can confirm that, through one of the [libraries](../README.md). diff --git a/sql/duckdb.sql b/sql/duckdb.sql index ae59722..e0c4bf6 100644 --- a/sql/duckdb.sql +++ b/sql/duckdb.sql @@ -1,5 +1,6 @@ -- Nigeria's NDAPS postcode for DuckDB: macros with the same names and answers as -- sql/postgres.sql. +-- Version 1.0.0 -- -- .read sql/duckdb.sql -- @@ -7,6 +8,9 @@ -- CHECK (ng_postcode_parse(code) IS NOT DISTINCT FROM code). scripts/sql_conformance.py -- runs the cases in spec/vectors.json against this file. +-- The version of this file, so that an installed copy can be told from a newer one. +CREATE OR REPLACE MACRO ng_postcode_version() AS '1.0.0'; + -- The letters and digits of a hyphenated, spaced or compact code, in upper case, or NULL -- if it holds anything else. CREATE OR REPLACE MACRO ng_postcode_compact(t) AS diff --git a/sql/postgres.sql b/sql/postgres.sql index 08d31e9..a1378b3 100644 --- a/sql/postgres.sql +++ b/sql/postgres.sql @@ -1,4 +1,5 @@ -- Nigeria's NDAPS postcode for PostgreSQL (tested on 14 and 17): two domains and a few functions. +-- Version 1.0.0 -- Plain SQL, so it loads on managed services that accept no extensions: -- -- psql -f sql/postgres.sql @@ -6,6 +7,10 @@ -- Store the compact form in an ng_postcode column. Behaviour follows spec/vectors.json, -- as the libraries do; scripts/sql_conformance.py runs those cases against this file. +-- The version of this file, so that an installed copy can be told from a newer one. +CREATE FUNCTION ng_postcode_version() RETURNS text + LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$ SELECT '1.0.0' $$; + -- A well-formed code in its compact form, EK01A03FK01. Well formed is not assigned: -- only the NIPOST API knows whether a code belongs to a building. CREATE DOMAIN ng_postcode AS text COLLATE "C" From 6f65d4df4c5fd7e10cfef3a416cf422ddbe73a69 Mon Sep 17 00:00:00 2001 From: mkbadeniyi Date: Sun, 11 Oct 2026 00:26:23 +0100 Subject: [PATCH 2/4] test(sql): run the README examples against PostgreSQL --- scripts/sql_conformance.py | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/scripts/sql_conformance.py b/scripts/sql_conformance.py index c598d1f..cecba4a 100644 --- a/scripts/sql_conformance.py +++ b/scripts/sql_conformance.py @@ -4,12 +4,14 @@ python3 scripts/sql_conformance.py duckdb # needs the duckdb package SQL has no error values, so a rejected input is NULL. Each case becomes one expression that -is true when the SQL agrees with the spec. +is true when the SQL agrees with the spec. For PostgreSQL, the examples in `sql/README.md` are +run as well. """ from __future__ import annotations import json +import os import re import subprocess import sys @@ -67,6 +69,12 @@ def version(engine: str) -> str: return re.search(r"^-- Version (\S+)$", header, re.MULTILINE)[1] +def readme() -> str: + """The SQL in `sql/README.md`, in order: its examples must run as written.""" + text = (ROOT / "sql" / "README.md").read_text(encoding="utf-8") + return "\n".join(re.findall(r"```sql\n(.*?)```", text, re.DOTALL)) + + def postgres(expressions: list[str]) -> list[bool]: script = (ROOT / "sql" / "postgres.sql").read_text(encoding="utf-8") # In a transaction that is rolled back, so the database is left as it was found. @@ -80,6 +88,15 @@ def postgres(expressions: list[str]) -> list[bool]: ) if run.returncode != 0: sys.exit(run.stderr) + examples = subprocess.run( + ["psql", "-X", "-q", "-At", "-v", "ON_ERROR_STOP=1", "-o", os.devnull], + input=f"BEGIN;\n{script}\n{readme()}\nROLLBACK;\n", + capture_output=True, + text=True, + check=False, + ) + if examples.returncode != 0: + sys.exit("sql/README.md does not run as written:\n" + examples.stderr) return [line == "t" for line in run.stdout.splitlines()] From 604972b1fb834f7258f1dc5eb227d407dc29b2cf Mon Sep 17 00:00:00 2001 From: mkbadeniyi Date: Sun, 11 Oct 2026 00:26:23 +0100 Subject: [PATCH 3/4] test(docs): run the grouping page's Python example --- python/tests/test_readme.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/python/tests/test_readme.py b/python/tests/test_readme.py index 65e0a5d..a11ef8a 100644 --- a/python/tests/test_readme.py +++ b/python/tests/test_readme.py @@ -28,3 +28,13 @@ def test_an_example_runs(example: str, monkeypatch: pytest.MonkeyPatch) -> None: stub = httpx.MockTransport(nipost) monkeypatch.setattr(httpx, "Client", lambda **options: real(transport=stub, **options)) exec(compile(example, str(README), "exec"), {}) + + +GROUPING = Path(__file__).resolve().parents[2] / "docs" / "group-by-place.md" + + +@pytest.mark.skipif(not GROUPING.exists(), reason="the page lives in the repository, not the sdist") +def test_the_grouping_page_example_runs(capsys: pytest.CaptureFixture[str]) -> None: + page = GROUPING.read_text(encoding="utf-8") + exec(compile(re.findall(r"```python\n(.*?)```", page, re.DOTALL)[0], str(GROUPING), "exec"), {}) + assert "'EK-01-A03': 2" in capsys.readouterr().out From b691e04ff8088cd0b0c642753caf030274852f6c Mon Sep 17 00:00:00 2001 From: mkbadeniyi Date: Sun, 11 Oct 2026 00:26:23 +0100 Subject: [PATCH 4/4] ci(sql): attach the SQL files to a release for each sql-v tag --- .github/workflows/release-sql.yml | 37 +++++++++++++++++++++++++++++++ docs/llms-full.txt | 2 ++ sql/README.md | 2 ++ 3 files changed, 41 insertions(+) create mode 100644 .github/workflows/release-sql.yml diff --git a/.github/workflows/release-sql.yml b/.github/workflows/release-sql.yml new file mode 100644 index 0000000..1e7a6c7 --- /dev/null +++ b/.github/workflows/release-sql.yml @@ -0,0 +1,37 @@ +name: Release SQL files + +# Push a tag such as sql-v1.0.0. Nothing is published to a registry: the two files are +# attached to a GitHub release, so that a database can be loaded from a pinned copy. +on: + push: + tags: ["sql-v*"] + +permissions: + contents: read + +jobs: + release: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + - name: Tag is on main + run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main + - name: Tag matches the version in both files + run: | + for file in sql/postgres.sql sql/duckdb.sql; do + test "sql-v$(sed -n 's/^-- Version //p' "$file")" = "$GITHUB_REF_NAME" + done + - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 + - name: Both files agree with spec/vectors.json + run: | + sudo systemctl start postgresql.service + sudo -u postgres createuser --superuser "$USER" + PGDATABASE=postgres python3 scripts/sql_conformance.py postgres + uv run --no-project --with duckdb==1.5.5 python scripts/sql_conformance.py duckdb + - run: gh release create "$GITHUB_REF_NAME" sql/postgres.sql sql/duckdb.sql --title "SQL files ${GITHUB_REF_NAME#sql-v}" --generate-notes + env: + GH_TOKEN: ${{ github.token }} diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 7a9fe4d..ee57919 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -923,6 +923,8 @@ psql -f sql/postgres.sql # PostgreSQL, tested on 14 and 17 duckdb my.db < sql/duckdb.sql # DuckDB, tested on 1.5 ``` +Each numbered version of the two files is attached to a [GitHub release](https://github.com/Adeniyikayodee/ng-postcode/releases) tagged `sql-v`, so you can pin the copy you load. + ## Store and check ```sql diff --git a/sql/README.md b/sql/README.md index 10f81f1..effa143 100644 --- a/sql/README.md +++ b/sql/README.md @@ -7,6 +7,8 @@ psql -f sql/postgres.sql # PostgreSQL, tested on 14 and 17 duckdb my.db < sql/duckdb.sql # DuckDB, tested on 1.5 ``` +Each numbered version of the two files is attached to a [GitHub release](https://github.com/Adeniyikayodee/ng-postcode/releases) tagged `sql-v`, so you can pin the copy you load. + ## Store and check ```sql