sqlmirror 0.2.0__tar.gz

sqlmirror-0.2.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: sqlmirror
+Version: 0.2.0
+Summary: Mirror Jira Cloud into your own Postgres or SQL Server under Data Center table names
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.28
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: sqlglot>=25
+Provides-Extra: sqlserver
+Requires-Dist: python-tds>=1.15; extra == "sqlserver"
+Requires-Dist: pyOpenSSL>=23; extra == "sqlserver"
+Requires-Dist: certifi; extra == "sqlserver"
+Provides-Extra: dev
+Requires-Dist: moto[server]>=5; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: python-tds>=1.15; extra == "dev"

sqlmirror-0.2.0/README.md

@@ -0,0 +1,26 @@
+# sqlmirror CLI
+
+```bash
+pip install -e ".[dev]"            # from this folder
+pip install -e ".[sqlserver]"      # to write to SQL Server / Azure SQL as well
+sqlmirror --help
+```
+
+The database is chosen by `DATABASE_URL`: `postgresql://user:pass@host:5432/db` or `sqlserver://user:pass@host:1433/db` (`?encrypt=true` for Azure SQL). See TESTING.md part 4 for SQL Server options.
+
+| Command | Does |
+|---|---|
+| `sqlmirror init-db` | Create the Data-Center-compatible tables in `$DATABASE_URL` (Postgres or SQL Server). |
+| `sqlmirror ddl [--dialect sqlserver]` | Print the CREATE TABLE statements, for a DBA to run. |
+| `sqlmirror backfill [--project KEY] [--resume]` | Load everything with your API token (runs on your machine, uses your own rate limit). |
+| `sqlmirror apply s3://bucket/prefix [--watch \| --cron "*/15 * * * *"]` | Load the Forge app's change files, once, continuously, or on a cron schedule (UTC). Safe to run repeatedly; files are tracked individually. |
+| `sqlmirror reconcile [--deep] [--repair]` | Compare counts (or every id and updated time) with Jira; `--repair` fixes differences. |
+| `sqlmirror status` | Counts and freshness. |
+| `sqlmirror log [--app]` | Recent apply / backfill runs; with `--app`, the Forge app's sync jobs and which issues each changed. |
+| `sqlmirror check-sql reports/ --dialect sqlserver [--target sqlserver] [--id-map id_map.csv]` | Check Data Center report SQL against the mirror, rewrite it for the mirror's database, compile the result there. |
+| `sqlmirror idmap export-sql --dialect sqlserver` | Query to run on the Data Center database to export id/name pairs. |
+| `sqlmirror idmap build dc_export.csv` | Match those to Cloud ids by name, write `id_map.csv`. |
+
+Test tools (`sqlmirror-dev`): `e2e`, `golden`, `compare`, `synth`, `mock-jira`, and for demo sites only: `load-site`, `simulate-edits`, `bulk-edit`.
+
+Tests: `pytest -q` (needs Postgres at `$SQLMIRROR_TEST_SERVER_DSN`; the pipeline test also needs Node and `npm install` in `../sql-mirror`; the SQL Server tests run when `$SQLMIRROR_TEST_MSSQL_DSN` is set and are otherwise skipped).

