codepulse-engine 0.1.0__py3-none-any.whl

codepulse/storage/migrations.py

@@ -0,0 +1,347 @@
+"""
+Schema migrations: the Alembic plumbing, plus the safe `codepulse migrate` logic
+(CODEPULSE_FUTURE_CHANGES.md items 8 and 17 and finding K; user-approved 2026-10-14).
+
+The migration scripts live INSIDE the package (`codepulse/storage/schema_migrations/`)
+so they ship in a wheel, and the Alembic config is built in code instead of read from a
+repository-root `alembic.ini`, so none of this depends on the checkout or the current
+directory. (`alembic.ini` still exists for developers running `alembic upgrade head`
+from the repo root; it points at the same scripts.) Building the config without an
+ini file also means a migration run no longer applies the ini's logging section, which
+used to disable every logger that already existed and reset the root handlers.
+
+A database can be in one of these states (`get_schema_status`):
+  fresh      no tables yet (or no file): nothing to upgrade, `migrate` creates it at head
+  current    tracked by Alembic and at head
+  behind     tracked, at an older revision this CodePulse knows: `migrate` upgrades it
+  unstamped  has tables but was never tracked (created by `create_all`, as every
+             database CodePulse made before this change) AND its schema matches the
+             models, apart from tables it simply does not have yet (a database made
+             before a table existed, not opened by newer code since): `migrate`
+             creates those empty tables and stamps it at head
+  diverged   unstamped and its schema DIFFERS from the models in any other way (a
+             missing or extra column, an extra table -- e.g. a legacy table that a later
+             migration renames): stamping it would claim a schema it does not have, so
+             `migrate` refuses and says what differs
+  unknown    tracked, but at a revision this CodePulse does not have (a database from
+             a newer CodePulse): `migrate` refuses
+
+`migrate_database` never changes a database it refuses, takes a consistent backup of a
+SQLite file (the sqlite3 backup API, safe with a writer present) before it alters one,
+and verifies the result. Looking at a database (`get_schema_status`, `check=True`) never
+creates or changes it.
+"""
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+from alembic import command
+from alembic.autogenerate import compare_metadata
+from alembic.config import Config
+from alembic.runtime.migration import MigrationContext
+from alembic.script import ScriptDirectory
+from sqlalchemy import create_engine, inspect, text
+from sqlalchemy.engine import Engine, make_url
+from sqlalchemy.exc import IntegrityError
+
+from codepulse.config import get_settings
+from codepulse.storage.db import Base
+
+SCRIPT_LOCATION = Path(__file__).resolve().parent / "schema_migrations"
+
+# Structural differences that make an unstamped database unsafe to stamp. Index, constraint, type and
+# default differences between `create_all` and the migrations are deliberately NOT included: they do
+# not change what data the tables can hold.
+_STRUCTURAL_DIFFS = ("add_table", "remove_table", "add_column", "remove_column")
+
+
+class MigrationRefused(Exception):
+    """`migrate` will not change this database (diverged or from a newer CodePulse); nothing was touched."""
+
+
+def get_alembic_config(db_url: str | None = None) -> Config:
+    """
+    An Alembic `Config` built in code: the scripts are the packaged ones and no `alembic.ini` is needed.
+    """
+    cfg = Config()
+    cfg.set_main_option("script_location", str(SCRIPT_LOCATION))
+    # configparser treats % as interpolation; a percent-encoded URL would otherwise break.
+    cfg.set_main_option("sqlalchemy.url", (db_url or get_settings().db_url).replace("%", "%%"))
+    return cfg
+
+
+@lru_cache(maxsize=1)
+def head_revision() -> str:
+    """The newest revision this CodePulse knows (computed once per process)."""
+    head = ScriptDirectory.from_config(get_alembic_config("sqlite://")).get_current_head()
+    assert head, "no migration revisions found"
+    return head
+
+
+def run_migrations(db_url: str | None = None, revision: str = "head") -> None:
+    """Applies Alembic migrations up to the specified revision (default: head)."""
+    command.upgrade(get_alembic_config(db_url=db_url), revision)
+
+
+def stamp_database(db_url: str | None = None, revision: str = "head") -> None:
+    """
+    Stamps the database at the specified revision without running migration scripts.
+    Only correct for a database whose schema already matches that revision;
+    `migrate_database` checks that before it calls this.
+    """
+    command.stamp(get_alembic_config(db_url=db_url), revision)
+
+
+def downgrade_migrations(db_url: str | None = None, revision: str = "base") -> None:
+    """Downgrades Alembic migrations to the specified revision (default: base)."""
+    command.downgrade(get_alembic_config(db_url=db_url), revision)
+
+
+def get_current_revision(db_url: str | None = None) -> Optional[str]:
+    """The database's alembic_version revision, or None if it is not tracked (or does not exist)."""
+    target_url = db_url or get_settings().db_url
+    path = _sqlite_file(target_url)
+    if path is not None and not path.exists():
+        return None
+    engine = create_engine(target_url)
+    try:
+        if "alembic_version" not in inspect(engine).get_table_names():
+            return None
+        with engine.connect() as conn:
+            return conn.execute(text("SELECT version_num FROM alembic_version")).scalar()
+    finally:
+        engine.dispose()
+
+
+def stamp_new_database(engine: Engine) -> None:
+    """
+    Records head as the revision of a database that `StorageManager` has JUST created from scratch with
+    `create_all` (so its schema IS head). Before this, such a database was never tracked by Alembic and
+    could not be upgraded later. Safe if two processes create the same new database at once.
+    """
+    head = head_revision()
+    try:
+        with engine.begin() as conn:
+            conn.execute(text(
+                "CREATE TABLE IF NOT EXISTS alembic_version (version_num VARCHAR(32) NOT NULL, "
+                "CONSTRAINT alembic_version_pkc PRIMARY KEY (version_num))"
+            ))
+            if conn.execute(text("SELECT count(*) FROM alembic_version")).scalar() == 0:
+                conn.execute(text("INSERT INTO alembic_version (version_num) VALUES (:v)"), {"v": head})
+    except IntegrityError:
+        pass  # the other process stamped it first
+
+
+# --- status ------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class SchemaStatus:
+    state: str  # fresh | current | behind | unstamped | diverged | unknown
+    current: Optional[str]
+    head: str
+    pending: list[str] = field(default_factory=list)  # revisions `migrate` would apply, oldest first
+    differences: list[str] = field(default_factory=list)  # for diverged: what differs from the models
+    missing_tables: list[str] = field(default_factory=list)  # for unstamped: tables `migrate` will create
+    detail: str = ""
+
+    @property
+    def needs_action(self) -> bool:
+        return self.state in ("behind", "unstamped", "diverged", "unknown")
+
+
+def _sqlite_file(db_url: str) -> Optional[Path]:
+    url = make_url(db_url)
+    if url.get_backend_name() == "sqlite" and url.database and url.database != ":memory:":
+        return Path(url.database)
+    return None
+
+
+def _pending(current: str) -> list[str]:
+    script = ScriptDirectory.from_config(get_alembic_config("sqlite://"))
+    revisions = [rev.revision for rev in script.iterate_revisions(head_revision(), current)]
+    return [rev for rev in reversed(revisions) if rev != current]
+
+
+def _structural_differences(engine: Engine) -> tuple[list[str], list[str]]:
+    """
+    `(differences, missing_tables)`: what in the database does NOT match the models, split into things that
+    make it unsafe to stamp (`differences`) and tables that are merely absent (`missing_tables`). Creating an
+    absent empty table cannot conflict with existing data, so those alone do not block.
+    """
+    with engine.connect() as conn:
+        context = MigrationContext.configure(conn, opts={"compare_type": False, "compare_server_default": False})
+        diffs = compare_metadata(context, Base.metadata)
+    out: list[str] = []
+    missing: list[str] = []
+    for diff in diffs:
+        kind = diff[0]
+        if kind == "add_table":
+            missing.append(diff[1].name)
+        elif kind == "remove_table":
+            if diff[1].name != "alembic_version":
+                out.append(f"table {diff[1].name} is not in the models")
+        elif kind == "add_column":
+            out.append(f"column {diff[2]}.{diff[3].name} is missing")
+        elif kind == "remove_column":
+            out.append(f"column {diff[2]}.{diff[3].name} is not in the models")
+    return sorted(out), sorted(missing)
+
+
+def get_schema_status(db_url: str | None = None) -> SchemaStatus:
+    """Classifies the database (see the module docstring). Never creates or changes it."""
+    target_url = db_url or get_settings().db_url
+    head = head_revision()
+    path = _sqlite_file(target_url)
+    if path is not None and (not path.exists() or path.stat().st_size == 0):
+        return SchemaStatus("fresh", None, head, detail="no database yet")
+
+    engine = create_engine(target_url)
+    try:
+        tables = set(inspect(engine).get_table_names())
+        user_tables = tables - {"alembic_version"}
+        current = None
+        if "alembic_version" in tables:
+            with engine.connect() as conn:
+                current = conn.execute(text("SELECT version_num FROM alembic_version")).scalar() or None
+        if not user_tables:
+            return SchemaStatus("fresh", current, head, detail="no tables yet")
+        if current is not None:
+            if current == head:
+                return SchemaStatus("current", current, head, detail=f"at {head}")
+            known = {rev.revision for rev in ScriptDirectory.from_config(get_alembic_config("sqlite://")).walk_revisions()}
+            if current not in known:
+                return SchemaStatus(
+                    "unknown", current, head,
+                    detail=f"revision {current} is not known to this CodePulse (a database from a newer version?)",
+                )
+            pending = _pending(current)
+            return SchemaStatus("behind", current, head, pending, detail=f"at {current}, {len(pending)} revision(s) behind {head}")
+        differences, missing_tables = _structural_differences(engine)
+        if differences:
+            return SchemaStatus(
+                "diverged", None, head, differences=differences,
+                missing_tables=missing_tables,
+                detail="not tracked by Alembic and its schema differs from the models: "
+                + "; ".join(differences + [f"table {t} is missing" for t in missing_tables]),
+            )
+        if missing_tables:
+            return SchemaStatus(
+                "unstamped", None, head, missing_tables=missing_tables,
+                detail=f"not tracked by Alembic; its schema matches the models except for missing table(s) {', '.join(missing_tables)}, which migrate will create",
+            )
+        return SchemaStatus("unstamped", None, head, detail="not tracked by Alembic, but its schema matches the models")
+    finally:
+        engine.dispose()
+
+
+# --- migrate -----------------------------------------------------------------
+
+@dataclass(frozen=True)
+class MigrationResult:
+    action: str  # created | up-to-date | upgraded | stamped | needs-upgrade | needs-stamp | blocked
+    state: str
+    from_revision: Optional[str]
+    to_revision: Optional[str]
+    backup_path: Optional[str] = None
+    applied: list[str] = field(default_factory=list)
+    detail: str = ""
+
+
+def _backup_sqlite(path: Path, label: str) -> str:
+    """A consistent copy of a live SQLite database (the sqlite3 backup API, safe with a writer present)."""
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    dest = path.with_name(f"{path.name}.pre-{label}-{stamp}.bak")
+    counter = 1
+    while dest.exists():
+        counter += 1
+        dest = path.with_name(f"{path.name}.pre-{label}-{stamp}-{counter}.bak")
+    source = sqlite3.connect(str(path))
+    target = sqlite3.connect(str(dest))
+    try:
+        source.backup(target)
+    finally:
+        target.close()
+        source.close()
+    return str(dest)
+
+
+def _verify(db_url: str, backup_path: Optional[str]) -> None:
+    if get_current_revision(db_url) != head_revision():
+        raise RuntimeError(f"migration finished but the database is not at {head_revision()}" + _restore_hint(backup_path))
+    path = _sqlite_file(db_url)
+    if path is not None:
+        conn = sqlite3.connect(str(path))
+        try:
+            result = conn.execute("PRAGMA integrity_check").fetchone()[0]
+        finally:
+            conn.close()
+        if result != "ok":
+            raise RuntimeError(f"integrity check failed after migrating: {result}" + _restore_hint(backup_path))
+
+
+def _restore_hint(backup_path: Optional[str]) -> str:
+    return f" (a backup of the previous state is at {backup_path})" if backup_path else ""
+
+
+def migrate_database(db_url: str | None = None, *, backup: bool = True, check: bool = False) -> MigrationResult:
+    """
+    Brings the database to head, safely (see the module docstring for what each state does).
+
+    `check=True` only reports what would happen and never changes anything. Otherwise a `diverged` or
+    `unknown` database raises `MigrationRefused` and is left exactly as it was. A SQLite file is backed up
+    (unless `backup=False`) before it is upgraded or stamped; a database that did not exist has nothing to
+    back up.
+    """
+    target_url = db_url or get_settings().db_url
+    status = get_schema_status(target_url)
+    head = status.head
+    path = _sqlite_file(target_url)
+
+    if check:
+        action = {
+            "fresh": "up-to-date", "current": "up-to-date", "behind": "needs-upgrade",
+            "unstamped": "needs-stamp", "diverged": "blocked", "unknown": "blocked",
+        }[status.state]
+        return MigrationResult(action, status.state, status.current, head, applied=list(status.pending), detail=status.detail)
+
+    if status.state == "current":
+        return MigrationResult("up-to-date", "current", status.current, head, detail=status.detail)
+    if status.state in ("diverged", "unknown"):
+        raise MigrationRefused(
+            status.detail + ". Nothing was changed. "
+            + ("Back the file up and rebuild it by re-indexing, or migrate it by hand." if status.state == "diverged"
+               else "Upgrade CodePulse instead of migrating this database.")
+        )
+
+    backup_path: Optional[str] = None
+    if status.state == "fresh":
+        run_migrations(target_url)
+        _verify(target_url, None)
+        return MigrationResult("created", "fresh", None, head, applied=[head], detail="created the schema")
+
+    if backup and path is not None:
+        backup_path = _backup_sqlite(path, status.current or "unstamped")
+    if status.state == "behind":
+        run_migrations(target_url)
+        _verify(target_url, backup_path)
+        return MigrationResult("upgraded", "behind", status.current, head, backup_path, list(status.pending), f"upgraded {status.current} -> {head}")
+    # unstamped and matching the models, apart from tables it does not have yet
+    created: list[str] = []
+    if status.missing_tables:
+        engine = create_engine(target_url)
+        try:
+            Base.metadata.create_all(engine, tables=[Base.metadata.tables[name] for name in status.missing_tables])
+        finally:
+            engine.dispose()
+        created = list(status.missing_tables)
+    stamp_database(target_url)
+    _verify(target_url, backup_path)
+    detail = f"stamped at {head} (its schema matches the models)"
+    if created:
+        detail = f"created missing table(s) {', '.join(created)} and stamped at {head}"
+    return MigrationResult("stamped", "unstamped", None, head, backup_path, [], detail)

