postgresledger 0.0.1__py3-none-any.whl

postgresledger/__init__.py

@@ -0,0 +1,6 @@
+"""postgresledger - versioned PostgreSQL migrations from plain SQL, on top of pgschema."""
+
+from importlib.metadata import version
+
+# the version of the installed package: the release tag it was built from (0.0.0 in a local checkout)
+__version__ = version("postgresledger")

postgresledger/cli.py

@@ -0,0 +1,205 @@
+"""pgl - versioned PostgreSQL migrations from plain SQL, without an ORM."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import textwrap
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import __version__, commands
+from .config import CONFIG_NAME, Config, relative
+
+# commands that run without a postgresledger.toml
+NO_CONFIG = {"init", "setup"}
+# commands that read the project but never touch a database
+# (compare with two snapshots; compare with one checks DATABASE_NAME itself)
+NO_DATABASE = {"new", "compare"}
+
+INTRO = """\
+Versioned PostgreSQL migrations from plain SQL, without an ORM.
+
+Works on one database: DATABASE_* from .env (or the environment). schema.sql
+is the desired state; every change to it becomes a numbered migration. The
+database records which migrations it has, and changes made by hand (drift)
+are found and can be captured as a migration. Scratch work happens in
+a throwaway Postgres on this machine, deleted after each command."""
+
+EXAMPLES = """\
+examples:
+  pgl init                   start in a new project
+  pgl baseline               snapshot the existing database
+  pgl new add_email          after editing schema.sql
+  pgl apply                  bring the database up to date
+  pgl drift                  was the database changed by hand?
+  pgl compare uat prod       how do two saved snapshots differ?
+
+`pgl <command> -h` shows the details of one command.
+postgresledger.toml is read from the current folder (or --config)."""
+
+
+def add_init_arguments(command_parser: argparse.ArgumentParser) -> None:
+    command_parser.add_argument("--dir", default="database",
+                                help="folder for schema/ and migrations/ (default: database)")
+    command_parser.add_argument("--no-setup", action="store_true",
+                                help="don't download pgschema and the scratch Postgres")
+
+
+def add_name_argument(command_parser: argparse.ArgumentParser) -> None:
+    command_parser.add_argument("name", help="lowercase letters, digits and _")
+
+
+def add_new_arguments(command_parser: argparse.ArgumentParser) -> None:
+    add_name_argument(command_parser)
+    command_parser.add_argument("--note", help="comment written into the migration header")
+
+
+def add_apply_arguments(command_parser: argparse.ArgumentParser) -> None:
+    command_parser.add_argument("--dry-run", action="store_true", help="only list what would be applied")
+
+
+def add_snapshot_arguments(command_parser: argparse.ArgumentParser) -> None:
+    command_parser.add_argument("name", help="label for the database, e.g. prod")
+
+
+def add_compare_arguments(command_parser: argparse.ArgumentParser) -> None:
+    command_parser.add_argument("a", help="snapshot name or file")
+    command_parser.add_argument("b", nargs="?", help="snapshot name or file (default: the database)")
+
+
+@dataclass(frozen=True)
+class Command:
+    """One `pgl` command as the help shows it. It runs commands.cmd_<name>."""
+
+    group: str  # a key of GROUPS
+    name: str
+    usage: str  # the arguments shown in the overview
+    summary: str
+    details: str
+    add_arguments: Callable[[argparse.ArgumentParser], None] | None = None
+
+
+COMMANDS = [
+    Command(
+        "setup", "init", "[--dir D]", "create postgresledger.toml, .env and folders",
+        "Creates postgresledger.toml (project settings, committed) and .env with DATABASE_* (never committed, "
+        "added to .gitignore) in the current folder, plus <dir>/schema/ and <dir>/migrations/, then runs setup.",
+        add_init_arguments),
+    Command(
+        "setup", "setup", "", "download pgschema + scratch Postgres, check psql",
+        "Downloads the pinned pgschema and a pinned Postgres server into ~/.cache/postgresledger/ (once per "
+        "machine, SHA256 checked) and checks that psql is installed. The Postgres server is only ever "
+        "started as a throwaway scratch database on this machine."),
+
+    Command(
+        "migrations", "baseline", "", "snapshot the database as 0001_baseline",
+        "No migrations yet: dumps the database into schema.sql and creates 0001_baseline.sql from it, "
+        "recorded as 'baseline' (not executed). Migrations exist: an existing database that already has "
+        "exactly their schema gets them recorded as 'baseline' instead of applying them; if it differs, "
+        "the differences are listed and nothing is recorded."),
+    Command(
+        "migrations", "new", "<name> [--note T]", "new migration from the changes in schema.sql",
+        "Builds the state of every existing migration in a scratch Postgres, compares it with schema.sql "
+        "and writes the difference as NNNN_<name>.sql. The file is checked there and deleted if it does "
+        "not reproduce schema.sql. Nothing is written when there is no change. The database is not touched.",
+        add_new_arguments),
+    Command(
+        "migrations", "apply", "[--dry-run]", "apply pending migrations",
+        "Runs every migration the database does not have yet, in order, each in one transaction together "
+        "with its record. Refuses to run when an already applied file was edited.",
+        add_apply_arguments),
+    Command(
+        "migrations", "status", "", "which migrations the database has",
+        "Every migration with its state on the database: applied, baseline, captured or PENDING."),
+
+    Command(
+        "drift", "drift", "", "list manual changes (exit 1 if any)",
+        "Compares the database with the state its migrations describe (built in a scratch Postgres) and "
+        "lists every difference. The database must be up to date first (apply)."),
+    Command(
+        "drift", "capture", "<name>", "keep manual changes as a new migration",
+        "Takes the manual changes into schema.sql and creates NNNN_<name>.sql from them. It is recorded "
+        "as 'captured' on this database (not executed) and reaches the other databases with apply.",
+        add_name_argument),
+
+    Command(
+        "compare", "snapshot", "<name>", "save the database schema as snapshots/<name>.sql",
+        "Dumps the schema of the database into <snapshots_dir>/<name>.sql, e.g. `pgl snapshot prod` with "
+        "the prod .env. Commit it to compare databases later.",
+        add_snapshot_arguments),
+    Command(
+        "compare", "compare", "<a> [b]", "differences between two snapshots",
+        "Compares two snapshots (names from snapshots_dir or file paths) object by object: only in a, "
+        "only in b, different. Without b, a is compared with the database itself. Exit 1 on differences.",
+        add_compare_arguments),
+]
+
+GROUPS = {
+    "setup": "setup",
+    "migrations": "migrations",
+    "drift": "drift (changes made by hand on the database)",
+    "compare": "comparing databases",
+}
+
+
+def overview() -> str:
+    """Every command with its summary, grouped, for the main help."""
+    width = max(len(f"{command.name} {command.usage}".strip()) for command in COMMANDS) + 2
+    lines = []
+    for group, title in GROUPS.items():
+        lines.append(f"{title}:")
+        for command in COMMANDS:
+            if command.group == group:
+                name_and_usage = f"{command.name} {command.usage}".strip()
+                lines.append(f"  {name_and_usage:<{width}}{command.summary}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def parser() -> argparse.ArgumentParser:
+    main_parser = argparse.ArgumentParser(
+        prog="pgl", usage="pgl [--env-file PATH] <command> [arguments]",
+        description=f"{INTRO}\n\n{overview()}\n{EXAMPLES}",
+        formatter_class=argparse.RawDescriptionHelpFormatter, add_help=False)
+    options = main_parser.add_argument_group("options")
+    options.add_argument("-h", "--help", action="help", help="show this help and exit")
+    options.add_argument("--version", action="version", version=f"postgresledger {__version__}")
+    options.add_argument("--config", metavar="PATH",
+                         help="postgresledger.toml to use (default: the one in the current folder)")
+    options.add_argument("--env-file", metavar="PATH",
+                         help="read DATABASE_* from this file (default: .env next to postgresledger.toml)")
+    subparsers = main_parser.add_subparsers(dest="cmd", required=True, metavar="<command>", help=argparse.SUPPRESS)
+    for command in COMMANDS:
+        command_parser = subparsers.add_parser(
+            command.name, help=command.summary,
+            description=f"{command.summary}.\n\n{textwrap.fill(command.details, 78)}",
+            formatter_class=argparse.RawDescriptionHelpFormatter)
+        command_function = getattr(commands, "cmd_" + command.name.replace("-", "_"))
+        command_parser.set_defaults(fn=command_function)
+        if command.add_arguments is not None:
+            command.add_arguments(command_parser)
+    return main_parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parser().parse_args(argv)
+    if args.cmd in NO_CONFIG:
+        sys.exit(args.fn(args) or 0)
+
+    config_file = Path(args.config) if args.config else Path(CONFIG_NAME)
+    env_file = Path(args.env_file) if args.env_file else None
+    cfg = Config(config_file, env_file)
+    if args.cmd in NO_DATABASE:
+        sys.exit(args.fn(cfg, args) or 0)
+
+    # every other command works on the one database: checked here, once
+    if cfg.target is None:
+        sys.exit(f"no DATABASE_NAME - set it in {relative(cfg.env_file)} or in the environment "
+                 "(with DATABASE_HOST, DATABASE_PORT, DATABASE_USER, DATABASE_PASSWORD)")
+    sys.exit(args.fn(cfg, cfg.target, args) or 0)
+
+
+if __name__ == "__main__":
+    main()

postgresledger/commands.py

@@ -0,0 +1,285 @@
+"""One function per `pgl` command. Every command works on one database: the DATABASE_* variables."""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from pathlib import Path
+
+from . import pgschema, scratch
+from .compare import compare
+from .config import CONFIG_NAME, Config, Connection, relative
+from .core import (
+    applied,
+    apply_file,
+    build_shadow,
+    check_checksums,
+    ensure_meta,
+    generate_migration,
+    list_migrations,
+    pgschema_dump,
+    pgschema_plan,
+    psql,
+    record_migration_sql,
+    require_up_to_date,
+)
+
+
+def config_file_text(folder: str) -> str:
+    """The postgresledger.toml `pgl init` writes, with every path inside `folder`."""
+    return f"""\
+# postgresledger project settings - the same for every database, committed to git.
+# Paths are relative to this file. The database itself is DATABASE_* in .env
+# (or in the environment), one database per run.
+
+[project]
+schema = "public"                                # schema managed by postgresledger
+schema_file = "{folder}/schema/schema.sql"          # desired state, the source of truth
+migrations_dir = "{folder}/migrations"
+snapshots_dir = "{folder}/snapshots"                # pgl snapshot <name> writes here
+meta_schema = "postgresledger"                         # tracking table: <meta_schema>.schema_migrations
+"""
+
+
+def dotenv_file_text(database: str) -> str:
+    """The .env `pgl init` writes: a local database called `database`."""
+    return f"""\
+# The database pgl works on. Never commit this file.
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_USER=postgres
+DATABASE_PASSWORD=postgres
+DATABASE_NAME={database}
+"""
+
+
+def database_name_from_folder(folder_name: str) -> str:
+    """The project folder name as a database name: lowercase letters, digits and _ ("My-App" -> "my_app")."""
+    allowed_characters = "abcdefghijklmnopqrstuvwxyz0123456789_"
+    database = ""
+    for character in folder_name.lower():
+        if character in allowed_characters:
+            database += character
+        elif not database.endswith("_"):
+            # a run of other characters becomes one _
+            database += "_"
+    return database.strip("_") or "app"
+
+
+def cmd_init(args) -> int:
+    root = Path.cwd()
+    config_file = root / CONFIG_NAME
+    if config_file.exists():
+        sys.exit(f"{CONFIG_NAME} already exists here")
+    for subfolder in ("schema", "migrations"):
+        (root / args.dir / subfolder).mkdir(parents=True, exist_ok=True)
+    (root / args.dir / "migrations" / ".gitkeep").touch()
+    config_file.write_text(config_file_text(args.dir))
+    created = [CONFIG_NAME, f"{args.dir}/schema/", f"{args.dir}/migrations/"]
+
+    dotenv_file = root / ".env"
+    if not dotenv_file.exists():
+        dotenv_file.write_text(dotenv_file_text(database_name_from_folder(root.name)))
+        created.append(".env")
+
+    gitignore = root / ".gitignore"
+    ignored = gitignore.read_text().splitlines() if gitignore.exists() else []
+    if ".env" not in ignored:
+        # start on a new line when the file does not end with one
+        needs_newline = bool(ignored) and ignored[-1] != ""
+        with gitignore.open("a") as gitignore_file:
+            gitignore_file.write(("\n" if needs_newline else "") + ".env\n")
+        created.append(".gitignore (.env)")
+
+    print(f"✔ created {', '.join(created)}")
+    exit_code = 0 if args.no_setup else pgschema.setup()
+    print(f"""
+next:
+  1. set the DATABASE_* variables in .env to your database
+  2. pgl baseline        snapshot it as the first migration
+     or write {args.dir}/schema/schema.sql and run `pgl new initial`""")
+    return exit_code
+
+
+def cmd_setup(args) -> int:
+    return pgschema.setup()
+
+
+def cmd_baseline(cfg: Config, connection: Connection, args) -> int:
+    migrations = list_migrations(cfg)
+    with scratch.server() as scratch_server:
+        if not migrations:
+            cfg.schema_file.parent.mkdir(parents=True, exist_ok=True)
+            print(f"- dump {connection.label} -> {relative(cfg.schema_file)}")
+            pgschema_dump(cfg, connection, cfg.schema_file)
+            baseline = generate_migration(cfg, scratch_server, "baseline", f"baseline taken from {connection.database}")
+            if baseline is None:
+                sys.exit("the database is empty, nothing to snapshot")
+            ensure_meta(cfg, connection)
+            psql(connection, record_migration_sql(cfg, baseline, "baseline"))
+            print(f"✔ {baseline.id} recorded on {connection.label} (baseline, not executed)")
+            return 0
+        # migrations exist: adopt a database that already has their schema
+        if applied(cfg, connection):
+            sys.exit(f"{connection.label} already tracks migrations - use `pgl apply`")
+        print(f"- building the state of {len(migrations)} migrations (scratch Postgres)")
+        shadow = build_shadow(cfg, scratch_server, migrations)
+        with tempfile.TemporaryDirectory() as temporary_dir:
+            actual = Path(temporary_dir) / "actual.sql"
+            pgschema_dump(cfg, connection, actual)
+            plan = pgschema_plan(cfg, shadow, actual, scratch_server)
+    if plan.sql:
+        print(f"✘ {connection.label} does not match the migrations, so they cannot be recorded as already there:\n")
+        print(plan.human)
+        print("\nempty database: `pgl apply` instead; otherwise align it first (see `pgl compare`)")
+        return 1
+    # every record in one transaction: all of them or none
+    records = [record_migration_sql(cfg, migration, "baseline") for migration in migrations]
+    psql(connection, "BEGIN;\n" + "\n".join(records) + "\nCOMMIT;")
+    print(f"✔ {connection.label} matches the migrations: {len(migrations)} recorded as baseline (not executed)")
+    return 0
+
+
+def cmd_new(cfg: Config, args) -> None:
+    with scratch.server() as scratch_server:
+        generate_migration(cfg, scratch_server, args.name, args.note or "change in schema.sql")
+
+
+def cmd_apply(cfg: Config, connection: Connection, args) -> None:
+    applied_by_version = applied(cfg, connection)
+    migrations = list_migrations(cfg)
+    check_checksums(connection, migrations, applied_by_version)
+    pending = [migration for migration in migrations if migration.version not in applied_by_version]
+    if not pending:
+        print(f"{connection.label}: all migrations are already applied")
+        return
+    for migration in pending:
+        if args.dry_run:
+            print(f"[dry-run] {connection.label}: would apply {migration.id}")
+            continue
+        print(f"- {connection.label}: applying {migration.id}")
+        apply_file(cfg, connection, migration)
+    if not args.dry_run:
+        print(f"✔ {connection.label}: applied {len(pending)} migration(s)")
+
+
+def cmd_status(cfg: Config, connection: Connection, args) -> None:
+    migrations = list_migrations(cfg)
+    applied_by_version = applied(cfg, connection)
+    width = max([len(migration.id) for migration in migrations] + [9])
+    print(f"{connection.label}\n")
+    print(f"{'migration':<{width}}  {'state':<9}  applied at")
+    pending_count = 0
+    for migration in migrations:
+        applied_migration = applied_by_version.get(migration.version)
+        if applied_migration is None:
+            pending_count += 1
+            print(f"{migration.id:<{width}}  {'PENDING':<9}")
+        else:
+            print(f"{migration.id:<{width}}  {applied_migration.mode:<9}  {applied_migration.applied_at}")
+    summary = f"\n{len(migrations) - pending_count} of {len(migrations)} applied"
+    if pending_count:
+        summary += f", {pending_count} pending - `pgl apply`"
+    print(summary)
+
+
+def cmd_drift(cfg: Config, connection: Connection, args) -> int:
+    """Changes made by hand: the database compared with the state of the migrations it has.
+
+    Migrations the database doesn't have yet are reported, not counted as drift.
+    """
+    applied_migrations = applied(cfg, connection)
+    all_migrations = list_migrations(cfg)
+    known_versions = {migration.version for migration in all_migrations}
+
+    unknown = [record for record in applied_migrations.values() if record.version not in known_versions]
+    if unknown:
+        names = ", ".join(f"{record.version}_{record.name}" for record in unknown)
+        sys.exit(f"{connection.label} has migrations that are not in the repository ({names}) - "
+                 "its expected state cannot be built")
+
+    has = [migration for migration in all_migrations if migration.version in applied_migrations]
+    pending = [migration for migration in all_migrations if migration.version not in applied_migrations]
+    if pending:
+        names = ", ".join(migration.id for migration in pending)
+        print(f"! {connection.label} does not have {len(pending)} migration(s) yet: {names} - `pgl apply`")
+        print(f"  comparing with the {len(has)} it has, so these are not counted as drift")
+
+    with scratch.server() as scratch_server:
+        print(f"- building the state of the {len(has)} migrations {connection.database} has (scratch Postgres)")
+        shadow = build_shadow(cfg, scratch_server, has)
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            actual = Path(tmp_dir) / "actual.sql"
+            pgschema_dump(cfg, connection, actual)
+            # "what turns the expected state into the actual database" = the manual changes
+            plan = pgschema_plan(cfg, shadow, actual, scratch_server)
+    if not plan.sql:
+        print(f"✔ {connection.label}: no drift, the database matches its migrations")
+        return 0
+    print(f"✘ {connection.label}: DRIFT - the database was changed outside of migrations:\n")
+    print(plan.human)
+    if pending:
+        print("\nrun `pgl apply` first, then keep or drop the changes:")
+    print("\nkeep the changes:   pgl capture <name>")
+    print("drop the changes:   undo them by hand (or with a new migration), then `pgl drift` again")
+    return 1
+
+
+def cmd_capture(cfg: Config, connection: Connection, args) -> None:
+    require_up_to_date(cfg, connection)
+    print(f"- dump {connection.label} -> {relative(cfg.schema_file)} (manual changes become the desired state)")
+    # put back when there is nothing to capture
+    schema_before = cfg.schema_file.read_text()
+    pgschema_dump(cfg, connection, cfg.schema_file)
+    note = f"manual changes captured from {connection.database} (recorded as captured there)"
+    with scratch.server() as scratch_server:
+        migration = generate_migration(cfg, scratch_server, args.name, note)
+    if migration is None:
+        cfg.schema_file.write_text(schema_before)
+        print(f"{connection.label}: no drift, nothing captured")
+        return
+    psql(connection, record_migration_sql(cfg, migration, "captured"))
+    print(f"✔ {migration.id} recorded on {connection.label} (captured, not executed) - "
+          "other databases get it with `pgl apply`")
+
+
+def is_valid_snapshot_name(name: str) -> bool:
+    """Letters, digits, _ . and - only, so the name is safe as a file name."""
+    allowed_characters = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.-")
+    return name != "" and set(name) <= allowed_characters
+
+
+def cmd_snapshot(cfg: Config, connection: Connection, args) -> None:
+    if not is_valid_snapshot_name(args.name):
+        sys.exit("snapshot name: letters, digits, _ . - only")
+    snapshot = cfg.snapshots_dir / f"{args.name}.sql"
+    pgschema_dump(cfg, connection, snapshot)
+    print(f"✔ {connection.label} -> {relative(snapshot)}")
+
+
+def snapshot_file(cfg: Config, name_or_path: str) -> Path:
+    """A snapshot given as a file path, or by name from snapshots_dir."""
+    for candidate in (Path(name_or_path), cfg.snapshots_dir / f"{name_or_path}.sql"):
+        if candidate.is_file():
+            return candidate
+    sys.exit(f"no snapshot '{name_or_path}' (neither a file nor {relative(cfg.snapshots_dir)}/{name_or_path}.sql) - "
+             f"`pgl snapshot {name_or_path}`")
+
+
+def cmd_compare(cfg: Config, args) -> int:
+    first_dump = snapshot_file(cfg, args.a).read_text()
+    if args.b:
+        second_dump = snapshot_file(cfg, args.b).read_text()
+        second_label = args.b
+    else:
+        # no second snapshot: compare with the database itself, dumped right now
+        if cfg.target is None:
+            sys.exit("comparing with the database needs DATABASE_NAME in .env - or give two snapshots")
+        with tempfile.TemporaryDirectory() as temporary_dir:
+            live_dump_file = Path(temporary_dir) / "live.sql"
+            pgschema_dump(cfg, cfg.target, live_dump_file)
+            second_dump = live_dump_file.read_text()
+        second_label = cfg.target.label
+    comparison = compare(first_dump, second_dump, args.a, second_label)
+    print(comparison.report)
+    return 1 if comparison.difference_count else 0

postgresledger/compare.py

@@ -0,0 +1,116 @@
+"""Differences between two schema dumps, object by object, without a database.
+
+pgschema writes every object as its own block under a header
+`-- Name: <name>; Type: <type>; Schema: ...`, in a stable order, so two dumps
+can be compared block by block.
+"""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass
+
+HEADER_START = "-- Name: "
+# lines around an object's SQL that are not part of it
+SEPARATOR_LINES = ("", "--")
+
+
+@dataclass(frozen=True, order=True)
+class SchemaObject:
+    """One object in a dump, e.g. TABLE customer. Sorted by type, then name."""
+
+    type: str
+    name: str
+
+
+def parse_header(line: str) -> SchemaObject | None:
+    """The object a `-- Name: <name>; Type: <type>; Schema: ...` line starts; None for any other line."""
+    if not line.startswith(HEADER_START):
+        return None
+    name, _, rest = line.removeprefix(HEADER_START).partition("; Type: ")
+    object_type, _, schema = rest.partition("; Schema:")
+    if not object_type or not schema:
+        return None
+    return SchemaObject(type=object_type, name=name)
+
+
+def strip_separator_lines(lines: list[str]) -> list[str]:
+    """`lines` without the empty and `--` lines at the start and the end."""
+    start = 0
+    end = len(lines)
+    while start < end and lines[start].strip() in SEPARATOR_LINES:
+        start += 1
+    while end > start and lines[end - 1].strip() in SEPARATOR_LINES:
+        end -= 1
+    return lines[start:end]
+
+
+def add_object(sql_by_object: dict[SchemaObject, str], schema_object: SchemaObject, lines: list[str]) -> None:
+    # same type and name twice (overloaded functions): the next ones become "name #2", "name #3", ...
+    unique_object = schema_object
+    number = 2
+    while unique_object in sql_by_object:
+        unique_object = SchemaObject(schema_object.type, f"{schema_object.name} #{number}")
+        number += 1
+    sql_by_object[unique_object] = "\n".join(strip_separator_lines(lines))
+
+
+def objects(dump: str) -> dict[SchemaObject, str]:
+    """The SQL of every object in a pgschema dump."""
+    sql_by_object: dict[SchemaObject, str] = {}
+    current_object = None
+    current_lines: list[str] = []
+    for line in dump.splitlines():
+        header_object = parse_header(line)
+        if header_object is not None:
+            if current_object is not None:
+                add_object(sql_by_object, current_object, current_lines)
+            current_object = header_object
+            current_lines = []
+        elif current_object is not None:
+            current_lines.append(line)
+    if current_object is not None:
+        add_object(sql_by_object, current_object, current_lines)
+    return sql_by_object
+
+
+@dataclass(frozen=True)
+class Comparison:
+    difference_count: int  # 0 when the dumps are identical
+    report: str  # readable, for the terminal
+
+
+def compare(first_dump: str, second_dump: str, first_label: str, second_label: str) -> Comparison:
+    first_objects = objects(first_dump)
+    second_objects = objects(second_dump)
+    only_in_first = sorted(item for item in first_objects if item not in second_objects)
+    only_in_second = sorted(item for item in second_objects if item not in first_objects)
+    changed = sorted(item for item in first_objects
+                     if item in second_objects and first_objects[item] != second_objects[item])
+    difference_count = len(only_in_first) + len(only_in_second) + len(changed)
+    # the type column is as wide as the longest type
+    width = max([len(item.type) for item in [*only_in_first, *only_in_second, *changed]] + [4])
+
+    report_lines = []
+    for title, missing_objects in [(f"only in {first_label}", only_in_first),
+                                   (f"only in {second_label}", only_in_second)]:
+        if missing_objects:
+            report_lines.append(f"{title} ({len(missing_objects)}):")
+            for item in missing_objects:
+                report_lines.append(f"  {item.type:<{width}}  {item.name}")
+            report_lines.append("")
+    if changed:
+        report_lines.append(f"different ({len(changed)}):")
+        for item in changed:
+            report_lines.append(f"  {item.type:<{width}}  {item.name}")
+            diff = difflib.unified_diff(first_objects[item].splitlines(), second_objects[item].splitlines(),
+                                        first_label, second_label, n=1, lineterm="")
+            for diff_line in diff:
+                report_lines.append(f"      {diff_line}")
+        report_lines.append("")
+    if difference_count:
+        report_lines.append(f"✘ {difference_count} difference(s) between {first_label} ({len(first_objects)} objects) "
+                            f"and {second_label} ({len(second_objects)} objects)")
+    else:
+        report_lines.append(f"✔ {first_label} and {second_label} are identical ({len(first_objects)} objects)")
+    return Comparison(difference_count=difference_count, report="\n".join(report_lines))