feat: CI workflows, Update fixture impl, runnable examples/

Jürgen Zornig · Jürgen Zornig · commit 4d8acd49d10f · 2026-05-29T22:18:05.000+02:00
- .github/workflows/ci.yml: pytest on Python 3.12 + 3.13 + uv build
- .github/workflows/publish.yml: PyPI Trusted Publishing on release
- Update fixture: full DBFit-compatible impl with '=' WHERE-column convention
  (SQLite-backed unit tests, 7 cases)
- examples/: three runnable .test.md suites
  - 01-hello: smallest possible Query test
  - 02-stored-procedure: Insert+capture, Execute Procedure, &lt;&lt;read, :bind
  - 03-schema-drift: Inspect Table as anti-flake schema lock
- README: link to examples/ from Quickstart
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs for the same ref when a new commit arrives.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Install project + dev dependencies
+        run: uv sync --python ${{ matrix.python }}
+
+      # Live database tests are gated behind `skipif` on the presence of
+      # local connection.properties files — on CI runners they will skip
+      # automatically, so unit-only execution is the default here.
+      - name: Run tests
+        run: uv run python -m pytest -q --tb=short
+
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+# Triggered when a GitHub Release is published. Tag the release with
+# the version (e.g. `v0.2.0`) — the workflow builds wheel + sdist and
+# publishes via PyPI Trusted Publishing (OIDC, no API token).
+#
+# One-time setup on PyPI: create a Trusted Publisher entry under
+#   https://pypi.org/manage/project/dbression/settings/publishing/
+# with:
+#   * Owner:           angrydat
+#   * Repository name: dbression
+#   * Workflow name:   publish.yml
+#   * Environment:     pypi
+on:
+  release:
+    types: [published]
+
+  # Allow manual runs for emergencies / re-publishes from a tag.
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dbression
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Optional belt-and-braces: verify package metadata before upload.
+          verify-metadata: true
diff --git a/README.md b/README.md
@@ -55,12 +55,16 @@ the model gets every detail it needs to suggest a fix, no screenshots, no contex
 
 ```bash
 # install (we use uv, but pip works too)
-uv tool install git+https://github.com/<your-org>/dbression.git
+uv tool install git+https://github.com/angrydat/dbression.git
 
 # run
 dbression run tests/
 ```
 
+There's also an [`examples/`](examples/) folder with three runnable demo suites
+(hello-SQL, stored-procedure-with-capture, schema-drift via `Inspect Table`) — each
+file is browsable Markdown *and* an executable test.
+
 ### Your first test
 
 Drop a `.wiki` file in a folder with a `_root.wiki` and a `connection.properties`:
