l3io-wordpress-database 0.3.5__py3-none-any.whl

l3io/wp/database/verdict.py

@@ -0,0 +1,193 @@
+"""What a check found, as data a caller can branch on.
+
+Every check returns a :class:`Verdict`. An operation runs its check first and
+refuses with :class:`~l3io.wp.database.errors.RefusedError` carrying the same
+verdict when it holds a blocker; on success the verdict's warnings travel on the
+result. A caller therefore branches on :class:`Code` values and never parses a
+message.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+
+
+class Severity(StrEnum):
+    """Whether a finding stops the operation."""
+
+    BLOCKER = "blocker"
+    WARNING = "warning"
+
+
+class Code(StrEnum):
+    """Every finding a check can report. Each code has exactly one severity."""
+
+    UNREACHABLE = "unreachable"
+    CREDENTIALS_UNOBTAINABLE = "credentials_unobtainable"
+    AUTHENTICATION_FAILED = "authentication_failed"
+    SERVER_UNSUPPORTED = "server_unsupported"
+    MISSING_PRIVILEGE = "missing_privilege"
+    PRIVILEGES_UNVERIFIED = "privileges_unverified"
+    DATABASE_ABSENT = "database_absent"
+    USER_ABSENT = "user_absent"
+    CONFIRMATION_MISMATCH = "confirmation_mismatch"
+    LIVE_WORDPRESS_SITE = "live_wordpress_site"
+    END_OF_LIFE_SERVER = "end_of_life_server"
+    MISSING_DEPENDENCY = "missing_dependency"
+    PASSWORD_UNVERIFIED = "password_unverified"  # noqa: S105 - a finding code, not a password
+    CLIENT_TOOL_MISSING = "client_tool_missing"
+    CLIENT_SERVER_SKEW = "client_server_skew"
+    PLATFORM_UNSUPPORTED = "platform_unsupported"
+    OPTION_NOT_ALLOWED = "option_not_allowed"
+    DATABASE_NOT_EMPTY = "database_not_empty"
+    INCOMPATIBLE_DUMP_SOURCE = "incompatible_dump_source"
+    CROSS_FAMILY_DUMP = "cross_family_dump"
+    STORED_OBJECTS_PRESENT = "stored_objects_present"
+    IDENTITY_REQUIRED = "identity_required"
+
+    @property
+    def severity(self) -> Severity:
+        """The fixed severity of this code."""
+        return _SEVERITY[self]
+
+    @property
+    def description(self) -> str:
+        """When this code is raised."""
+        return _DESCRIPTION[self]
+
+
+_B, _W = Severity.BLOCKER, Severity.WARNING
+
+_SEVERITY: Mapping[Code, Severity] = MappingProxyType(
+    {
+        Code.UNREACHABLE: _B,
+        Code.CREDENTIALS_UNOBTAINABLE: _B,
+        Code.AUTHENTICATION_FAILED: _B,
+        Code.SERVER_UNSUPPORTED: _B,
+        Code.MISSING_PRIVILEGE: _B,
+        Code.PRIVILEGES_UNVERIFIED: _W,
+        Code.DATABASE_ABSENT: _B,
+        Code.USER_ABSENT: _B,
+        Code.CONFIRMATION_MISMATCH: _B,
+        Code.LIVE_WORDPRESS_SITE: _W,
+        Code.END_OF_LIFE_SERVER: _W,
+        Code.MISSING_DEPENDENCY: _B,
+        Code.PASSWORD_UNVERIFIED: _W,
+        Code.CLIENT_TOOL_MISSING: _B,
+        Code.CLIENT_SERVER_SKEW: _W,
+        Code.PLATFORM_UNSUPPORTED: _B,
+        Code.OPTION_NOT_ALLOWED: _B,
+        Code.DATABASE_NOT_EMPTY: _B,
+        Code.INCOMPATIBLE_DUMP_SOURCE: _B,
+        Code.CROSS_FAMILY_DUMP: _W,
+        Code.STORED_OBJECTS_PRESENT: _W,
+        Code.IDENTITY_REQUIRED: _B,
+    }
+)
+
+_DESCRIPTION: Mapping[Code, str] = MappingProxyType(
+    {
+        Code.UNREACHABLE: "the server could not be reached",
+        Code.CREDENTIALS_UNOBTAINABLE: "a credential source failed to supply credentials",
+        Code.AUTHENTICATION_FAILED: "the server rejected the supplied account",
+        Code.SERVER_UNSUPPORTED: "the server is below MySQL 8.0 or MariaDB 10.2",
+        Code.MISSING_PRIVILEGE: (
+            "the account lacks a privilege the operation needs; fields.privilege names it"
+        ),
+        Code.PRIVILEGES_UNVERIFIED: (
+            "the account holds an active role, whose privileges information_schema does "
+            "not show, so privilege checks were skipped"
+        ),
+        Code.DATABASE_ABSENT: "the operation needs an existing database",
+        Code.USER_ABSENT: "the operation needs an existing account",
+        Code.CONFIRMATION_MISMATCH: "confirm= does not equal the operation's target",
+        Code.LIVE_WORDPRESS_SITE: (
+            "a destructive target has a WordPress options table and schema version"
+        ),
+        Code.END_OF_LIFE_SERVER: "the server version is past upstream end of life",
+        Code.PASSWORD_UNVERIFIED: (
+            "the account's host does not match this machine, so its password could not be "
+            "checked by logging in and was left unchanged; use rotate_password to set it"
+        ),
+        Code.MISSING_DEPENDENCY: (
+            "a credential source needs an extra that is not installed; fields.extra names it"
+        ),
+        Code.CLIENT_TOOL_MISSING: (
+            "no suitable dump or client program is on PATH; fields.tools names those tried"
+        ),
+        Code.CLIENT_SERVER_SKEW: (
+            "the client program's family, or its major.minor version, is older than or differs "
+            "from the server's"
+        ),
+        Code.PLATFORM_UNSUPPORTED: "export and import need /dev/fd, which this platform lacks",
+        Code.OPTION_NOT_ALLOWED: (
+            "a caller-supplied client option is not on the allow-list; fields.option names it"
+        ),
+        Code.DATABASE_NOT_EMPTY: "the load target holds tables and replace= was not given",
+        Code.INCOMPATIBLE_DUMP_SOURCE: (
+            "the dump begins with MariaDB's sandbox line and this client cannot read it; "
+            "allow_unsandboxed=True strips that line"
+        ),
+        Code.CROSS_FAMILY_DUMP: (
+            "the dump comes from the other server family; collations it uses may not exist here"
+        ),
+        Code.STORED_OBJECTS_PRESENT: (
+            "the database has views or triggers: they carry DEFINER clauses that loading needs "
+            "privilege for, and MariaDB keeps their original text, which may name this schema"
+        ),
+        Code.IDENTITY_REQUIRED: "the source is age-encrypted and no identity was supplied",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """One thing a check found."""
+
+    code: Code
+    message: str
+    fields: Mapping[str, str | int | bool] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Frozen dataclasses still hold a mutable dict; freeze the view too.
+        object.__setattr__(self, "fields", MappingProxyType(dict(self.fields)))
+
+    @property
+    def severity(self) -> Severity:
+        """The code's fixed severity."""
+        return self.code.severity
+
+
+@dataclass(frozen=True, slots=True)
+class Verdict:
+    """Everything one check found about one operation."""
+
+    operation: str
+    findings: tuple[Finding, ...] = ()
+
+    @property
+    def blockers(self) -> tuple[Finding, ...]:
+        """Findings that stop the operation."""
+        return tuple(f for f in self.findings if f.severity is Severity.BLOCKER)
+
+    @property
+    def warnings(self) -> tuple[Finding, ...]:
+        """Findings that let the operation run but describe a risk."""
+        return tuple(f for f in self.findings if f.severity is Severity.WARNING)
+
+    @property
+    def ok(self) -> bool:
+        """Whether nothing blocks the operation."""
+        return not self.blockers
+
+    @property
+    def codes(self) -> frozenset[Code]:
+        """Every code present."""
+        return frozenset(f.code for f in self.findings)
+
+    def with_findings(self, *findings: Finding) -> Verdict:
+        """A new verdict with ``findings`` appended."""
+        return Verdict(self.operation, self.findings + findings)

