snapdelta-postgres 0.2.0__tar.gz

snapdelta_postgres-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.tmp

snapdelta_postgres-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

snapdelta_postgres-0.2.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: snapdelta-postgres
+Version: 0.2.0
+Summary: PostgreSQL store backend for snapdelta: snapshots, diffs and runs in a database that many servers share
+Project-URL: Homepage, https://github.com/antoinekh/snapdelta
+Project-URL: Documentation, https://github.com/antoinekh/snapdelta/blob/main/docs/stores.md
+Project-URL: Issues, https://github.com/antoinekh/snapdelta/issues
+Project-URL: Changelog, https://github.com/antoinekh/snapdelta/blob/main/CHANGELOG.md
+Author-email: Antoine Keranflec'h <antoine.keranflech@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: diff,netdevops,network-automation,plugin-architecture,postgresql,snapshot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: psycopg-pool<4,>=3.2
+Requires-Dist: psycopg[binary]<4,>=3.2
+Requires-Dist: snapdelta<0.3,>=0.2.0
+Description-Content-Type: text/markdown
+
+# snapdelta-postgres
+
+A PostgreSQL store backend for [snapdelta](https://github.com/antoinekh/snapdelta): the snapshots, the diffs and the runs in a database, which many snapdelta servers and workers can share.
+
+```bash
+pip install snapdelta-postgres
+snapdelta --store postgresql://snapdelta@db.example.net/snapdelta info
+```
+
+The location is a libpq URI without its password, such as `postgresql://USER@HOST:PORT/DATABASE?sslmode=require`; snapdelta shows the location in its pages and its runs. Give the password in the settings, or in `PGPASSWORD` or `~/.pgpass`:
+
+```toml
+[store]
+location = "postgresql://snapdelta@db.example.net/snapdelta"
+
+[stores.postgresql]
+password = { env = "SNAPDELTA_DB_PASSWORD" }
+connect_timeout_s = 10
+pool_size = 4
+```
+
+The store creates its three tables, `snapdelta_snapshots`, `snapdelta_outputs` and `snapdelta_runs`, at its first use; the user needs the right to create tables in the database. The bodies are the JSON documents of the file store, as `json`, which keeps their order. See [docs/stores.md](https://github.com/antoinekh/snapdelta/blob/main/docs/stores.md).

snapdelta_postgres-0.2.0/README.md

@@ -0,0 +1,22 @@
+# snapdelta-postgres
+
+A PostgreSQL store backend for [snapdelta](https://github.com/antoinekh/snapdelta): the snapshots, the diffs and the runs in a database, which many snapdelta servers and workers can share.
+
+```bash
+pip install snapdelta-postgres
+snapdelta --store postgresql://snapdelta@db.example.net/snapdelta info
+```
+
+The location is a libpq URI without its password, such as `postgresql://USER@HOST:PORT/DATABASE?sslmode=require`; snapdelta shows the location in its pages and its runs. Give the password in the settings, or in `PGPASSWORD` or `~/.pgpass`:
+
+```toml
+[store]
+location = "postgresql://snapdelta@db.example.net/snapdelta"
+
+[stores.postgresql]
+password = { env = "SNAPDELTA_DB_PASSWORD" }
+connect_timeout_s = 10
+pool_size = 4
+```
+
+The store creates its three tables, `snapdelta_snapshots`, `snapdelta_outputs` and `snapdelta_runs`, at its first use; the user needs the right to create tables in the database. The bodies are the JSON documents of the file store, as `json`, which keeps their order. See [docs/stores.md](https://github.com/antoinekh/snapdelta/blob/main/docs/stores.md).

snapdelta_postgres-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "snapdelta-postgres"
+version = "0.2.0"
+description = "PostgreSQL store backend for snapdelta: snapshots, diffs and runs in a database that many servers share"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+authors = [{ name = "Antoine Keranflec'h", email = "antoine.keranflech@gmail.com" }]
+keywords = ["network-automation", "netdevops", "snapshot", "diff", "postgresql", "plugin-architecture"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: System :: Networking",
+    "Typing :: Typed",
+]
+dependencies = ["snapdelta>=0.2.0,<0.3", "psycopg[binary]>=3.2,<4", "psycopg-pool>=3.2,<4"]
+
+[project.urls]
+Homepage = "https://github.com/antoinekh/snapdelta"
+Documentation = "https://github.com/antoinekh/snapdelta/blob/main/docs/stores.md"
+Issues = "https://github.com/antoinekh/snapdelta/issues"
+Changelog = "https://github.com/antoinekh/snapdelta/blob/main/CHANGELOG.md"
+
+[project.entry-points."snapdelta.stores"]
+postgresql = "snapdelta_postgres:PostgresStore"
+
+[tool.uv.sources]
+snapdelta = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/snapdelta_postgres"]

snapdelta_postgres-0.2.0/src/snapdelta_postgres/__init__.py

@@ -0,0 +1,5 @@
+"""PostgreSQL store backend for snapdelta: `--store postgresql://USER@HOST:PORT/DATABASE`."""
+
+from .store import PostgresSettings, PostgresStore
+
+__all__ = ["PostgresSettings", "PostgresStore"]

snapdelta_postgres-0.2.0/src/snapdelta_postgres/store.py

@@ -0,0 +1,258 @@
+"""The store `postgresql://`: the tables of the SQLite store in a PostgreSQL database, with the bodies as json.
+
+json and not jsonb: jsonb sorts the keys, and the order of the models and objects of a diff is the order to show.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, LiteralString
+
+import psycopg
+from psycopg.conninfo import conninfo_to_dict
+from psycopg.types.json import Json
+from psycopg_pool import ConnectionPool, PoolTimeout
+from pydantic import Field
+
+from snapdelta.activity import Run
+from snapdelta.errors import NotFoundError, SnapdeltaError
+from snapdelta.output import Output
+from snapdelta.settings import Secret, StoreBackendSettings
+from snapdelta.snapshot import SnapshotFile
+from snapdelta.store import (
+    OutputEntry,
+    SnapshotEntry,
+    Store,
+    StoreInfo,
+    output_entry,
+    parse_output,
+    parse_run,
+    parse_snapshot,
+    snapshot_entry,
+)
+
+SCHEME = "postgresql"
+TABLES = """
+create table if not exists snapdelta_snapshots (
+    reference text primary key,
+    target text not null,
+    captured_at timestamptz not null,
+    label text,
+    source text not null,
+    body json not null
+);
+create index if not exists snapdelta_snapshots_by_target on snapdelta_snapshots (target, reference);
+create table if not exists snapdelta_outputs (
+    name text primary key,
+    created_at timestamptz not null,
+    left_target text not null,
+    right_target text not null,
+    body json not null
+);
+create index if not exists snapdelta_outputs_by_time on snapdelta_outputs (created_at);
+create table if not exists snapdelta_runs (
+    id text primary key,
+    body json not null
+);
+"""
+# Two servers that start at the same time must not create the tables twice.
+LOCK_ID = 0x736E6170
+
+
+class PostgresSettings(StoreBackendSettings):
+    password: Secret | None = Field(
+        default=None,
+        description="The password of the database user; never in the location, which the pages and the runs show.",
+    )
+    connect_timeout_s: float = Field(default=10, gt=0, description="How long a connection may take, in seconds.")
+    pool_size: int = Field(
+        default=4, ge=1, le=100, description="The connections that the store keeps open, for the requests at once."
+    )
+
+
+class PostgresStore(Store):
+    """`postgresql://USER@HOST:PORT/DATABASE?OPTIONS`: any libpq URI, without its password."""
+
+    backend = SCHEME
+    settings_class = PostgresSettings
+
+    def __init__(self, address: str, settings: PostgresSettings) -> None:
+        conninfo = f"{SCHEME}://{address}"
+        try:
+            parts = conninfo_to_dict(conninfo)
+        except psycopg.ProgrammingError as error:
+            raise SnapdeltaError(f"{SCHEME}://{_without_password(address)}: not a valid location ({error})") from error
+        if "password" in parts:
+            raise SnapdeltaError(
+                "the location of a postgresql store holds a password, and snapdelta shows the location: "
+                "put the password in [stores.postgresql] password, or in PGPASSWORD or ~/.pgpass"
+            )
+        self.address = address
+        connection: dict[str, Any] = {"connect_timeout": math.ceil(settings.connect_timeout_s)}
+        if settings.password is not None:
+            connection["password"] = settings.password.value()
+        self.pool = ConnectionPool(conninfo, kwargs=connection, min_size=1, max_size=settings.pool_size, open=False)
+        try:
+            self.pool.open(wait=True, timeout=settings.connect_timeout_s)
+        except PoolTimeout as error:
+            self.pool.close()
+            raise SnapdeltaError(f"{self.location}: no connection within {settings.connect_timeout_s} s") from error
+        with self._connect() as db:
+            db.execute("select pg_advisory_xact_lock(%s)", (LOCK_ID,))
+            db.execute(TABLES)
+
+    @classmethod
+    def open(cls, address: str, settings: StoreBackendSettings) -> PostgresStore:
+        return cls(address, settings if isinstance(settings, PostgresSettings) else PostgresSettings())
+
+    @property
+    def location(self) -> str:
+        return f"{SCHEME}://{self.address}"
+
+    def close(self) -> None:
+        self.pool.close()
+
+    @contextmanager
+    def _connect(self) -> Iterator[psycopg.Connection[Any]]:
+        """A connection of the pool, in one transaction that commits at the end of the block."""
+        with self.pool.connection() as db:
+            yield db
+
+    def targets(self, query: str = "") -> list[str]:
+        wanted = query.strip().lower()
+        with self._connect() as db:
+            rows = db.execute(
+                "select distinct target from snapdelta_snapshots where strpos(lower(target), %s) > 0 order by target",
+                (wanted,),
+            ).fetchall()
+        return [row[0] for row in rows]
+
+    def snapshot_entries(self, target: str) -> list[SnapshotEntry]:
+        with self._connect() as db:
+            rows = db.execute(
+                "select reference from snapdelta_snapshots where target = %s order by reference desc", (target,)
+            ).fetchall()
+        return [entry for (reference,) in rows if (entry := snapshot_entry(reference))]
+
+    def output_entries(self, query: str = "") -> list[OutputEntry]:
+        wanted = query.strip().lower()
+        with self._connect() as db:
+            rows = db.execute(
+                "select name from snapdelta_outputs "
+                "where strpos(lower(left_target), %s) > 0 or strpos(lower(right_target), %s) > 0 order by name desc",
+                (wanted, wanted),
+            ).fetchall()
+        return [entry for (name,) in rows if (entry := output_entry(name))]
+
+    def info(self) -> StoreInfo:
+        with self._connect() as db:
+            row = db.execute(
+                "select (select count(distinct target) from snapdelta_snapshots), "
+                "(select count(*) from snapdelta_snapshots), (select count(*) from snapdelta_outputs), "
+                "(select count(*) from snapdelta_runs), "
+                "pg_total_relation_size('snapdelta_snapshots') + pg_total_relation_size('snapdelta_outputs') "
+                "+ pg_total_relation_size('snapdelta_runs')"
+            ).fetchone()
+        assert row is not None
+        targets, snapshots, outputs, runs, size = row
+        return StoreInfo(self.backend, self.location, targets, snapshots, outputs, size, runs)
+
+    def _has_snapshot(self, reference: str) -> bool:
+        with self._connect() as db:
+            found = db.execute("select 1 from snapdelta_snapshots where reference = %s", (reference,)).fetchone()
+        return found is not None
+
+    def _write_snapshot(self, reference: str, snapshot: SnapshotFile) -> None:
+        values = (
+            reference,
+            reference.partition("/")[0],
+            snapshot.captured_at,
+            snapshot.label,
+            snapshot.source,
+            Json(snapshot.model_dump(mode="json", by_alias=True)),
+        )
+        try:
+            with self._connect() as db:
+                db.execute(
+                    "insert into snapdelta_snapshots (reference, target, captured_at, label, source, body) "
+                    "values (%s, %s, %s, %s, %s, %s)",
+                    values,
+                )
+        except psycopg.errors.UniqueViolation as error:
+            # Another writer saved the same reference between the check and this insert.
+            raise SnapdeltaError(f"snapshot {reference} already exists: give another label") from error
+
+    def _read_snapshot(self, reference: str) -> SnapshotFile:
+        body = self._body("select body from snapdelta_snapshots where reference = %s", reference, "snapshot")
+        return parse_snapshot(body, reference)
+
+    def _delete_snapshot(self, reference: str) -> None:
+        with self._connect() as db:
+            db.execute("delete from snapdelta_snapshots where reference = %s", (reference,))
+
+    def _has_output(self, name: str) -> bool:
+        with self._connect() as db:
+            return db.execute("select 1 from snapdelta_outputs where name = %s", (name,)).fetchone() is not None
+
+    def _write_output(self, name: str, output: Output) -> None:
+        values = (
+            name,
+            output.created_at,
+            output.left.target,
+            output.right.target,
+            Json(output.model_dump(mode="json", by_alias=True)),
+        )
+        with self._connect() as db:
+            db.execute(
+                "insert into snapdelta_outputs (name, created_at, left_target, right_target, body) "
+                "values (%s, %s, %s, %s, %s)",
+                values,
+            )
+
+    def _read_output(self, name: str) -> Output:
+        return parse_output(self._body("select body from snapdelta_outputs where name = %s", name, "output"), name)
+
+    def _replace_output(self, name: str, output: Output) -> None:
+        with self._connect() as db:
+            db.execute(
+                "update snapdelta_outputs set body = %s where name = %s",
+                (Json(output.model_dump(mode="json", by_alias=True)), name),
+            )
+
+    def _delete_output(self, name: str) -> None:
+        with self._connect() as db:
+            db.execute("delete from snapdelta_outputs where name = %s", (name,))
+
+    def _write_run(self, run: Run) -> None:
+        with self._connect() as db:
+            db.execute(
+                "insert into snapdelta_runs (id, body) values (%s, %s) "
+                "on conflict (id) do update set body = excluded.body",
+                (run.id, Json(run.model_dump(mode="json"))),
+            )
+
+    def _read_run(self, run_id: str) -> Run:
+        return parse_run(self._body("select body from snapdelta_runs where id = %s", run_id, "run"), run_id)
+
+    def _run_ids(self) -> list[str]:
+        with self._connect() as db:
+            return [row[0] for row in db.execute("select id from snapdelta_runs order by id desc").fetchall()]
+
+    def _delete_run(self, run_id: str) -> None:
+        with self._connect() as db:
+            db.execute("delete from snapdelta_runs where id = %s", (run_id,))
+
+    def _body(self, query: LiteralString, key: str, kind: str) -> dict[str, Any]:
+        with self._connect() as db:
+            row = db.execute(query, (key,)).fetchone()
+        # Another process can delete the row between the existence check and this read.
+        if row is None:
+            raise NotFoundError(f"no {kind} {key!r} in {self.location}")
+        return row[0]
+
+
+def _without_password(address: str) -> str:
+    user, at, rest = address.rpartition("@")
+    return f"{user.partition(':')[0]}{at}{rest}" if at else address

snapdelta_postgres-0.2.0/tests/test_postgres.py

@@ -0,0 +1,73 @@
+"""The PostgreSQL store against a server: set SNAPDELTA_POSTGRES_URL, such as `make test-postgres` does."""
+
+import os
+import uuid
+from collections.abc import Iterator
+
+import psycopg
+import pytest
+
+from snapdelta.errors import SnapdeltaError
+from snapdelta.settings import Secret
+from snapdelta.store import open_store
+from snapdelta.testing import StoreContract, sample
+from snapdelta_postgres import PostgresSettings, PostgresStore
+
+# An administrator of a server, which may create and drop a database for each test.
+SERVER = os.environ.get("SNAPDELTA_POSTGRES_URL", "")
+needs_server = pytest.mark.skipif(not SERVER, reason="set SNAPDELTA_POSTGRES_URL to test against PostgreSQL")
+
+
+@pytest.fixture
+def database() -> Iterator[str]:
+    """The address of a new, empty database, dropped after the test."""
+    name = f"snapdelta_test_{uuid.uuid4().hex[:12]}"
+    with psycopg.connect(SERVER, autocommit=True) as admin:
+        admin.execute(f'create database "{name}"')
+    yield SERVER.removeprefix("postgresql://").rsplit("/", 1)[0] + f"/{name}"
+    with psycopg.connect(SERVER, autocommit=True) as admin:
+        admin.execute(f'drop database "{name}" with (force)')
+
+
+@needs_server
+class TestPostgresStore(StoreContract):
+    @pytest.fixture
+    def store(self, database: str) -> Iterator[PostgresStore]:
+        store = PostgresStore.open(database, PostgresSettings())
+        yield store
+        store.close()
+
+
+@needs_server
+def test_the_scheme_opens_the_backend_and_two_stores_share_the_tables(database: str) -> None:
+    first = open_store(f"postgresql://{database}")
+    second = open_store(f"postgresql://{database}")
+    try:
+        assert isinstance(first, PostgresStore) and first.info().backend == "postgresql"
+        reference = first.save_snapshot(sample())
+        assert second.resolve_snapshot("R1@latest") == reference
+        with pytest.raises(SnapdeltaError, match="already exists"):
+            second.save_snapshot(sample())
+    finally:
+        first.close()
+        second.close()
+
+
+@needs_server
+def test_a_password_of_the_settings_is_used(database: str, monkeypatch: pytest.MonkeyPatch) -> None:
+    password = os.environ.get("PGPASSWORD")
+    if password is None:
+        pytest.skip("the test server needs no password")
+    monkeypatch.delenv("PGPASSWORD")
+    store = PostgresStore.open(database, PostgresSettings(password=Secret(plain=password)))
+    store.close()
+
+
+def test_a_location_with_a_password_is_refused() -> None:
+    with pytest.raises(SnapdeltaError, match=r"put the password in \[stores.postgresql\] password"):
+        PostgresStore.open("snapdelta:s3cret@db.example.net/snapdelta", PostgresSettings())
+
+
+def test_a_server_that_does_not_answer_is_an_error_message() -> None:
+    with pytest.raises(SnapdeltaError, match="no connection within 1.0 s"):
+        PostgresStore.open("snapdelta@127.0.0.1:9/snapdelta", PostgresSettings(connect_timeout_s=1))