codepulse/storage/schema_migrations/README

@@ -0,0 +1 @@
+Generic single-database configuration.

codepulse/storage/schema_migrations/env.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from logging.config import fileConfig
+from sqlalchemy import engine_from_config, pool
+from alembic import context
+
+from codepulse.config import get_settings
+from codepulse.storage.db import Base
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Model metadata for autogenerate support
+target_metadata = Base.metadata
+
+
+def get_db_url() -> str:
+    """Returns the database URL from config file option, or defaults to CodePulseConfig."""
+    url = config.get_main_option("sqlalchemy.url")
+    if not url or url.strip() == "" or url == "driver://user:pass@localhost/dbname":
+        url = get_settings().db_url
+    return url
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = get_db_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        render_as_batch=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    configuration = config.get_section(config.config_ini_section, {})
+    configuration["sqlalchemy.url"] = get_db_url()
+
+    connectable = engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            render_as_batch=True,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

codepulse/storage/schema_migrations/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

codepulse/storage/schema_migrations/versions/135a7b064ea7_add_base_classes_and_relationship_type.py

@@ -0,0 +1,82 @@
+"""add_base_classes_and_relationship_type
+
+Revision ID: 135a7b064ea7
+Revises: 2cd38eb12a7e
+Create Date: 2026-09-19 00:00:00.000000
+
+Phase 4.1 (roadmap §37 item 4.1: "Base-class/inheritance extraction
+(Python + JS/TS)"; §29 Data Model: "Symbol | Yes (exists, needs upsert
+key + base-class field) | Core"). Architecture approved explicitly by
+the user before implementation (see CODEPULSE_PROGRESS.md): raw
+base-class text lives on `Symbol`/`symbols`; resolved inheritance
+relationships are persisted as `CallEdge`/`call_edges` rows,
+distinguished from ordinary call edges by a new `relationship_type`
+column, reusing that table's existing `repo_id` scoping, `confidence`
+vocabulary, and Phase 3.5 incremental-update machinery rather than
+introducing a second persistence mechanism.
+
+This migration is purely additive and non-destructive:
+
+  1. Adds `symbols.base_classes` (nullable `TEXT`, JSON-serialized
+     `list[str]`, the same "Text column holding a JSON-serialized list,
+     parsed in application code" convention `EmbeddingModel.
+     embedding_json` already uses -- not a new serialization approach).
+     `NULL` for every existing row (none of them were ever asked for
+     this data before this migration existed -- not a guess, an honest
+     absence, exactly like `confidence`'s own precedent in
+     `f6e481353553`) and for every non-CLASS symbol going forward.
+     Every existing row's `id`/`name`/`start_line`/`body_hash`/etc. is
+     untouched.
+
+  2. Adds `call_edges.relationship_type` (`VARCHAR(20)`, `NOT NULL`,
+     `DEFAULT 'calls'`). Every one of this table's existing rows is
+     UNAMBIGUOUSLY a call -- nothing else has ever been written to it
+     (confirmed: no code path existed to write anything else before
+     this migration) -- so `'calls'` is the correct backfill for every
+     existing row, not a guess in the way `confidence`'s or `repo_id`'s
+     own backfills had to be conservative about ambiguity. SQLite
+     applies the column default to every existing row automatically
+     when a `NOT NULL DEFAULT` column is added.
+
+Both additions use Alembic "batch" mode (SQLite table-rebuild-under-
+the-hood), matching every prior column-addition migration in this
+project's history, even though a plain `ALTER TABLE ADD COLUMN` with a
+constant default would likely work directly here -- consistency with
+established migration style, not a functional requirement.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '135a7b064ea7'
+down_revision: Union[str, Sequence[str], None] = '2cd38eb12a7e'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    with op.batch_alter_table('symbols', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('base_classes', sa.Text(), nullable=True))
+
+    with op.batch_alter_table('call_edges', schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column(
+                'relationship_type',
+                sa.String(length=20),
+                nullable=False,
+                server_default='calls',
+            )
+        )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    with op.batch_alter_table('call_edges', schema=None) as batch_op:
+        batch_op.drop_column('relationship_type')
+
+    with op.batch_alter_table('symbols', schema=None) as batch_op:
+        batch_op.drop_column('base_classes')

codepulse/storage/schema_migrations/versions/20fc2d0607e2_add_file_content_hash_and_natural_key_.py

@@ -0,0 +1,106 @@
+"""add_file_content_hash_and_natural_key_uniqueness
+
+Revision ID: 20fc2d0607e2
+Revises: 21a7cb7f1a85
+Create Date: 2026-09-05 12:55:39.151635
+
+Phase 0.3 (Repository/File upsert with content_hash).
+
+This migration is additive and non-destructive:
+
+  - Adds `files.content_hash` (nullable). Existing File rows predate content
+    hashing and only ever stored path/language/size/line-count metadata --
+    the actual source bytes that were indexed were never persisted anywhere
+    in the database (Symbol.body only stores per-symbol snippets, not whole
+    files), so there is no reliable, non-fabricated way to compute a
+    historically-accurate hash for pre-existing rows during this migration.
+    Per the Phase 0.3 spec, we do NOT invent/backfill a value for them --
+    `content_hash` is left NULL for rows that predate this migration. Each
+    such row gets a real, accurate content_hash automatically the next time
+    its file is re-indexed by the application (see
+    IndexingEngine._persist_to_db), at which point the current on-disk
+    content is genuinely available to hash.
+
+  - Adds a UNIQUE constraint on `files(repo_id, path)` and on
+    `repositories(url)`, enforcing the natural-key invariants the Phase 0.3
+    upsert logic depends on. A pre-flight check aborts the migration (rather
+    than failing partway through a batch table-recreate, or silently
+    accepting an inconsistent state) if any pre-existing duplicate rows
+    would violate these constraints.
+
+No table is dropped or recreated destructively and no existing row is
+deleted or overwritten. SQLAlchemy/Alembic "batch" mode is used because
+SQLite requires a copy-and-swap under the hood to add a constraint to an
+existing table -- all existing rows and columns are carried over unchanged
+by that process.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '20fc2d0607e2'
+down_revision: Union[str, Sequence[str], None] = '21a7cb7f1a85'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _assert_no_duplicates() -> None:
+    """
+    Pre-flight safety check: refuse to add the UNIQUE constraints if any
+    pre-existing data would violate them, rather than letting the batch
+    table-recreate fail halfway (or, on backends that don't error the same
+    way, silently accepting an inconsistent state).
+    """
+    bind = op.get_bind()
+
+    dup_repo_urls = bind.execute(
+        sa.text(
+            "SELECT url, COUNT(*) AS c FROM repositories "
+            "GROUP BY url HAVING COUNT(*) > 1"
+        )
+    ).fetchall()
+    if dup_repo_urls:
+        raise RuntimeError(
+            "Cannot add UNIQUE constraint on repositories.url: duplicate "
+            f"url values already exist: {[row[0] for row in dup_repo_urls]}. "
+            "Resolve duplicate Repository rows before applying this migration."
+        )
+
+    dup_files = bind.execute(
+        sa.text(
+            "SELECT repo_id, path, COUNT(*) AS c FROM files "
+            "GROUP BY repo_id, path HAVING COUNT(*) > 1"
+        )
+    ).fetchall()
+    if dup_files:
+        raise RuntimeError(
+            "Cannot add UNIQUE constraint on files(repo_id, path): duplicate "
+            f"(repo_id, path) pairs already exist: "
+            f"{[(row[0], row[1]) for row in dup_files]}. Resolve duplicate "
+            "File rows before applying this migration."
+        )
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    _assert_no_duplicates()
+
+    with op.batch_alter_table("files", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("content_hash", sa.String(length=64), nullable=True))
+        batch_op.create_unique_constraint("uq_files_repo_id_path", ["repo_id", "path"])
+
+    with op.batch_alter_table("repositories", schema=None) as batch_op:
+        batch_op.create_unique_constraint("uq_repositories_url", ["url"])
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    with op.batch_alter_table("repositories", schema=None) as batch_op:
+        batch_op.drop_constraint("uq_repositories_url", type_="unique")
+
+    with op.batch_alter_table("files", schema=None) as batch_op:
+        batch_op.drop_constraint("uq_files_repo_id_path", type_="unique")
+        batch_op.drop_column("content_hash")