specrig 0.3.0__tar.gz → 0.3.2__tar.gz

{specrig-0.3.0 → specrig-0.3.2}/Makefile

@@ -7,7 +7,7 @@ $(VENV):
 	$(VENV)/bin/pip install -q --upgrade pip
 
 install: $(VENV)
-	$(VENV)/bin/pip install -q -e ".[fastapi,django,postgres]" --group dev
+	$(VENV)/bin/pip install -q -e ".[fastapi,django,postgres,mysql,sqlite]" --group dev
 
 generate: install
 	cd samples/shop && $(VENV)/bin/specrig surface && $(VENV)/bin/specrig agents

specrig-0.3.0/README.md → specrig-0.3.2/PKG-INFO

@@ -1,3 +1,34 @@
+Metadata-Version: 2.5
+Name: specrig
+Version: 0.3.2
+Summary: A harness for a FastAPI or Django service developed specification first
+Project-URL: Homepage, https://github.com/specrig/specrig-python
+Project-URL: Protocol, https://github.com/specrig/protocol
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: pytest-bdd>=8.1
+Requires-Dist: pytest>=7.4
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: time-machine>=2.10
+Requires-Dist: tomlkit>=0.11
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: anyio>=4; extra == 'fastapi'
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: mysql
+Requires-Dist: pymysql[rsa]>=1.1; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1.8; extra == 'postgres'
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
 # specrig for Python
 
 A harness for a FastAPI or Django service developed specification first: the
@@ -9,7 +40,7 @@ application.
 **Status: built.** Everything below runs green on two samples — `shop`, a FastAPI
 API over Postgres through SQLAlchemy and Alembic, with a job and a command, and
 `reminders`, a Django service over Postgres and Redis with a job and a management