diff --git a/examples/01-hello/HelloSql.test.md b/examples/01-hello/HelloSql.test.md
@@ -0,0 +1,13 @@
+# Hello SQL
+
+The smallest possible test: one Query, one expected row.
+
+### Query
+
+```sql
+select 'OK' as connection
+```
+
+| connection |
+|------------|
+| OK         |
diff --git a/examples/01-hello/_root.wiki b/examples/01-hello/_root.wiki
@@ -0,0 +1,2 @@
+!|DatabaseEnvironment|postgres|
+|ConnectUsingFile|connection.properties|
diff --git a/examples/01-hello/connection.properties b/examples/01-hello/connection.properties
@@ -0,0 +1,5 @@
+### Point this at any Postgres you have lying around.
+service=${PG_HOST:-localhost}
+username=${PG_USER:-postgres}
+password=${POSTGRES_PASSWORD}
+database=${PG_DB:-postgres}
diff --git a/examples/02-stored-procedure/BumpCounterTest.test.md b/examples/02-stored-procedure/BumpCounterTest.test.md
@@ -0,0 +1,34 @@
+# Bump counter
+
+Demonstrates four DBFit conventions back-to-back:
+
+1. **Insert** with a capture column (`>>row_id`) — Postgres `RETURNING` is generated automatically.
+2. **Set Parameter** stores a constant in the symbol table.
+3. **Execute Procedure** is dialect-aware: `SELECT name(args)` on Postgres, `EXEC name args` on SQL Server, `BEGIN name(args); END;` on Oracle.
+4. **Query** with `<<symbol_read` inside the expected cell, and `:bind` inside the SQL.
+
+### Insert counter
+
+| label   | >>row_id |
+|---------|----------|
+| widgets |          |
+
+### Set Parameter expected_hits 3
+
+### Execute Procedure bump_counter p_label
+
+| p_label |
+|---------|
+| widgets |
+| widgets |
+| widgets |
+
+### Query
+
+```sql
+select hits from counter where id = :row_id
+```
+
+| hits           |
+|----------------|
+| <<expected_hits|
diff --git a/examples/02-stored-procedure/SuiteSetUp.test.md b/examples/02-stored-procedure/SuiteSetUp.test.md
@@ -0,0 +1,23 @@
+# Setup — a temp table and a procedure to test
+
+Both DDL statements run inside the same suite transaction as the test, so they vanish
+when SuiteTearDown rolls back.
+
+### Execute
+
+```sql
+CREATE TEMP TABLE counter (id integer GENERATED ALWAYS AS IDENTITY, label text, hits integer NOT NULL DEFAULT 0)
+```
+
+### Execute
+
+```sql
+CREATE OR REPLACE FUNCTION bump_counter(p_label text)
+RETURNS void
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  UPDATE counter SET hits = hits + 1 WHERE label = p_label;
+END;
+$$
+```
diff --git a/examples/02-stored-procedure/SuiteTearDown.test.md b/examples/02-stored-procedure/SuiteTearDown.test.md
@@ -0,0 +1,9 @@
+# Teardown
+
+The whole suite ran inside a single transaction. Roll it back to leave the database
+untouched — even the temp table and function disappear.
+
+### DatabaseEnvironment
+
+| rollback |
+|----------|
diff --git a/examples/02-stored-procedure/_root.wiki b/examples/02-stored-procedure/_root.wiki
@@ -0,0 +1,2 @@
+!|DatabaseEnvironment|postgres|
+|ConnectUsingFile|connection.properties|
diff --git a/examples/02-stored-procedure/connection.properties b/examples/02-stored-procedure/connection.properties
@@ -0,0 +1,4 @@
+service=${PG_HOST:-localhost}
+username=${PG_USER:-postgres}
+password=${POSTGRES_PASSWORD}
+database=${PG_DB:-postgres}
diff --git a/examples/03-schema-drift/SchemaSnapshotTest.test.md b/examples/03-schema-drift/SchemaSnapshotTest.test.md
@@ -0,0 +1,17 @@
+# Lock the public shape of `customer`
+
+The `Inspect Table` fixture queries `information_schema.columns` (PG/MSSQL) or
+`all_tab_columns` (Oracle) and compares the result against the expected rows below.
+A new column, a renamed column, a different data type — anything that drifts will
+fail this test loudly.
+
+This is the *anti-flake* DBFit pattern: instead of writing a brittle `SELECT *` test
+that just checks values, you pin down the contract.
+
+### Inspect Table pg_temp.customer
+
+| column_name | data_type                |
+|-------------|--------------------------|
+| id          | integer                  |
+| email       | text                     |
+| created_at  | timestamp with time zone |
diff --git a/examples/03-schema-drift/SuiteSetUp.test.md b/examples/03-schema-drift/SuiteSetUp.test.md
@@ -0,0 +1,14 @@
+# Setup — a versioned table we want to lock down
+
+This temp table is the contract that the SchemaSnapshotTest will pin down. It exists
+only for the duration of the suite transaction.
+
+### Execute
+
+```sql
+CREATE TEMP TABLE customer (
+  id          serial PRIMARY KEY,
+  email       text NOT NULL,
+  created_at  timestamptz NOT NULL DEFAULT now()
+)
+```
diff --git a/examples/03-schema-drift/SuiteTearDown.test.md b/examples/03-schema-drift/SuiteTearDown.test.md
@@ -0,0 +1,6 @@
+# Teardown
+
+### DatabaseEnvironment
+
+| rollback |
+|----------|
diff --git a/examples/03-schema-drift/_root.wiki b/examples/03-schema-drift/_root.wiki
@@ -0,0 +1,2 @@
+!|DatabaseEnvironment|postgres|
+|ConnectUsingFile|connection.properties|
diff --git a/examples/03-schema-drift/connection.properties b/examples/03-schema-drift/connection.properties
@@ -0,0 +1,4 @@
+service=${PG_HOST:-localhost}
+username=${PG_USER:-postgres}
+password=${POSTGRES_PASSWORD}
+database=${PG_DB:-postgres}
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,23 @@
+# dbression examples
+
+Tiny, self-contained `.test.md` suites that double as living documentation for
+dbression's Markdown format. Each example renders nicely on GitHub — open any
+file and you can read it as prose, then run it as a test.
+
+| Example | What it shows |
+|---|---|
+| [`01-hello/`](01-hello/) | The smallest possible test: a single `Query` |
+| [`02-stored-procedure/`](02-stored-procedure/) | `Insert` → `Execute Procedure` → `Query`, with `>>capture` and `<<read` |
+| [`03-schema-drift/`](03-schema-drift/) | `Inspect Table` as a guard against unintended schema changes |
+
+## Running
+
+Every example needs a working `connection.properties` next to its `_root.wiki`
+(point it at any Postgres for the first two; the schema-drift demo expects a
+specific table — see that example's README).
+
+```bash
+# Quickstart against your own Postgres:
+export POSTGRES_PASSWORD=...
+dbression run examples/01-hello/
+```
diff --git a/src/dbression/fixtures/basic.py b/src/dbression/fixtures/basic.py
@@ -141,18 +141,84 @@ def run(self, table: Table, ctx: FixtureContext) -> FixtureResult:
 
 @register("Update")
 class Update(Fixture):
-    """Update fixture — Phase-1 stub.
+    """``!|Update|<schema.table>|`` with column headers and data rows.
 
-    DBFit's convention here is complex (WHERE columns appended at the end of the row,
-    marked via `=` column headers). WLK uses no Update fixtures and KBGSuite only once —
-    implementation deferred until a concrete example exists.
+    Convention (DBFit-compatible):
+
+    * Headers ending in ``=`` mark **WHERE columns** (the row's value is used in the WHERE clause).
+    * All other headers are **SET columns** (assigned to the new value).
+
+    Data-cell substitution: ``<<sym`` reads from the symbol table, empty / ``null`` becomes NULL.
+    Each data row issues one ``UPDATE`` statement. NULL on a WHERE column generates ``IS NULL``
+    (rather than ``= NULL`` which never matches).
+
+    Example::
+
+        !|Update|wlk.app_selectset|
+        |selected|oid=|table_name=|
+        |true    |42  |WB         |
+
+    runs ``UPDATE wlk.app_selectset SET selected = :v_0 WHERE oid = :v_1 AND table_name = :v_2``.
     """
 
     def run(self, table: Table, ctx: FixtureContext) -> FixtureResult:
-        return FixtureResult(
-            passed=False,
-            message="Update fixture not implemented yet (Phase 1 MVP)",
-        )
+        tablename = table.header_args[0] if table.header_args else ""
+        if not tablename:
+            return FixtureResult(passed=False, message="Update without table name")
+        if not table.headers:
+            return FixtureResult(passed=False, message="Update without column headers")
+
+        # Pre-classify headers; emit a clear error if the user gave SET-only or WHERE-only.
+        set_columns: list[tuple[int, str]] = []
+        where_columns: list[tuple[int, str]] = []
+        for c_i, raw in enumerate(table.headers):
+            h = raw.strip()
+            if h.endswith("="):
+                where_columns.append((c_i, h[:-1].strip()))
+            else:
+                set_columns.append((c_i, h))
+        if not set_columns:
+            return FixtureResult(
+                passed=False,
+                message="Update has no SET columns (every header ends with `=`)",
+            )
+
+        updated = 0
+        for r_i, row in enumerate(table.rows):
+            sets: list[str] = []
+            wheres: list[str] = []
+            binds: dict[str, Any] = {}
+            for c_i, col in set_columns:
+                cell = row[c_i] if c_i < len(row) else ""
+                key = f"s_{c_i}"
+                binds[key] = _cell_to_bind_value(cell, ctx)
+                sets.append(f"{col} = :{key}")
+            for c_i, col in where_columns:
+                cell = row[c_i] if c_i < len(row) else ""
+                val = _cell_to_bind_value(cell, ctx)
+                if val is None:
+                    wheres.append(f"{col} IS NULL")
+                else:
+                    key = f"w_{c_i}"
+                    binds[key] = val
+                    wheres.append(f"{col} = :{key}")
+
+            sql = f"UPDATE {tablename} SET {', '.join(sets)}"
+            if wheres:
+                sql += f" WHERE {' AND '.join(wheres)}"
+
+            try:
+                result = ctx.conn.execute(text(sql), binds)
+                updated += result.rowcount or 0
+            except DBAPIError as e:
+                err = wrap_dbapi_error(e, sql=sql, binds=binds)
+                return FixtureResult(
+                    passed=False,
+                    message=f"Update fail at row {r_i + 1}: {err}",
+                    details=_format_sql_block(sql, err),
+                )
+
+        return FixtureResult(passed=True, message=f"Update {updated} rows in {tablename}")
 
 
 @register("Insert")
diff --git a/tests/test_update_fixture.py b/tests/test_update_fixture.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+!\|DatabaseEnvironment\|postgres\|`
	`2`	`+\|ConnectUsingFile\|connection.properties\|`