l3io/wp/database/versions.py

@@ -0,0 +1,101 @@
+"""Interpreting WordPress's ``db_version``.
+
+WordPress stores a schema revision in its options table. A hand-maintained
+dictionary mapping it to a release number stops at whatever release its author
+last added, and then returns ``None`` for every WordPress after it: it quietly
+stops working rather than merely ageing.
+
+The map is now derived from the source of truth and committed as generated
+data, so the runtime needs no network. See ``tools/generate_version_map.py``;
+regenerating is a maintenance task, not a deployment step.
+
+Two properties worth stating:
+
+* **The floor is WordPress 5.0**, which is a support decision rather than a
+  limit of the derivation -- ``$wp_db_version`` is readable back to 2.0 if the
+  floor ever needs lowering. Every one of the 328 releases at or above 5.0
+  yields a value, so the map has no gaps within its supported range. Anything
+  below the floor reports ``None`` and is distinguishable via
+  :attr:`SchemaVersion.is_older_than_supported`.
+* **The mapping is many-to-one.** Several releases share a ``db_version``
+  (7.0 and 7.1 both report 61833), so a value identifies the release that
+  *introduced* that schema, not the exact release installed.
+"""
+
+from __future__ import annotations
+
+import bisect
+from dataclasses import dataclass
+
+from ._version_map import DB_VERSION_TO_RELEASE, MIN_RELEASE
+
+#: Sorted db_version values, for the bisecting lookup below.
+_KNOWN: list[int] = sorted(DB_VERSION_TO_RELEASE)
+
+#: The db_version of the oldest supported release.
+FLOOR_DB_VERSION: int = _KNOWN[0]
+
+#: The db_version of the newest release the committed map knows about.
+CEILING_DB_VERSION: int = _KNOWN[-1]
+
+#: The oldest WordPress release this package reports on.
+SUPPORTED_FROM: str = MIN_RELEASE
+
+
+def release_for(db_version: int) -> str | None:
+    """The WordPress release that introduced this schema revision.
+
+    Returns the highest known release whose ``db_version`` is less than or
+    equal to the one observed -- not an exact-match lookup, because a site can
+    report a value between two releases (a development build), and because the
+    map is many-to-one.
+
+    Comparison is numeric. The original stored these values as strings, where
+    ``'9872' <= '48748'`` is ``False``, so an ordered lookup over the old map
+    would have been wrong even where its data was right.
+
+    Returns ``None`` below :data:`FLOOR_DB_VERSION`.
+    """
+    if db_version < FLOOR_DB_VERSION:
+        return None
+    index = bisect.bisect_right(_KNOWN, db_version) - 1
+    return DB_VERSION_TO_RELEASE[_KNOWN[index]]
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaVersion:
+    """A WordPress schema revision read from a site's options table."""
+
+    db_version: int
+
+    @property
+    def release(self) -> str | None:
+        """The WordPress release that introduced this schema, if supported.
+
+        A plain property, not cached: `slots=True` leaves no `__dict__` for
+        functools to cache into, and a bisect over a handful of entries is not
+        worth caching anyway.
+        """
+        return release_for(self.db_version)
+
+    @property
+    def is_newer_than_known(self) -> bool:
+        """Whether this schema postdates the committed map.
+
+        Distinct from unsupported: the map needs regenerating, rather than the
+        site being too old to report on.
+        """
+        return self.db_version > CEILING_DB_VERSION
+
+    @property
+    def is_older_than_supported(self) -> bool:
+        """Whether this site predates the oldest supported release."""
+        return self.db_version < FLOOR_DB_VERSION
+
+    def __str__(self) -> str:
+        if self.is_older_than_supported:
+            return f"db_version {self.db_version} (older than WordPress {SUPPORTED_FROM})"
+        if self.release is None:  # pragma: no cover - unreachable above the floor
+            return f"db_version {self.db_version} (no known release)"
+        suffix = " or newer" if self.is_newer_than_known else ""
+        return f"WordPress {self.release}{suffix} (db_version {self.db_version})"