-command. [docs/design.md](docs/design.md) has what each part is built from and
+command; the tests run both again on MySQL and on SQLite. [docs/design.md](docs/design.md) has what each part is built from and
 why; what every specrig stack agrees on — the records, the modes, the text of
 `specrig.md` — is the [specrig protocol](https://github.com/specrig/protocol),
 whose modes and `specrig.md` parts are copied into
@@ -67,7 +98,8 @@ In the service's directory, with its virtual environment in `.venv`:
 .venv/bin/pip install "specrig[fastapi,postgres]"
 ```
 
-or `specrig[django,postgres]`, then:
+or `specrig[django,postgres]` — `mysql` or `sqlite` in place of `postgres` for a
+service on those —, then:
 
 ```bash
 .venv/bin/specrig init --backend billing=BILLING_URL --contract billing=../docs/billing.yaml
@@ -78,12 +110,19 @@ or `specrig[django,postgres]`, then:
 dependencies. `--backend` names a neighbour the service calls over HTTP and the
 variable that holds its address; a variable the code does not read is refused,
 with the list of those it does, and a service that calls out with no `--backend`
-is refused, naming the calls. Postgres becomes a `Postgres` resource where the
-service depends on a Postgres driver and reads `DATABASE_URL`, with the URL's
-scheme from `.env.example` or the drivers — `postgresql+psycopg`,
-`postgresql+asyncpg`; Redis a `Redis` where it depends on `redis` and reads a
-variable that names it. Every other variable the code needs is a constant the
-harness answers empty, and a Django service gets a `SECRET_KEY` of its own.
+is refused, naming the calls. The database the service reads from `DATABASE_URL`
+becomes a resource by what says which it is: a Django settings module's `ENGINE`
+first, then the server's driver the service depends on — a `Postgres` for psycopg
+or asyncpg, a `MySQL` for mysqlclient, PyMySQL, asyncmy or aiomysql —, and a
+`SQLite` only where nothing names a server and `.env.example` gives a `sqlite:`
+address or the service depends on aiosqlite; with none of these there is no
+database resource, and the variable is a constant like any other. The URL's scheme
+comes from `.env.example` where it names the dialect chosen, else from the drivers,
+an async one first — `postgresql+asyncpg`, `mysql+asyncmy` before `mysql+aiomysql`,
+`mysql+pymysql`, `sqlite+aiosqlite`. Redis becomes a `Redis` where it depends on
+`redis` and reads a variable that names it. Every other variable the code needs is
+a constant the harness answers empty, and a Django service gets a `SECRET_KEY` of
+its own.
 
 | option | |
 |---|---|
@@ -215,7 +254,9 @@ fixtures, autouse ones included, would change the service the cases see.
 |---|---|
 | `harness.<backend>.reply(method, path, status, body, headers)` | what the neighbour answers; `headers`, strings to strings, are added to the response the client sees. A segment in braces, `/orders/{id}`, takes any one segment, the exact path wins over a template and the first declared of two templates over the second — in every call here that names a path |
 | `harness.<backend>.reply_to(method, path, query, status, body, headers)` | the same, for a request whose query has these values; the reply naming the most of them wins |
-| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once |
+| `harness.<backend>.reply_with(method, path, answer, headers)` | the answer worked out from each request: `answer` takes what `requests` returns one of and gives `(status, body)`; a reply naming no query, checked as the others |
+| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once; no reply lifts it |
+| `harness.<backend>.heal()` | the neighbour answers again: every `time_out` is lifted, the replies stay |
 | `harness.<backend>.requests(method, path)` | what reached the neighbour: `method`, `path`, `query` and `json`, its decoded body; a template returns the requests it takes |
 | `harness.http()` | a client of the service's own stack: `get`, `post`, `put`, `patch`, `delete`, `send`; a response with `status`, `headers`, `text`, `json()` |
 | `harness.run(job, *args, **kwargs)` | a job — see below |
@@ -224,11 +265,11 @@ fixtures, autouse ones included, would change the service the cases see.
 | `harness.replace(target, instance)` | a granted class or function of the service, replaced before the service boots |
 | `harness.logs` | what the service logged, under its real logging configuration |
 | `harness.clock` | the service's clock: the wall clock until a step calls `set()`, then `advance()` |
-| `harness.<resource>.fail_with(error=None)` | the resource goes down for the service — see Postgres and Redis |
-| `harness.<postgres>.refuse(table, *writes)` | every insert, update and delete on the table, or those given, fails in Postgres itself, whoever sends it; reads go on working — see Postgres |
-| `harness.<postgres>.refuse_after(table, rows, *writes)` | the same after the first `rows` rows |
-| `harness.<postgres>.refuse_commit(table, *writes)` | the statements go through, and the commit of a transaction that wrote the table fails |
-| `harness.<postgres>.heal()` | the database comes back: `fail_with` and every refusal end, and the rows stay |
+| `harness.<resource>.fail_with(error=None)` | the resource goes down for the service — see Postgres, MySQL and SQLite, and Redis |
+| `harness.<database>.refuse(table, *writes)` | every insert, update and delete on the table, or those given, fails in the database itself, whoever sends it; reads go on working — see Postgres |
+| `harness.<database>.refuse_after(table, rows, *writes)` | the same after the first `rows` rows |
+| `harness.<postgres>.refuse_commit(table, *writes)` | Postgres only: the statements go through, and the commit of a transaction that wrote the table fails |
+| `harness.<database>.heal()` | the database comes back: `fail_with` and every refusal end, and the rows stay |
 | `harness.application` | FastAPI: the app the case runs |
 
 The service boots at the first step that reaches it, so a `Given` declares and
@@ -281,7 +322,7 @@ in `settings = "config.settings"` where FastAPI's names `app`; the rest is the s
 | member | |
 |---|---|
 | a `Backend` | an HTTP neighbour: its origin, the variable that points the service at it, its OpenAPI document, the schema of its 5xx |
-| a `Postgres` or `Redis` | a real system, and the variable that receives its address |
+| a `Postgres`, `MySQL`, `SQLite` or `Redis` | a real system, and the variable that receives its address |
 | `app` | FastAPI: the application, `module:attribute`; a function there builds a new one for every case |
 | `settings` | Django: the settings module |
 | `console` | FastAPI: the service's console, `module:callable`, where `pyproject.toml` has more than one script |
@@ -343,7 +384,11 @@ database = Postgres("DATABASE_URL", scheme="postgresql+psycopg")
 The variable receives one URL with the scheme given, `postgresql` by default. The
 server is `address=` if given, else `<SERVICE>_TEST_POSTGRES`, else a container
 started through the Docker socket and kept between runs — starting postgres costs
-seconds, a database a fraction of one. The database is the run's own:
+seconds, a database a fraction of one. Its role has no password, so the container
+is published on loopback only — on every interface where
+`TESTCONTAINERS_HOST_OVERRIDE` says the suite runs in a container of its own; a
+container an older specrig started is reused as it was published. The database is
+the run's own:
 `shop_test_<pid>`, created at the first boot and dropped when the run ends. A run
 killed before its end leaves its database behind, and the next run drops it: a
 name of that shape, marked by specrig over an hour ago, with nobody connected.
@@ -369,7 +414,11 @@ resets.
 `harness.database.fail_with()` closes the gate: every connection the service holds
 is cut and every new one refused, as by a database that is down, and the service
 meets its driver's own exception. An error given instead fails every statement
-with it — through SQLAlchemy's events, or Django's execute wrappers. A fault a
+with it — through SQLAlchemy's events, or Django's execute wrappers. An error of
+the driver's DB-API reaches the service as the framework raises one the driver
+raised: Django's `OperationalError` for psycopg's, SQLAlchemy's for SQLAlchemy —
+which wraps it itself from 2.1, and the harness before. With asyncpg the DB-API is
+SQLAlchemy's adapter, so asyncpg's own exceptions pass as given. A fault a
 step sets before the boot waits for the service to start, so the migration and
 the start go through; the next case starts whole.
 
@@ -390,6 +439,84 @@ refusals, before it writes the rows back. They live in a schema of their own,
 `specrig_refusal`, which the reset's discovery and the `specrig_baseline` copy never
 see.
 
+## MySQL and SQLite
+
+```python
+database = MySQL("DATABASE_URL", scheme="mysql+pymysql")
+```
+
+```python
+database = SQLite("DATABASE_URL", scheme="sqlite+aiosqlite")
+```
+
+The scheme is `mysql` and `sqlite` by default. Both are Postgres's resource with
+what the dialect lacks worked around: the migrations once per run, the rows they
+wrote put back before every case, `keep=`, `fail_with`, `refuse`, `refuse_after` and
+`heal`. **There is no `refuse_commit`**: MySQL has no deferred constraint at all,
+and the only thing that fails an SQLite commit on demand is a deferred foreign
+key, which every driver raises as an `IntegrityError` — a case would test the
+conflict branch instead of a failed commit.
+
+**What a refusal raises is the dialect's.** A MySQL trigger refuses with
+`SIGNAL SQLSTATE '45000'`, which every MySQL driver raises as an
+`OperationalError`, the class of a lost connection: a service that answers an
+`OperationalError` as a database down answers a refused write the same way, as
+`shop` does with a 503. SQLite's `RAISE(ABORT)` is a failed constraint, so the
+service meets an `IntegrityError`. Postgres's refusal is an `InternalError`.
+
+### MySQL
+
+The server is `address=`, else `<SERVICE>_TEST_MYSQL`, else a `mysql:8.4` container
+started as root with no password and kept between runs, published as Postgres's
+is. MySQL 8.0.19 and up: the tests run on 8.4, and the MySQL ones passed once
+against 8.0.46. The database is the run's own, behind a gate, and a killed run's
+is dropped by the next, as Postgres's. MySQL keeps no comment on a database, so the
+mark is the comment of a `specrig_mark` table inside it; the copied rows sit in
+`specrig_kept_<n>` tables beside the service's, which the reset never sees; and the
+drop kills the connections left on the database first, since there is no
+`WITH (FORCE)`. The harness talks to MySQL through PyMySQL, which the `mysql` extra
+brings with `cryptography`: a user with a password over a connection without TLS
+signs in with an RSA key. The service talks through the driver its URL names.
+
+**A reset touches only what a case changed.** Truncating a table, creating a
+trigger and setting a counter are DDL in MySQL. `CHECKSUM TABLE` over every table
+in one statement finds the tables a case changed, and only those are emptied by
+`DELETE` and written back, in one transaction, on the harness's own connection,
+which checks no foreign keys and keeps an id 0 a migration wrote
+(`NO_AUTO_VALUE_ON_ZERO`). An insert trigger of a table with rows to write back and
+a delete trigger of a table with rows to delete are dropped first and created
+again after, in their order and the `sql_mode` they were made in, and a trigger the
+migrations made that a case dropped is made again; a counter is set back only where
+it moved. Measured on a laptop, six tables:
+
+| per reset | |
+|---|---|
+| nothing changed | ~3 ms |
+| two rows inserted | 21–24 ms, most of them setting the two counters back |
+| a row updated in a table with two triggers | 34–39 ms |
+| every table truncated and the rows written back | 118–158 ms |
+| Postgres, two rows inserted | ~7 ms |
+
+### SQLite
+
+**There is no address and no container.** The service is answered with a file of
+the run's own, `sqlite:////…/specrig-…/shop.db` with the scheme given, in a
+temporary directory the run removes at its end: nothing is shared between runs or
+processes, and nothing is left to sweep. The copied rows are kept in a second file
+that only the resetting connection attaches. SQLite cannot switch a trigger off, so
+the reset drops every trigger and creates it again inside its transaction, with
+foreign keys off on that connection, and puts `sqlite_sequence` back; it takes
+under a millisecond. A virtual table — FTS5, R*Tree — and the tables it keeps
+behind it are left as they are: their rows are not reset.
+
+Whether the service's own connections check foreign keys is the framework's, as in
+production: Django turns them on, SQLAlchemy leaves them off unless the service
+turns them on.
+
+`fail_with()` has no gate to close: every statement through SQLAlchemy or Django
+fails with `sqlite3.OperationalError("unable to open database file")`, as from a
+file that does not open, raised as the framework raises the driver's own.
+
 ## Redis
 
 ```python
@@ -523,7 +650,7 @@ the edits are let through, and the plugin says so once.
 
 ## Limits
 
-- FastAPI 0.90 and up, and any ASGI application a module builds, through the
+- FastAPI 0.100 and up, and any ASGI application a module builds, through the
   `fastapi` harness; Django 4.2 and up through its WSGI handler. Flask has no
   harness.
 - The service is imported once per run: what a module builds as it loads — a
@@ -545,7 +672,7 @@ the edits are let through, and the plugin says so once.
 - The database is one URL in one variable. A Django service that sets its
   `DATABASES` host by host from several variables is answered on the one the
   harness names only.
-- `Postgres` and `Redis` are the resources there are.
+- `Postgres`, `MySQL`, `SQLite` and `Redis` are the resources there are.
 - One service per run: two suites in one `pytest` process are refused, and a run
   split by `pytest-xdist` writes no `tests/flows.yaml`, since no worker sees the
   whole.
@@ -576,7 +703,7 @@ run against copies of the samples, then the suites of the two samples in
 docker rm -f $(docker ps -aq --filter label=specrig=postgres)
 ```
 
-removes the kept Postgres container.
+removes the kept Postgres container, and `label=specrig=mysql` the MySQL one.
 
 ```bash
 make protocol

specrig-0.3.0/PKG-INFO → specrig-0.3.2/README.md

@@ -1,31 +1,3 @@
-Metadata-Version: 2.5
-Name: specrig
-Version: 0.3.0
-Summary: A harness for a FastAPI or Django service developed specification first
-Project-URL: Homepage, https://github.com/specrig/specrig-python
-Project-URL: Protocol, https://github.com/specrig/protocol
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Framework :: Django
-Classifier: Framework :: FastAPI
-Classifier: Framework :: Pytest
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.11
-Requires-Dist: jsonschema>=4.0
-Requires-Dist: pytest-bdd>=8.1
-Requires-Dist: pytest>=7.4
-Requires-Dist: pyyaml>=6.0.1
-Requires-Dist: time-machine>=2.10
-Requires-Dist: tomlkit>=0.11
-Provides-Extra: django
-Requires-Dist: django>=4.2; extra == 'django'
-Provides-Extra: fastapi
-Requires-Dist: anyio>=4; extra == 'fastapi'
-Requires-Dist: fastapi>=0.90; extra == 'fastapi'
-Provides-Extra: postgres
-Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
-Description-Content-Type: text/markdown
-
 # specrig for Python
 
 A harness for a FastAPI or Django service developed specification first: the
@@ -37,7 +9,7 @@ application.
 **Status: built.** Everything below runs green on two samples — `shop`, a FastAPI
 API over Postgres through SQLAlchemy and Alembic, with a job and a command, and
 `reminders`, a Django service over Postgres and Redis with a job and a management
-command. [docs/design.md](docs/design.md) has what each part is built from and
+command; the tests run both again on MySQL and on SQLite. [docs/design.md](docs/design.md) has what each part is built from and
 why; what every specrig stack agrees on — the records, the modes, the text of
 `specrig.md` — is the [specrig protocol](https://github.com/specrig/protocol),
 whose modes and `specrig.md` parts are copied into
@@ -95,7 +67,8 @@ In the service's directory, with its virtual environment in `.venv`:
 .venv/bin/pip install "specrig[fastapi,postgres]"
 ```
 
-or `specrig[django,postgres]`, then:
+or `specrig[django,postgres]` — `mysql` or `sqlite` in place of `postgres` for a
+service on those —, then:
 
 ```bash
 .venv/bin/specrig init --backend billing=BILLING_URL --contract billing=../docs/billing.yaml
@@ -106,12 +79,19 @@ or `specrig[django,postgres]`, then:
 dependencies. `--backend` names a neighbour the service calls over HTTP and the
 variable that holds its address; a variable the code does not read is refused,
 with the list of those it does, and a service that calls out with no `--backend`
-is refused, naming the calls. Postgres becomes a `Postgres` resource where the
-service depends on a Postgres driver and reads `DATABASE_URL`, with the URL's
-scheme from `.env.example` or the drivers — `postgresql+psycopg`,
-`postgresql+asyncpg`; Redis a `Redis` where it depends on `redis` and reads a
-variable that names it. Every other variable the code needs is a constant the
-harness answers empty, and a Django service gets a `SECRET_KEY` of its own.
+is refused, naming the calls. The database the service reads from `DATABASE_URL`
+becomes a resource by what says which it is: a Django settings module's `ENGINE`
+first, then the server's driver the service depends on — a `Postgres` for psycopg
+or asyncpg, a `MySQL` for mysqlclient, PyMySQL, asyncmy or aiomysql —, and a
+`SQLite` only where nothing names a server and `.env.example` gives a `sqlite:`
+address or the service depends on aiosqlite; with none of these there is no
+database resource, and the variable is a constant like any other. The URL's scheme
+comes from `.env.example` where it names the dialect chosen, else from the drivers,
+an async one first — `postgresql+asyncpg`, `mysql+asyncmy` before `mysql+aiomysql`,
+`mysql+pymysql`, `sqlite+aiosqlite`. Redis becomes a `Redis` where it depends on
+`redis` and reads a variable that names it. Every other variable the code needs is
+a constant the harness answers empty, and a Django service gets a `SECRET_KEY` of
+its own.
 
 | option | |
 |---|---|
@@ -243,7 +223,9 @@ fixtures, autouse ones included, would change the service the cases see.
 |---|---|
 | `harness.<backend>.reply(method, path, status, body, headers)` | what the neighbour answers; `headers`, strings to strings, are added to the response the client sees. A segment in braces, `/orders/{id}`, takes any one segment, the exact path wins over a template and the first declared of two templates over the second — in every call here that names a path |
 | `harness.<backend>.reply_to(method, path, query, status, body, headers)` | the same, for a request whose query has these values; the reply naming the most of them wins |
-| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once |
+| `harness.<backend>.reply_with(method, path, answer, headers)` | the answer worked out from each request: `answer` takes what `requests` returns one of and gives `(status, body)`; a reply naming no query, checked as the others |
+| `harness.<backend>.time_out(method, path, query=None)` | the neighbour does not answer in time: the client meets the timeout it would meet, at once; no reply lifts it |
+| `harness.<backend>.heal()` | the neighbour answers again: every `time_out` is lifted, the replies stay |
 | `harness.<backend>.requests(method, path)` | what reached the neighbour: `method`, `path`, `query` and `json`, its decoded body; a template returns the requests it takes |
 | `harness.http()` | a client of the service's own stack: `get`, `post`, `put`, `patch`, `delete`, `send`; a response with `status`, `headers`, `text`, `json()` |
 | `harness.run(job, *args, **kwargs)` | a job — see below |
@@ -252,11 +234,11 @@ fixtures, autouse ones included, would change the service the cases see.
 | `harness.replace(target, instance)` | a granted class or function of the service, replaced before the service boots |
 | `harness.logs` | what the service logged, under its real logging configuration |
 | `harness.clock` | the service's clock: the wall clock until a step calls `set()`, then `advance()` |
-| `harness.<resource>.fail_with(error=None)` | the resource goes down for the service — see Postgres and Redis |
-| `harness.<postgres>.refuse(table, *writes)` | every insert, update and delete on the table, or those given, fails in Postgres itself, whoever sends it; reads go on working — see Postgres |
-| `harness.<postgres>.refuse_after(table, rows, *writes)` | the same after the first `rows` rows |
-| `harness.<postgres>.refuse_commit(table, *writes)` | the statements go through, and the commit of a transaction that wrote the table fails |
-| `harness.<postgres>.heal()` | the database comes back: `fail_with` and every refusal end, and the rows stay |
+| `harness.<resource>.fail_with(error=None)` | the resource goes down for the service — see Postgres, MySQL and SQLite, and Redis |
+| `harness.<database>.refuse(table, *writes)` | every insert, update and delete on the table, or those given, fails in the database itself, whoever sends it; reads go on working — see Postgres |
+| `harness.<database>.refuse_after(table, rows, *writes)` | the same after the first `rows` rows |
+| `harness.<postgres>.refuse_commit(table, *writes)` | Postgres only: the statements go through, and the commit of a transaction that wrote the table fails |
+| `harness.<database>.heal()` | the database comes back: `fail_with` and every refusal end, and the rows stay |
 | `harness.application` | FastAPI: the app the case runs |
 
 The service boots at the first step that reaches it, so a `Given` declares and
@@ -309,7 +291,7 @@ in `settings = "config.settings"` where FastAPI's names `app`; the rest is the s
 | member | |
 |---|---|
 | a `Backend` | an HTTP neighbour: its origin, the variable that points the service at it, its OpenAPI document, the schema of its 5xx |
-| a `Postgres` or `Redis` | a real system, and the variable that receives its address |
+| a `Postgres`, `MySQL`, `SQLite` or `Redis` | a real system, and the variable that receives its address |
 | `app` | FastAPI: the application, `module:attribute`; a function there builds a new one for every case |
 | `settings` | Django: the settings module |
 | `console` | FastAPI: the service's console, `module:callable`, where `pyproject.toml` has more than one script |
@@ -371,7 +353,11 @@ database = Postgres("DATABASE_URL", scheme="postgresql+psycopg")
 The variable receives one URL with the scheme given, `postgresql` by default. The
 server is `address=` if given, else `<SERVICE>_TEST_POSTGRES`, else a container
 started through the Docker socket and kept between runs — starting postgres costs
-seconds, a database a fraction of one. The database is the run's own:
+seconds, a database a fraction of one. Its role has no password, so the container
+is published on loopback only — on every interface where
+`TESTCONTAINERS_HOST_OVERRIDE` says the suite runs in a container of its own; a
+container an older specrig started is reused as it was published. The database is
+the run's own:
 `shop_test_<pid>`, created at the first boot and dropped when the run ends. A run
 killed before its end leaves its database behind, and the next run drops it: a
 name of that shape, marked by specrig over an hour ago, with nobody connected.
@@ -397,7 +383,11 @@ resets.
 `harness.database.fail_with()` closes the gate: every connection the service holds
 is cut and every new one refused, as by a database that is down, and the service
 meets its driver's own exception. An error given instead fails every statement
-with it — through SQLAlchemy's events, or Django's execute wrappers. A fault a
+with it — through SQLAlchemy's events, or Django's execute wrappers. An error of
+the driver's DB-API reaches the service as the framework raises one the driver
+raised: Django's `OperationalError` for psycopg's, SQLAlchemy's for SQLAlchemy —
+which wraps it itself from 2.1, and the harness before. With asyncpg the DB-API is
+SQLAlchemy's adapter, so asyncpg's own exceptions pass as given. A fault a
 step sets before the boot waits for the service to start, so the migration and
 the start go through; the next case starts whole.
 
@@ -418,6 +408,84 @@ refusals, before it writes the rows back. They live in a schema of their own,
 `specrig_refusal`, which the reset's discovery and the `specrig_baseline` copy never
 see.
 
+## MySQL and SQLite
+
+```python
+database = MySQL("DATABASE_URL", scheme="mysql+pymysql")
+```
+
+```python
+database = SQLite("DATABASE_URL", scheme="sqlite+aiosqlite")
+```
+
+The scheme is `mysql` and `sqlite` by default. Both are Postgres's resource with
+what the dialect lacks worked around: the migrations once per run, the rows they
+wrote put back before every case, `keep=`, `fail_with`, `refuse`, `refuse_after` and
+`heal`. **There is no `refuse_commit`**: MySQL has no deferred constraint at all,
+and the only thing that fails an SQLite commit on demand is a deferred foreign
+key, which every driver raises as an `IntegrityError` — a case would test the
+conflict branch instead of a failed commit.
+
+**What a refusal raises is the dialect's.** A MySQL trigger refuses with
+`SIGNAL SQLSTATE '45000'`, which every MySQL driver raises as an
+`OperationalError`, the class of a lost connection: a service that answers an
+`OperationalError` as a database down answers a refused write the same way, as
+`shop` does with a 503. SQLite's `RAISE(ABORT)` is a failed constraint, so the
+service meets an `IntegrityError`. Postgres's refusal is an `InternalError`.
+
+### MySQL
+
+The server is `address=`, else `<SERVICE>_TEST_MYSQL`, else a `mysql:8.4` container
+started as root with no password and kept between runs, published as Postgres's
+is. MySQL 8.0.19 and up: the tests run on 8.4, and the MySQL ones passed once
+against 8.0.46. The database is the run's own, behind a gate, and a killed run's
+is dropped by the next, as Postgres's. MySQL keeps no comment on a database, so the
+mark is the comment of a `specrig_mark` table inside it; the copied rows sit in
+`specrig_kept_<n>` tables beside the service's, which the reset never sees; and the
+drop kills the connections left on the database first, since there is no
+`WITH (FORCE)`. The harness talks to MySQL through PyMySQL, which the `mysql` extra
+brings with `cryptography`: a user with a password over a connection without TLS
+signs in with an RSA key. The service talks through the driver its URL names.
+
+**A reset touches only what a case changed.** Truncating a table, creating a
+trigger and setting a counter are DDL in MySQL. `CHECKSUM TABLE` over every table
+in one statement finds the tables a case changed, and only those are emptied by
+`DELETE` and written back, in one transaction, on the harness's own connection,
+which checks no foreign keys and keeps an id 0 a migration wrote
+(`NO_AUTO_VALUE_ON_ZERO`). An insert trigger of a table with rows to write back and
+a delete trigger of a table with rows to delete are dropped first and created
+again after, in their order and the `sql_mode` they were made in, and a trigger the
+migrations made that a case dropped is made again; a counter is set back only where
+it moved. Measured on a laptop, six tables:
+
+| per reset | |
+|---|---|
+| nothing changed | ~3 ms |
+| two rows inserted | 21–24 ms, most of them setting the two counters back |
+| a row updated in a table with two triggers | 34–39 ms |
+| every table truncated and the rows written back | 118–158 ms |
+| Postgres, two rows inserted | ~7 ms |
+
+### SQLite
+
+**There is no address and no container.** The service is answered with a file of
+the run's own, `sqlite:////…/specrig-…/shop.db` with the scheme given, in a
+temporary directory the run removes at its end: nothing is shared between runs or
+processes, and nothing is left to sweep. The copied rows are kept in a second file
+that only the resetting connection attaches. SQLite cannot switch a trigger off, so
+the reset drops every trigger and creates it again inside its transaction, with
+foreign keys off on that connection, and puts `sqlite_sequence` back; it takes
+under a millisecond. A virtual table — FTS5, R*Tree — and the tables it keeps
+behind it are left as they are: their rows are not reset.
+
+Whether the service's own connections check foreign keys is the framework's, as in
+production: Django turns them on, SQLAlchemy leaves them off unless the service
+turns them on.
+
+`fail_with()` has no gate to close: every statement through SQLAlchemy or Django
+fails with `sqlite3.OperationalError("unable to open database file")`, as from a
+file that does not open, raised as the framework raises the driver's own.
+
 ## Redis
 
 ```python
@@ -551,7 +619,7 @@ the edits are let through, and the plugin says so once.
 
 ## Limits
 
-- FastAPI 0.90 and up, and any ASGI application a module builds, through the
+- FastAPI 0.100 and up, and any ASGI application a module builds, through the
   `fastapi` harness; Django 4.2 and up through its WSGI handler. Flask has no
   harness.
 - The service is imported once per run: what a module builds as it loads — a
@@ -573,7 +641,7 @@ the edits are let through, and the plugin says so once.
 - The database is one URL in one variable. A Django service that sets its
   `DATABASES` host by host from several variables is answered on the one the
   harness names only.
-- `Postgres` and `Redis` are the resources there are.
+- `Postgres`, `MySQL`, `SQLite` and `Redis` are the resources there are.
 - One service per run: two suites in one `pytest` process are refused, and a run
   split by `pytest-xdist` writes no `tests/flows.yaml`, since no worker sees the
   whole.
@@ -604,7 +672,7 @@ run against copies of the samples, then the suites of the two samples in
 docker rm -f $(docker ps -aq --filter label=specrig=postgres)
 ```
 
-removes the kept Postgres container.
+removes the kept Postgres container, and `label=specrig=mysql` the MySQL one.
 
 ```bash
 make protocol

{specrig-0.3.0 → specrig-0.3.2}/docs/design.md

@@ -57,7 +57,9 @@ migrations write — the states an order moves through, the root of a tree — e
 in no environment, a step that writes them again is a second copy of the
 migration that drifts from the first, and a `keep` for them carries one case's
 changes into the next. Writing them back turns foreign keys and triggers off for
-one transaction, which takes a superuser; migrations that write no rows need none.
+one transaction, which takes a superuser on Postgres; migrations that write no rows
+need none. MySQL's foreign key checks are a session's and SQLite's a connection's,
+and the triggers on both are dropped and created again instead.
 
 ## One request at a time
 
@@ -83,6 +85,8 @@ flight between steps, and `time_out` stands in for a slow neighbour, as in PHP.
 | logs | a handler on the root logger, beside the service's | the same |
 | grants | `replace(name, instance)`: the name replaced in every module of the service that holds it, and in FastAPI's `dependency_overrides` | the name replaced in every module that holds it |
 | Postgres | `alembic upgrade head` once per run, in a process of its own, and the rows it wrote kept aside; before every case every table but `alembic_version` and `keep` truncated and those rows written back, with the sequences where they stood; a refusal by the gate, an error by SQLAlchemy's `before_cursor_execute`, a table's writes by triggers in a schema of their own | `migrate` once per run, and the rows it wrote kept aside; every table but Django's bookkeeping and `keep` truncated and those rows written back; an error by the connections' execute wrappers; a table's writes by the same triggers |
+| MySQL | as Postgres, but only the tables whose `CHECKSUM TABLE` moved are emptied by `DELETE` and written back, with the triggers those writes would fire dropped and created again in their order, a trigger a case dropped made again, and a counter set back only where it moved; a refusal by the gate, a table's writes by triggers that `SIGNAL` | as Postgres, with the same reset |
+| SQLite | a file of the run's own in a temporary directory; before every case every table but the virtual ones emptied and written back from a second file the resetting connection attaches, every trigger dropped and created again, `sqlite_sequence` put back; a refusal and an error alike by SQLAlchemy's `before_cursor_execute`; a table's writes by triggers that `RAISE(ABORT)` | the same, through the connections' execute wrappers |
 | Redis | `FLUSHDB` before every case; a refusal by the gate | the same |
 | steps | pytest-bdd: a plugin of `pytest11` marks Given, When and Then, fails a case on what the harness found, and writes `tests/flows.yaml` after a whole run | |
 | `tests/surface.yaml` | Python's `ast` over the service's modules: routes from FastAPI's decorators and routers | routes from the `ROOT_URLCONF` and the views' methods |
@@ -126,8 +130,8 @@ and `requests`' `HTTPAdapter`. Every other client meets the proxy.
 
 **A template names what a step answers, not what the service sent.** As in
 specrig-js, a path segment in braces takes any one segment, the exact path wins,
-and of two templates the first declared; `reply`, `reply_to`, `time_out` and
-`requests` all take one. The contract check and the trace go on naming a request
+and of two templates the first declared; `reply`, `reply_to`, `reply_with`,
+`time_out` and `requests` all take one. The contract check and the trace go on naming a request
 by the path it came with, so a template that matches too much is not hidden by
 the contract it is checked against. A reply's headers are added to the response
 as the transports hand it to the client, so `httpx`, `httpx2` and `requests` see
@@ -148,6 +152,50 @@ triggers, and the quota that lets `refuse_after`'s rows through, live in a
 copies, and the reset drops it first. A refusal a step sets before the boot waits
 for the start, since the reset would lift it and the schema may not exist yet.
 
+**One engine, a server half, a dialect each.** As in gorib's `sqltest`: what every
+database does — migrate once, keep the rows, put them back before every case, the
+steps' faults and refusals — is `database.py`; the address chain, the container,
+the database of the run's own, the gate and the sweep are `server.py`, which
+Postgres and MySQL share; each dialect is its own SQL. SQLite has no server half,
+since a file needs none.
+
+**MySQL puts back only what a case changed.** Truncating a table, creating a
+trigger and setting a counter are DDL there: measured on a laptop, ~16 ms for a
+`TRUNCATE`, ~3 ms for a `CREATE TRIGGER`, 3 to 7 ms for an `ALTER TABLE …
+AUTO_INCREMENT`, against ~0.2 ms for a `DELETE` in a transaction. So the reset finds
+the tables a case changed by `CHECKSUM TABLE`, one statement for all of them, and
+touches nothing else: ~3 ms when nothing changed, against 118–158 ms for truncating
+six tables and writing their rows back. The triggers it drops are those its own writes
+would fire, created again in the `sql_mode` they were made in.
+
+**The harness's MySQL connection checks no foreign keys.** gorib's `sqltest` resets
+on a connection it closes afterwards, so that one with the checks off never goes
+back to the pool the service shares. Here the harness's connection is its own and
+never the service's, so it stays open with the checks off: opening one costs ~8 ms,
+three times an untouched reset.
+
+**No `refuse_commit` on MySQL or SQLite.** MySQL has no deferred constraint at all;
+SQLite fails a commit on demand only through a deferred foreign key, which every
+driver raises as an `IntegrityError`, so a case would test the conflict branch
+instead of a failed commit. The method is absent rather than failing when called.
+
+**SQLite's outage is an error, not a gate.** A file has no connection to cut, so
+`fail_with()` fails every statement through the frameworks' hooks with the driver's
+own `unable to open database file`. A driver's error reaches the service as the
+framework raises the driver's own, Postgres's and MySQL's alike. Django's execute
+wrappers run outside its error wrapper, so the hook raises inside it, and Django
+marks the connection as a real failure would. SQLAlchemy before 2.1 lets an event's
+error through as it is, so the hook wraps a DB-API error there; from 2.1 SQLAlchemy
+handles the raw error as one the driver raised — the disconnect check, the pool's
+invalidation, `handle_error` — and the hook leaves it to it.
+
+**A dialect from evidence, not by elimination.** `init` takes the database from a
+Django settings module's `ENGINE`, else from a server's driver, and gives SQLite
+only on a `sqlite:` address in `.env.example` or aiosqlite: a Django or SQLAlchemy
+service with no driver it can see is not taken for one on SQLite, and a
+`sqlite:///dev.db` a Postgres service keeps for its developers does not turn it
+into one.
+
 **Alembic in a process of its own.** Alembic's `env.py` configures logging as it
 runs, disabling the loggers the service already made; production runs the
 migration as a job of its own, and so does the harness.
@@ -170,14 +218,17 @@ libraries.
 
 ## The owner's calls
 
-1. **Python and the frameworks.** Python 3.11 and up; FastAPI 0.90 and up, and any
-   ASGI app a module builds; Django 4.2 and up. Not the newest, and not what nobody
-   runs any more.
+1. **Python and the frameworks.** Python 3.11 and up; FastAPI 0.100 and up, the
+   first on pydantic 2, and any ASGI app a module builds; Django 4.2 and up, with
+   psycopg 3.1.8 and up, which Django 4.2 asks for. Not the newest, and not what
+   nobody runs any more.
 2. **pytest-bdd.** 8.1 and up, and pytest 7.4 and up.
 3. **No bus yet.** RabbitMQ, Celery and Django's tasks are a later release.
 4. **gRPC.** Neither way.
 5. **Enforcement in Claude Code.** As in .NET and PHP: `rules` prints the
    service's rules, and the plugin checks every edit against them.
+6. **Databases.** Postgres, MySQL and SQLite. The frameworks' own scaffolds stay
+   as they are; the harness adds its dialects.
 
 ## Order, and where it stands
 
@@ -186,5 +237,5 @@ libraries.
 | 0 | the records and the fixtures | built |
 | 1 | boot, settings, HTTP stand-ins and the contract check, the pytest-bdd binding, Postgres, logs, the clock; HTTP, jobs and commands as ways in; `tests/flows.yaml` | built |
 | 2 | `tests/surface.yaml` and `tests/checks.yaml`, `init`, `rules`, `specrig.md` | built |
-| 3 | Redis, grants, `fail_with`, a refused table and `heal`, reply headers and path templates | built |
+| 3 | Redis, grants, `fail_with`, a refused table and `heal`, reply headers and path templates; MySQL and SQLite | built |
 | 4 | a bus and a queue | not started |