Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions .github/workflows/release-sql.yml
Original file line number Diff line number Diff line change
@@ -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 }}
3 changes: 3 additions & 0 deletions docs/llms-full.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -966,5 +968,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).
10 changes: 10 additions & 0 deletions python/tests/test_readme.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
31 changes: 28 additions & 3 deletions scripts/sql_conformance.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,15 @@
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
from pathlib import Path
Expand All @@ -21,7 +24,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"))

Expand Down Expand Up @@ -56,9 +59,22 @@ 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 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.
Expand All @@ -72,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()]


Expand All @@ -85,7 +110,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")
Expand Down
3 changes: 3 additions & 0 deletions sql/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -50,5 +52,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).
4 changes: 4 additions & 0 deletions sql/duckdb.sql
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
-- 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
--
-- DuckDB has no domains, so keep a column to the compact form with a constraint:
-- 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
Expand Down
5 changes: 5 additions & 0 deletions sql/postgres.sql
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
-- 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
--
-- 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"
Expand Down
Loading