l3io/wp/database/wpconfig.py

@@ -0,0 +1,145 @@
+"""Read connection details out of a WordPress ``wp-config.php``.
+
+An adapter over ``l3io-wordpress-config``, which lives behind the ``wpconfig`` extra.
+Per AD-1 the adapter *holds* the config object and exposes only what this
+package needs, rather than subclassing it -- subclassing would make every
+method of the underlying type public here automatically, so the declared
+surface would leak by construction and ``__all__`` could not bound it.
+
+Three properties of the upstream API matter enough to state:
+
+* An absent key returns a ``MISSING`` sentinel, not ``None``. ``MISSING`` is
+  falsy, so ``if config.get("DB_PASSWORD"):`` cannot distinguish "not defined"
+  from a legitimately empty value. Every read here tests ``is MISSING``.
+* PHP types are preserved, so ``define('DB_PORT', 3306)`` is an ``int`` while
+  ``define('DB_PASSWORD', '3306')`` stays a ``str``. Values are coerced
+  deliberately rather than assumed to be strings.
+* ``$table_prefix`` is a PHP *variable*, not a ``define()``, and lives in a
+  separate namespace: ``get_variable("table_prefix")``. ``get("table_prefix")``
+  correctly returns ``MISSING``.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+from .connection import Connection
+from .credentials import ResolvedCredentials
+from .errors import (
+    ConfigUnreadableError,
+    CredentialsAbsentError,
+    CredentialsUnobtainableError,
+    MissingConfigValueError,
+    MissingDependencyError,
+)
+
+#: WordPress's own default when ``$table_prefix`` is not set.
+DEFAULT_TABLE_PREFIX = "wp_"
+
+#: The ``l3io-wordpress-config`` releases this adapter accepts: the ``wpconfig``
+#: extra's specifier, which tests/test_wpconfig.py holds equal. An earlier release
+#: truncates a quoted value containing ``);``, and ``ensure`` would then set the
+#: account's password to the truncated value. Only an install through the extra
+#: enforces the range, so it is checked again here.
+REQUIRED_CONFIG = ">=0.1.2,<0.2"
+_CONFIG_FLOOR, _CONFIG_CEILING = (0, 1, 2), (0, 2, 0)
+
+
+def _accepts(version: str) -> bool:
+    match = re.match(r"\d+(?:\.\d+)*", version)
+    release = tuple(int(part) for part in match.group().split(".")) if match else ()
+    release += (0,) * (3 - len(release))
+    return _CONFIG_FLOOR <= release < _CONFIG_CEILING
+
+
+def _installed_config_version() -> str | None:
+    try:
+        return metadata.version("l3io-wordpress-config")
+    except metadata.PackageNotFoundError:
+        return None
+
+
+class WpConfigFile:
+    """A site's ``wp-config.php``: a credential source, and where its database lives.
+
+    Needs the ``wpconfig`` extra.
+    """
+
+    __slots__ = ("_config", "_missing", "_path")
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = str(path)
+        try:
+            from l3io.wp.config import MISSING, WpConfigError
+            from l3io.wp.config import WpConfigFile as _Upstream
+        except ImportError as exc:
+            raise MissingDependencyError(
+                extra="wpconfig", distribution="l3io-wordpress-config"
+            ) from exc
+        installed = _installed_config_version()
+        if installed is not None and not _accepts(installed):
+            raise MissingDependencyError(
+                extra="wpconfig",
+                distribution="l3io-wordpress-config",
+                found=installed,
+                required=REQUIRED_CONFIG,
+            )
+        self._missing = MISSING
+        try:
+            self._config: Any = _Upstream(filename=self._path)
+        except WpConfigError as exc:
+            raise ConfigUnreadableError(self._path, str(exc)) from exc
+
+    @property
+    def path(self) -> str:
+        return self._path
+
+    @property
+    def source(self) -> str:
+        return f"wp-config:{self._path}"
+
+    @property
+    def table_prefix(self) -> str:
+        """WordPress's ``$table_prefix``, or ``wp_`` when unset."""
+        value = self._config.get_variable("table_prefix")
+        return DEFAULT_TABLE_PREFIX if value is self._missing else str(value)
+
+    def resolve(self) -> ResolvedCredentials:
+        user, password = self._get("DB_USER"), self._get("DB_PASSWORD")
+        if user is None and password is None:
+            msg = f"{self._path} defines neither DB_USER nor DB_PASSWORD"
+            raise CredentialsAbsentError(msg, sources=(self.source,))
+        try:
+            return ResolvedCredentials(
+                self._require("DB_USER", user),
+                self._require("DB_PASSWORD", password),
+                self.source,
+            )
+        except MissingConfigValueError as exc:
+            # Half a pair is a failure, not an absence: a chain must not fall
+            # through to another credential after it (spec §5).
+            raise CredentialsUnobtainableError(str(exc)) from exc
+
+    def connection(self) -> Connection:
+        """Where the configured database lives."""
+        host = self._require("DB_HOST", self._get("DB_HOST"))
+        name = self._require("DB_NAME", self._get("DB_NAME"))
+        return Connection.from_db_host(host, name)
+
+    def _require(self, key: str, value: str | None) -> str:
+        """Return a value read by ``_get``, or raise naming the missing key."""
+        if value is None:
+            raise MissingConfigValueError(key, self._path)
+        return value
+
+    def _get(self, key: str) -> str | None:
+        value: Any = self._config.get(key)
+        if value is self._missing:
+            return None
+        return value if isinstance(value, str) else str(value)
+
+    def __repr__(self) -> str:
+        return f"WpConfigFile(path={self._path!r})"