sqlmirror-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlmirror"
+version = "0.2.0"
+description = "Mirror Jira Cloud into your own Postgres or SQL Server under Data Center table names"
+requires-python = ">=3.10"
+dependencies = [
+  "boto3>=1.28",
+  "click>=8.1",
+  "httpx>=0.27",
+  "psycopg[binary]>=3.2",
+  "python-dotenv>=1.0",
+  "sqlglot>=25",
+]
+
+[project.optional-dependencies]
+# SQL Server / Azure SQL output. python-tds is pure Python (no ODBC driver);
+# pyOpenSSL is needed for encrypted connections (Azure SQL), certifi for its CA list.
+sqlserver = [
+  "python-tds>=1.15",
+  "pyOpenSSL>=23",
+  "certifi",
+]
+dev = [
+  "moto[server]>=5",
+  "pytest>=8",
+  "python-tds>=1.15",
+]
+
+[project.scripts]
+sqlmirror = "sqlmirror.cli:main"
+sqlmirror-dev = "sqlmirror.dev.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["sqlmirror*"]
+
+[tool.setuptools.package-data]
+sqlmirror = ["golden/*.sql", "golden/tsql/*.sql", "samples/*.csv", "samples/dc_reports/*.sql"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: end-to-end tests that need Node and the Forge app's npm packages"]

sqlmirror-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqlmirror-0.2.0/sqlmirror/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

sqlmirror-0.2.0/sqlmirror/apply.py

@@ -0,0 +1,136 @@
+"""Load change files written by the Forge app into the mirror database."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Callable
+
+from .cron import Cron
+from .db import ApplyStats, Mirror
+from .util import utcnow
+from .mapper import Mapper
+from .source import Source, parse_records
+
+# How far back to re-list files on each run. Files that land late (a slow
+# writer, clock skew) are still picked up because applied files are tracked
+# individually rather than by a single high-water mark.
+LOOKBACK = timedelta(days=1)
+
+
+class LicenseError(RuntimeError):
+    pass
+
+
+@dataclass
+class ApplyResult:
+    files: int
+    metadata_files: int
+    stats: ApplyStats
+
+
+def _day_key(source: Source, sub: str, last_key: str | None) -> str | None:
+    """Start listing one day before the newest applied file."""
+    if not last_key:
+        return None
+    rest = last_key[len(source.key(sub)):] if last_key.startswith(source.key(sub)) else ""
+    parts = rest.split("/")
+    try:
+        day = datetime(int(parts[0]), int(parts[1]), int(parts[2]))
+    except (ValueError, IndexError):
+        return None
+    start = day - LOOKBACK
+    return source.key(f"{sub}{start:%Y/%m/%d}/")
+
+
+def check_license(source: Source, log: Callable[[str], None]) -> None:
+    status = source.status()
+    if status is None:
+        log("Note: no app status file in the bucket yet (_sqlmirror/status.json).")
+        return
+    lic = status.get("license") or {}
+    if lic.get("active") is False:
+        raise LicenseError(
+            f"The SQL Mirror app on {status.get('site', 'your site')} reports an inactive license. "
+            "Renew it in Jira (Apps > Manage apps) to continue applying changes."
+        )
+
+
+def apply_once(source: Source, db: Mirror, mapper: Mapper, *, log: Callable[[str], None] = print,
+               verbose: bool = False) -> ApplyResult:
+    db.load_registry(mapper)
+    check_license(source, log)
+    stats = ApplyStats()
+
+    # Metadata first, so new custom fields are known before issues reference them.
+    last_meta = db.last_applied_file(source.key("metadata/"))
+    meta_keys = list(source.list("metadata/", _day_key(source, "metadata/", last_meta)))
+    new_meta = [k for k in meta_keys if k not in db.applied_files(meta_keys)]
+    if new_meta:
+        newest = new_meta[-1]
+        raw = source.read(newest)
+        if raw is not None:
+            for rec in parse_records(newest, raw):
+                if rec.get("type") == "metadata":
+                    db.apply_metadata(mapper, rec)
+        for k in new_meta:
+            db.mark_file_applied(k, 1 if k == newest else 0)
+        db.conn.commit()
+        if verbose:
+            log(f"Applied metadata {newest}")
+
+    last_issue = db.last_applied_file(source.key("issues/"))
+    keys = list(source.list("issues/", _day_key(source, "issues/", last_issue)))
+    applied = db.applied_files(keys)
+    todo = [k for k in keys if k not in applied]
+    for k in todo:
+        raw = source.read(k)
+        if raw is None:
+            continue
+        records = parse_records(k, raw)
+        file_stats = db.apply_records(mapper, records, source="forge")
+        db.mark_file_applied(k, len(records))
+        db.conn.commit()
+        stats.add(file_stats)
+        if verbose:
+            log(f"{k}: {file_stats.summary()}")
+    return ApplyResult(files=len(todo), metadata_files=len(new_meta), stats=stats)
+
+
+def apply_logged(source: Source, db: Mirror, mapper: Mapper, *, log: Callable[[str], None] = print,
+                 verbose: bool = False) -> ApplyResult:
+    """apply_once plus a row in sqlmirror_sync_log (also on failure)."""
+    started = utcnow()
+    try:
+        res = apply_once(source, db, mapper, log=log, verbose=verbose)
+    except Exception as exc:
+        db.log_run("apply", source.describe(), started, error=str(exc)[:1000])
+        raise
+    if res.files or res.metadata_files:
+        db.log_run("apply", source.describe(), started, files=res.files + res.metadata_files, stats=res.stats)
+    return res
+
+
+def apply_loop(source: Source, db: Mirror, mapper: Mapper, *, interval: int = 60, cron: str | None = None,
+               log: Callable[[str], None] = print, verbose: bool = False) -> None:
+    """Keep applying new files: every `interval` seconds, or on a cron schedule (UTC)."""
+    schedule = Cron.parse(cron) if cron else None
+    if schedule:
+        log(f"Watching {source.describe()} on schedule '{cron}' (UTC). Next run {schedule.next_after(utcnow()):%Y-%m-%d %H:%M} UTC. "
+            "Press Ctrl+C to stop.")
+    else:
+        log(f"Watching {source.describe()} every {interval}s. Press Ctrl+C to stop.")
+    while True:
+        if schedule:
+            wait = (schedule.next_after(utcnow()) - utcnow()).total_seconds()
+            time.sleep(max(0.0, wait))
+        try:
+            res = apply_logged(source, db, mapper, log=log, verbose=verbose)
+            if res.files or res.metadata_files:
+                log(f"{time.strftime('%H:%M:%S')} applied {res.files} files: {res.stats.summary()}")
+        except LicenseError as exc:
+            log(str(exc))
+        except Exception as exc:  # keep watching; the failure is in the sync log
+            log(f"{time.strftime('%H:%M:%S')} apply failed: {exc}")
+        if not schedule:
+            time.sleep(interval)

sqlmirror-0.2.0/sqlmirror/backfill.py

@@ -0,0 +1,65 @@
+"""Initial load: read every issue with the customer's API token and write the mirror.
+
+Runs on the customer's machine. Uses the customer's own Jira rate limit, not
+the Forge app's shared pool, so a 50k-issue history never starves the app's
+incremental sync.
+"""
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Callable
+
+from .db import ApplyStats, Mirror
+from .jira import JiraClient
+from .mapper import Mapper
+from .util import iso, utcnow
+
+
+def _jql_quote(key: str) -> str:
+    return '"' + key.replace('"', '\\"') + '"'
+
+
+def backfill(client: JiraClient, db: Mirror, mapper: Mapper, *, projects: list[str] | None = None,
+             resume: bool = False, workers: int = 4, page_size: int = 100,
+             log: Callable[[str], None] = print) -> ApplyStats:
+    started = time.time()
+    db.load_registry(mapper)
+    log("Fetching configuration (projects, statuses, fields, versions, components)...")
+    meta = client.metadata()
+    db.apply_metadata(mapper, meta)
+    all_keys = [p["key"] for p in meta.get("projects", [])]
+    keys = [k for k in all_keys if not projects or k in {p.upper() for p in projects}]
+    missing = sorted({p.upper() for p in projects or []} - set(all_keys))
+    if missing:
+        log(f"Warning: projects not visible to this token: {', '.join(missing)}")
+    log(f"{len(meta.get('projects', []))} projects, {len(meta.get('fields', []))} fields. "
+        f"Mirroring: {', '.join(keys) or 'none'}")
+
+    total = ApplyStats()
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        for key in keys:
+            last_id = db.get_meta(f"backfill:{key}:last_id") if resume else None
+            jql = f"project = {_jql_quote(key)}"
+            if last_id:
+                jql += f" AND id > {int(last_id)}"
+            jql += " ORDER BY id ASC"
+            approx = client.approximate_count(f"project = {_jql_quote(key)}")
+            log(f"[{key}] {approx if approx is not None else '?'} issues" + (f", resuming after id {last_id}" if last_id else ""))
+            done = 0
+            fetched_at = iso(utcnow())
+            for page in client.search(jql, fields=["*all"], expand="changelog", page_size=page_size):
+                snapshots = list(pool.map(lambda i: client.complete_snapshot(i, fetched_at), page))
+                stats = db.apply_records(mapper, snapshots, source="backfill")
+                total.add(stats)
+                done += len(page)
+                db.set_meta(f"backfill:{key}:last_id", str(max(int(i["id"]) for i in page)))
+                db.conn.commit()
+                log(f"[{key}] {done} issues mirrored")
+                fetched_at = iso(utcnow())
+            db.set_meta(f"backfill:{key}:completed_at", iso(utcnow()))
+            db.conn.commit()
+    db.set_meta("backfill_completed_at", iso(utcnow()))
+    db.conn.commit()
+    log(f"Backfill finished in {time.time() - started:.0f}s: {total.summary()}. {client.api_call_summary()}.")
+    return total

sqlmirror-0.2.0/sqlmirror/cli.py

@@ -0,0 +1,335 @@
+"""sqlmirror: keep a Data-Center-compatible copy of Jira Cloud in your own Postgres or SQL Server.
+
+Settings come from flags, environment variables, or a .env file in the
+current folder:
+
+  DATABASE_URL     postgresql://user:password@host:5432/dbname
+                   or sqlserver://user:password@host:1433/dbname (add ?encrypt=true for Azure SQL)
+  JIRA_SITE        https://your-site.atlassian.net
+  JIRA_EMAIL       the account that owns the API token
+  JIRA_API_TOKEN   an API token; it never leaves this machine
+  SQLMIRROR_SOURCE s3://bucket/prefix written by the Forge app (or a local folder)
+  SQLMIRROR_S3_ENDPOINT, AWS_PROFILE / AWS_* credentials for reading the bucket
+"""
+from __future__ import annotations
+
+import csv
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from . import __version__
+
+
+def _env(name: str) -> str | None:
+    v = os.environ.get(name)
+    return v.strip() if v else None
+
+
+def _db(dsn: str | None, schema: str | None):
+    from .db import open_mirror
+
+    dsn = dsn or _env("DATABASE_URL")
+    if not dsn:
+        raise click.UsageError("Set DATABASE_URL or pass --dsn postgresql://user:pass@host/db "
+                               "(or sqlserver://user:pass@host:1433/db)")
+    return open_mirror(dsn, schema=schema or _env("SQLMIRROR_SCHEMA"))
+
+
+def _jira(verbose: bool = False):
+    from .jira import JiraClient
+
+    site, email = _env("JIRA_SITE"), _env("JIRA_EMAIL")
+    token = _env("JIRA_API_TOKEN") or _env("ATLASSIAN_API_TOKEN") or _env("ATLASSIAN_API")
+    missing = [n for n, v in (("JIRA_SITE", site), ("JIRA_EMAIL", email), ("JIRA_API_TOKEN", token)) if not v]
+    if missing:
+        raise click.UsageError(f"Set {', '.join(missing)} (environment or .env). Create a token at "
+                               "https://id.atlassian.com/manage-profile/security/api-tokens")
+    return JiraClient(site, email, token, verbose=verbose)
+
+
+def _source(location: str | None, endpoint: str | None, region: str | None, profile: str | None):
+    from .source import open_source
+
+    location = location or _env("SQLMIRROR_SOURCE")
+    if not location:
+        raise click.UsageError("Give the bucket as s3://bucket/prefix (or set SQLMIRROR_SOURCE).")
+    kwargs = {}
+    if location.startswith("s3://"):
+        kwargs = {"endpoint_url": endpoint or _env("SQLMIRROR_S3_ENDPOINT"), "region": region or _env("AWS_REGION"),
+                  "profile": profile or _env("AWS_PROFILE")}
+    return open_source(location, **kwargs)
+
+
+dsn_option = click.option("--dsn", help="postgresql://... or sqlserver://... connection string (default: $DATABASE_URL).")
+schema_option = click.option("--schema", help="Schema for the mirror tables (default: public on Postgres, dbo on SQL Server; "
+                                              "on SQL Server prefer a separate database).")
+
+
+@click.group()
+@click.version_option(__version__)
+@click.option("--env-file", type=click.Path(dir_okay=False), help="Read settings from this file (default: ./.env).")
+def main(env_file: str | None) -> None:
+    """Mirror Jira Cloud into your own Postgres or SQL Server under Data Center table names."""
+    load_dotenv(env_file or Path.cwd() / ".env", override=False)
+
+
+# ------------------------------------------------------------------- setup
+@main.command("init-db")
+@dsn_option
+@schema_option
+def init_db(dsn: str | None, schema: str | None) -> None:
+    """Create the mirror tables (safe to run again)."""
+    db = _db(dsn, schema)
+    db.init_schema()
+    click.echo("Mirror tables are ready.")
+
+
+@main.command("ddl")
+@click.option("--dialect", default=None, help="postgres or sqlserver (default: from $DATABASE_URL, else postgres).")
+@schema_option
+def print_ddl(dialect: str | None, schema: str | None) -> None:
+    """Print the CREATE TABLE statements (for a DBA to run, if sqlmirror may not create tables)."""
+    from .db import is_sqlserver_dsn
+    from .schema import ddl
+
+    if not dialect:
+        dialect = "sqlserver" if is_sqlserver_dsn(_env("DATABASE_URL") or "") else "postgres"
+    try:
+        click.echo(ddl(dialect, schema or _env("SQLMIRROR_SCHEMA")))
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--dialect")
+
+
+@main.command("check-jira")
+def check_jira() -> None:
+    """Check the Jira token works and show what it can see."""
+    client = _jira()
+    me = client.myself()
+    click.echo(f"Signed in to {client.site} as {me.get('displayName')} ({me.get('accountId')}).")
+    projects = list(client.paged_values("/rest/api/2/project/search", 50))
+    click.echo(f"{len(projects)} projects visible: {', '.join(p['key'] for p in projects[:20])}"
+               + (" ..." if len(projects) > 20 else ""))
+
+
+# ------------------------------------------------------------------- sync
+@main.command()
+@dsn_option
+@schema_option
+@click.option("--project", "projects", multiple=True, help="Project key to mirror; repeat for more. Default: all.")
+@click.option("--resume", is_flag=True, help="Continue an interrupted backfill instead of starting over.")
+@click.option("--workers", default=4, show_default=True, help="Parallel requests for long histories.")
+@click.option("--verbose", is_flag=True)
+def backfill(dsn, schema, projects, resume, workers, verbose) -> None:
+    """Load all issues and history with your own API token (run once)."""
+    from .backfill import backfill as run
+    from .mapper import Mapper
+
+    from .util import utcnow
+
+    db = _db(dsn, schema)
+    db.init_schema()
+    started = utcnow()
+    try:
+        stats = run(_jira(verbose), db, Mapper(), projects=list(projects) or None, resume=resume, workers=workers)
+    except Exception as exc:
+        db.log_run("backfill", ",".join(projects) or "all projects", started, error=str(exc)[:1000])
+        raise
+    db.log_run("backfill", ",".join(projects) or "all projects", started, stats=stats)
+
+
+@main.command()
+@click.argument("source", required=False)
+@dsn_option
+@schema_option
+@click.option("--endpoint-url", help="S3-compatible endpoint (R2, GCS, MinIO). Default: AWS.")
+@click.option("--region", help="Bucket region.")
+@click.option("--profile", help="AWS profile to read the bucket with.")
+@click.option("--watch", is_flag=True, help="Keep running and apply new files as they arrive.")
+@click.option("--interval", default=60, show_default=True, help="Seconds between checks with --watch.")
+@click.option("--cron", "cron_expr", help='Run on a cron schedule in UTC instead, e.g. "*/15 * * * *" (implies --watch).')
+@click.option("--verbose", is_flag=True)
+def apply(source, dsn, schema, endpoint_url, region, profile, watch, interval, cron_expr, verbose) -> None:
+    """Apply change files written by the Forge app (s3://bucket/prefix or a folder)."""
+    from .apply import LicenseError, apply_logged, apply_loop
+    from .cron import Cron, CronError
+    from .mapper import Mapper
+
+    if cron_expr:
+        try:
+            Cron.parse(cron_expr)
+        except CronError as exc:
+            raise click.BadParameter(str(exc), param_hint="--cron")
+    src = _source(source, endpoint_url, region, profile)
+    db = _db(dsn, schema)
+    db.init_schema()
+    if watch or cron_expr:
+        apply_loop(src, db, Mapper(), interval=interval, cron=cron_expr, verbose=verbose)
+        return
+    try:
+        res = apply_logged(src, db, Mapper(), verbose=verbose)
+    except LicenseError as exc:
+        raise click.ClickException(str(exc))
+    click.echo(f"Applied {res.files} change files and {res.metadata_files} configuration files from "
+               f"{src.describe()}: {res.stats.summary()}.")
+
+
+@main.command()
+@dsn_option
+@schema_option
+@click.option("--project", "projects", multiple=True)
+@click.option("--deep", is_flag=True, help="Compare every issue id and updated time, not just counts.")
+@click.option("--repair", is_flag=True, help="Re-fetch missing or stale issues and remove deleted ones.")
+def reconcile(dsn, schema, projects, deep, repair) -> None:
+    """Compare the mirror with Jira (uses your API token)."""
+    from .mapper import Mapper
+    from .reconcile import format_reports, reconcile as run
+
+    reports = run(_jira(), _db(dsn, schema), Mapper(), projects=list(projects) or None, deep=deep or repair,
+                  repair=repair)
+    click.echo(format_reports(reports, deep or repair))
+    if not all(r.ok if (deep or repair) else r.jira == r.mirror for r in reports):
+        sys.exit(1)
+
+
+@main.command()
+@dsn_option
+@schema_option
+@click.option("--source", help="Also show the app status file from this bucket.")
+@click.option("--endpoint-url")
+@click.option("--region")
+@click.option("--profile")
+def status(dsn, schema, source, endpoint_url, region, profile) -> None:
+    """Show what is in the mirror and how fresh it is."""
+    db = _db(dsn, schema)
+    counts = db.table_counts()
+    applied_at, fetched_at = db.freshness()
+    click.echo(f"Issues: {counts['jiraissue']}  changes: {counts['changeitem']}  comments: {counts['jiraaction']}  "
+               f"worklogs: {counts['worklog']}  custom field values: {counts['customfieldvalue']}")
+    click.echo(f"Projects: {', '.join(f'{k} ({v})' for k, v in db.project_counts().items())}")
+    click.echo(f"Newest data fetched from Jira: {fetched_at}; last write: {applied_at}")
+    click.echo(f"Last change file applied: {db.last_applied_file() or 'none'}")
+    click.echo(f"Configuration fetched: {db.get_meta('metadata_fetched_at') or 'never'}; "
+               f"backfill finished: {db.get_meta('backfill_completed_at') or 'never'}")
+    if source or _env("SQLMIRROR_SOURCE"):
+        st = _source(source, endpoint_url, region, profile).status()
+        click.echo("App status: " + (json.dumps(st, indent=2) if st else "no status file yet"))
+
+
+@main.command("log")
+@dsn_option
+@schema_option
+@click.option("--limit", default=20, show_default=True)
+@click.option("--app", "show_app", is_flag=True, help="Also show the Forge app's sync log from the bucket.")
+@click.option("--source", help="Bucket (default $SQLMIRROR_SOURCE), for --app.")
+@click.option("--endpoint-url")
+@click.option("--region")
+@click.option("--profile")
+def show_log(dsn, schema, limit, show_app, source, endpoint_url, region, profile) -> None:
+    """Show recent runs: apply / backfill on this side, and with --app the app's sync jobs."""
+    db = _db(dsn, schema)
+    db.init_schema()
+    rows = db.recent_log(limit)
+    click.echo("Database side (apply, backfill):")
+    if not rows:
+        click.echo("  nothing yet")
+    for started, finished, kind, src, files, issues, tombstones, skipped, error in rows:
+        took = (finished - started).total_seconds() if finished and started else 0
+        line = (f"  {started:%Y-%m-%d %H:%M:%S} UTC  {kind:<9} {issues:>6} issues {tombstones:>4} deleted "
+                f"{files:>5} files {skipped:>5} skipped  {took:>6.0f}s")
+        click.echo(line + (f"  ERROR: {error}" if error else ""))
+    if show_app:
+        st = _source(source, endpoint_url, region, profile).status()
+        entries = (st or {}).get("log") or []
+        click.echo(f"\nApp side (sync jobs; schedule {(st or {}).get('schedule', '?')}):")
+        if not entries:
+            click.echo("  nothing yet (the app writes its log into _sqlmirror/status.json after each job)")
+        for e in entries[:limit]:
+            changed = ", ".join(e.get("changed") or [])
+            more = (e.get("changedCount") or 0) - len(e.get("changed") or [])
+            click.echo(f"  {e['at'][:19].replace('T', ' ')} UTC  {e.get('trigger', ''):<9} {e.get('issuesWritten', 0):>6} issues "
+                       f"{e.get('tombstones', 0):>4} deleted {e.get('apiCalls', 0):>4} Jira calls"
+                       + (f"  ERROR: {e['error']}" if e.get("error") else "")
+                       + (f"\n      {changed}" + (f" and {more} more" if more > 0 else "") if changed else ""))
+
+
+# ---------------------------------------------------------------- SQL check
+@main.command("check-sql")
+@click.argument("paths", nargs=-1, required=True, type=click.Path(exists=True, path_type=Path))
+@click.option("--dialect", default="postgres", show_default=True,
+              help="Dialect the reports were written for: postgres, sqlserver, mysql, oracle.")
+@click.option("--id-map", type=click.Path(exists=True), help="CSV from 'sqlmirror idmap build' to rewrite ids.")
+@click.option("--out", "out_dir", type=click.Path(path_type=Path), default=Path("sqlmirror-checked"), show_default=True,
+              help="Folder for rewritten SQL and report.md.")
+@click.option("--target", default=None,
+              help="Dialect to rewrite into: postgres or sqlserver (default: the mirror's, else postgres).")
+@click.option("--explain/--no-explain", default=True, show_default=True,
+              help="Compile each rewritten statement against the mirror ($DATABASE_URL): EXPLAIN on Postgres, "
+                   "sp_describe_first_result_set on SQL Server.")
+@dsn_option
+@schema_option
+def check_sql(paths, dialect, id_map, target, out_dir, explain, dsn, schema) -> None:
+    """Check Data Center report SQL against the mirror and rewrite what it can."""
+    from .db import is_sqlserver_dsn
+    from .idmap import IdMap
+    from .sqlcheck import Checker, check_paths, markdown_report, write_outputs
+
+    mirror = None
+    if explain and (dsn or _env("DATABASE_URL")):
+        mirror = _db(dsn, schema)
+    if not target:
+        if mirror is not None:
+            target = mirror.dialect
+        else:
+            target = "sqlserver" if is_sqlserver_dsn(dsn or _env("DATABASE_URL") or "") else "postgres"
+    try:
+        checker = Checker(dialect, idmap=IdMap.load(id_map) if id_map else None, mirror=mirror, target=target)
+    except ValueError as exc:
+        raise click.UsageError(str(exc))
+    results = check_paths(list(paths), checker)
+    write_outputs(results, out_dir)
+    report = markdown_report(results, dialect=dialect, explained=mirror is not None, target=checker.target)
+    (out_dir / "report.md").write_text(report, encoding="utf-8")
+    click.echo(report)
+    click.echo(f"\nRewritten SQL and report.md are in {out_dir}/")
+
+
+@main.group()
+def idmap() -> None:
+    """Map Data Center ids (statuses, fields, users...) to Cloud ids."""
+
+
+@idmap.command("export-sql")
+@click.option("--dialect", default="postgres", show_default=True, help="Your Data Center database type.")
+def idmap_export(dialect: str) -> None:
+    """Print the query to run on the Data Center database (save the result as CSV)."""
+    from .idmap import export_sql
+
+    click.echo(export_sql(dialect))
+
+
+@idmap.command("build")
+@click.argument("dc_csv", type=click.Path(exists=True))
+@click.option("--out", default="id_map.csv", show_default=True)
+@dsn_option
+@schema_option
+def idmap_build(dc_csv: str, out: str, dsn, schema) -> None:
+    """Match the Data Center export to the mirror by name and write id_map.csv."""
+    from .idmap import build, write_csv
+
+    with open(dc_csv, newline="", encoding="utf-8-sig") as fh:
+        rows = build(csv.DictReader(fh), _db(dsn, schema))
+    write_csv(rows, out)
+    matched = sum(1 for r in rows if r["cloud_id"])
+    click.echo(f"Matched {matched} of {len(rows)} Data Center ids; wrote {out}.")
+    for r in rows:
+        if not r["cloud_id"]:
+            click.echo(f"  no match: {r['entity']} {r['dc_id']} ({r['name']}) - {r['match']}")
+
+
+if __name__ == "__main__":
+    main()