l3io_wordpress_database-0.3.5.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: l3io-wordpress-database
+Version: 0.3.5
+Summary: Create and inspect WordPress MySQL databases and their users, idempotently.
+Project-URL: Homepage, https://github.com/LiquidLogicLabs/l3io-wordpress-database
+Project-URL: Source, https://github.com/LiquidLogicLabs/l3io-wordpress-database
+Author: Shawn Anderson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: database,mariadb,mysql,provisioning,wordpress
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api<2,>=1.30
+Requires-Dist: pymysql[rsa]<2,>=1.2
+Requires-Dist: structlog<27,>=26.1
+Provides-Extra: aws
+Requires-Dist: boto3<2,>=1.34; extra == 'aws'
+Provides-Extra: encryption
+Requires-Dist: l3io-age-passphrase<0.2,>=0.1.1; extra == 'encryption'
+Requires-Dist: pyrage<2,>=1.4; extra == 'encryption'
+Provides-Extra: wpconfig
+Requires-Dist: l3io-wordpress-config<0.2,>=0.1.2; extra == 'wpconfig'
+Description-Content-Type: text/markdown
+
+# l3io-wordpress-database
+
+The operations a WordPress site performs against its MySQL or MariaDB database:
+inspecting it, provisioning it, changing its accounts, destroying it, and exporting
+and importing it. Every operation acts with credentials the caller supplies, and
+every operation that changes or moves something can be checked before it runs.
+
+It imports as `l3io.wp.database`, in the `l3io.wp` namespace shared with
+`l3io-wordpress-config` and `l3io-wordpress-backup`.
+
+> **Status:** 0.x — documented and typed, with no stability promise until 1.0.0.
+> Not yet on PyPI; releases are on
+> [GitHub](https://github.com/LiquidLogicLabs/l3io-wordpress-database/releases).
+
+## Installing
+
+```shell
+pip install l3io-wordpress-database                # core: PyMySQL, structlog, opentelemetry-api
+pip install 'l3io-wordpress-database[aws]'         # credentials from AWS Secrets Manager
+pip install 'l3io-wordpress-database[wpconfig]'    # credentials and location from wp-config.php
+pip install 'l3io-wordpress-database[encryption]'  # age-encrypted dumps
+```
+
+An optional dependency is an optional import: a base install never imports
+`boto3`, the config reader or `pyrage`, and asking for a feature whose extra is
+absent raises `MissingDependencyError` naming the extra.
+
+## Two accounts
+
+WordPress's own account — the one in `wp-config.php` — is the account that is
+created and granted. A separate administrative account does the creating, and is
+never defaulted to the WordPress account. Whether a database exists is answered
+by the administrator: a server authenticates before it resolves the database, so a
+failed login by the WordPress account says nothing about the database.
+
+## Check, then run
+
+```python
+from l3io.wp.database import Connection, Database, Environment, Explicit
+
+db = Database(Connection("127.0.0.1", "wp_site"))
+admin = Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD")
+wordpress = Explicit("wpuser", "wp-pass")
+
+verdict = db.check_ensure(admin, wordpress)
+for finding in verdict.findings:
+    print(finding.severity, finding.code, finding.message)
+
+if verdict.ok:
+    result = db.ensure(admin, wordpress)
+    print(result.created_database, result.created_user, result.granted, result.changed)
+```
+
+`ensure` runs the same check itself and raises `RefusedError`, carrying the
+`Verdict`, on any blocker. It creates only what is missing, and a second run
+against a converged server changes nothing. Grants are scoped to the one database,
+with the `_` and `%` wildcards in its name escaped.
+
+Destructive operations — `revoke`, `drop_user`, `drop_database` — take
+`confirm=`, which must repeat the target's name.
+
+## From wp-config.php
+
+```python
+from l3io.wp.database import Database, Environment, WpConfigFile
+
+site = WpConfigFile("/var/www/html/wp-config.php")
+db = Database(site.connection())
+survey = db.survey(
+    Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD"),
+    wordpress_user=site.resolve().username,
+    table_prefix=site.table_prefix,
+)
+print(survey.database_exists, survey.table_count, survey.is_wordpress, survey.schema_version)
+```
+
+`inspect` asks the WordPress account itself what it can do, and never raises
+for an ordinary failure:
+
+| State | Meaning |
+|---|---|
+| `ready` | connected, authenticated, and the database is usable |
+| `database_absent` | authenticated, but the database does not exist |
+| `access_denied` | authenticated, but may not use this database |
+| `authentication_failed` | the server rejected the account |
+| `unreachable` | the server could not be reached |
+| `credentials_unobtainable` | the credentials could not be obtained; nothing was attempted |
+
+## Export and import
+
+```python
+from l3io.wp.database import (
+    Connection,
+    Database,
+    Environment,
+    WpConfigFile,
+    encrypt,
+    generate_identity,
+)
+
+site = WpConfigFile("/var/www/html/wp-config.php")
+identity, recipient = generate_identity()
+Database(site.connection()).dump(site, "/backups/wp_site.sql.age", recipients=[recipient])
+# Or passphrase mode (mutually exclusive with recipients= / identities=):
+# Database(site.connection()).dump(site, "/backups/wp_site.sql.age", passphrase=secret)
+
+admin = Environment("DB_ADMIN_USER", "DB_ADMIN_PASSWORD")
+staging = Database(Connection("127.0.0.1", "wp_site_staging"))
+staging.ensure(admin, site)
+staging.load(site, "/backups/wp_site.sql.age", identities=[identity])
+```
+
+Dumps are made by the server's own client tools (`mysqldump` or `mariadb-dump`),
+and loads by `mysql` or `mariadb`. The password reaches them only through an
+anonymous pipe: never an argument, an environment variable or a file. A dump to
+a path is written under a temporary name and renamed only on success. `iter_dump`
+yields the dump as chunks, and raises at the end if the tool failed, so a
+truncated dump is never mistaken for a whole one.
+
+Loading into a database that holds tables requires `replace=` naming it. A damaged
+source is discovered mid-load, after the statements before the damage have run,
+so load into a staging database and switch to it once the load succeeds.
+
+Encryption is standard [age](https://age-encryption.org): recipient keys or a
+passphrase (scrypt sole recipient). Either streams; any dump can be decrypted
+with the stock `age` command line. Passphrase mode uses the
+`l3io-age-passphrase` binder by default, or `age` + `age-plugin-batchpass` when
+`L3IO_AGE_PASSPHRASE_BACKEND=cli` (or when the binder is absent under `auto`).
+Archive callers can also
+`from l3io.wp.database import encrypt, decrypt, check_passphrase`.
+
+## Command line
+
+```shell
+l3io-wordpress-database survey --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database check ensure --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database ensure --wp-config /var/www/html/wp-config.php \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD
+l3io-wordpress-database dump --wp-config /var/www/html/wp-config.php \
+    --output wp_site.sql.age --recipient age1examplerecipient
+l3io-wordpress-database dump --wp-config /var/www/html/wp-config.php \
+    --output wp_site.sql.age --passphrase-file /run/secrets/age-passphrase
+l3io-wordpress-database load --db-host 127.0.0.1 --db-name wp_site_staging \
+    --db-user wpuser --db-password-env DB_PASSWORD \
+    --input wp_site.sql.age --identity key.txt
+l3io-wordpress-database load --db-host 127.0.0.1 --db-name wp_site_staging \
+    --db-user wpuser --db-password-env DB_PASSWORD \
+    --input wp_site.sql.age --ask-passphrase
+l3io-wordpress-database drop-database --db-host 127.0.0.1 --db-name wp_site_staging \
+    --admin-user root --admin-password-env DB_ADMIN_PASSWORD --confirm wp_site_staging
+```
+
+No password or age passphrase is accepted as an argument value, because an
+argument vector is visible to every user on the machine: a password comes from
+`--wp-config`, from the environment variable named by a `--*-password-env`
+option, from AWS Secrets Manager, or from a prompt; an age passphrase comes from
+`--passphrase-file` or `--ask-passphrase` (mutually exclusive with
+`--recipient` / `--identity`). Results are printed as JSON on stdout; with
+`dump --output -` the dump is on stdout and the result on stderr.
+
+| Exit code | Meaning |
+|---|---|
+| `0` | success |
+| `1` | the operation started and failed |
+| `2` | usage |
+| `3` | refused: the check found a blocker, and nothing ran |
+| `4` | credentials could not be obtained |
+| `5` | the server could not be reached |
+| `7` | not ready: `inspect` found the account cannot use the database |
+
+## Supported
+
+- Python 3.11, 3.12, 3.13 and 3.14.
+- MySQL 8.0 and later, MariaDB 10.2 and later. CI runs MySQL 8.0, 8.4 and 9.7 and
+  MariaDB 10.2 and 11.4.
+- Export and import need `/dev/fd` (Linux or macOS) and the client tools on `PATH`.
+  Everything else is pure Python.
+
+The package logs through `structlog` and never configures logging, and opens one
+OpenTelemetry span per operation through `opentelemetry-api`, inert until the host
+configures an SDK.
+
+## Design records
+
+This package's decisions are in [docs/adr](docs/adr/README.md). The rules the
+`l3io.wp` family shares (cited as AD-n) are in `l3io-wordpress-backup`'s
+architecture spine.
+
+## Development
+
+```shell
+make sync                                # locked environment, all extras
+make check                               # lint, format, types, tests, contracts
+make test-db DB_HOST=127.0.0.1           # integration tests against a server
+make test-transfer ENGINE=mysql:8.4      # export/import with that image's own client tools
+make verify-wheel                        # install the built wheel, bare and with each extra
+make ci                                  # replay the CI pipeline under act
+```
+
+## Licence
+
+MIT.