sqlmirror 0.2.0__py3-none-any.whl

sqlmirror/reconcile.py

@@ -0,0 +1,73 @@
+"""Compare the mirror with Jira and optionally repair differences."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .db import Mirror
+from .jira import JiraClient
+from .mapper import Mapper
+from .util import iso, parse_ts, utcnow
+
+
+@dataclass
+class ProjectReport:
+    key: str
+    jira: int | None
+    mirror: int
+    missing: list[int] = field(default_factory=list)
+    extra: list[int] = field(default_factory=list)
+    stale: list[int] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.jira == self.mirror and not self.missing and not self.extra and not self.stale
+
+
+def reconcile(client: JiraClient, db: Mirror, mapper: Mapper, *, projects: list[str] | None = None,
+              deep: bool = False, repair: bool = False, log: Callable[[str], None] = print) -> list[ProjectReport]:
+    db.load_registry(mapper)
+    counts = db.project_counts()
+    keys = [k for k in counts if not projects or k in {p.upper() for p in projects}]
+    reports: list[ProjectReport] = []
+    for key in keys:
+        jql = f'project = "{key}"'
+        rep = ProjectReport(key=key, jira=client.approximate_count(jql), mirror=counts[key])
+        if deep or repair:
+            jira_updated: dict[int, object] = {}
+            for page in client.search(jql + " ORDER BY id ASC", fields=["updated"], page_size=1000):
+                for issue in page:
+                    jira_updated[int(issue["id"])] = parse_ts((issue.get("fields") or {}).get("updated"))
+            mirror_updated = db.issue_updated(key)
+            rep.jira = len(jira_updated)
+            rep.missing = sorted(set(jira_updated) - set(mirror_updated))
+            rep.extra = sorted(set(mirror_updated) - set(jira_updated))
+            # SQL Server's datetime rounds to 1/300 s; don't call that stale.
+            slack = db.timestamp_resolution
+            rep.stale = sorted(i for i in set(jira_updated) & set(mirror_updated)
+                               if jira_updated[i] and mirror_updated[i] and jira_updated[i] > mirror_updated[i] + slack)
+        reports.append(rep)
+        if repair and (rep.missing or rep.stale or rep.extra):
+            fix = rep.missing + rep.stale
+            for i in range(0, len(fix), 100):
+                fetched_at = iso(utcnow())
+                issues = client.bulkfetch([str(x) for x in fix[i:i + 100]])
+                snaps = [client.complete_snapshot(issue, fetched_at) for issue in issues]
+                db.apply_records(mapper, snaps, source="reconcile")
+            if rep.extra:
+                now = iso(utcnow())
+                db.apply_records(mapper, [{"v": 1, "type": "deleted", "id": str(x), "deletedAt": now}
+                                          for x in rep.extra], source="reconcile")
+            log(f"[{key}] repaired {len(fix)} issues, removed {len(rep.extra)} deleted issues")
+    return reports
+
+
+def format_reports(reports: list[ProjectReport], deep: bool) -> str:
+    lines = ["Project    Jira   Mirror  " + ("Missing  Extra  Stale  " if deep else "") + "Status"]
+    for r in reports:
+        status = "OK" if (r.ok if deep else r.jira == r.mirror) else "DIFFERENT"
+        line = f"{r.key:<9} {str(r.jira if r.jira is not None else '?'):>5} {r.mirror:>8}  "
+        if deep:
+            line += f"{len(r.missing):>7} {len(r.extra):>6} {len(r.stale):>6}  "
+        lines.append(line + status)
+    return "\n".join(lines)

sqlmirror/samples/dc_export_example.csv

@@ -0,0 +1,19 @@
+entity,dc_id,name,extra
+status,1,To Do,
+status,3,In Progress,
+status,10200,In Review,
+status,6,Done,
+priority,1,Highest,
+priority,2,High,
+priority,3,Medium,
+priority,4,Low,
+priority,5,Lowest,
+project,10100,ALPHA,Alpha Project
+project,10101,BETA,Beta Project
+customfield,10500,Customer Impact,com.atlassian.jira.plugin.system.customfieldtypes:select
+customfield,10101,Sprint,com.pyxis.greenhopper.jira:gh-sprint
+customfield,10106,Story Points,com.atlassian.jira.plugin.system.customfieldtypes:float
+option,10603,Critical,Customer Impact
+option,10602,High,Customer Impact
+user,jsmith,ana.smith@example.com,Ana Smith
+user,JIRAUSER10200,nobody@example.com,Someone Who Left

sqlmirror/samples/dc_reports/mysql_sprint_report.sql

@@ -0,0 +1,10 @@
+-- MySQL: closed sprints with completed issue counts
+SELECT s.NAME AS sprint, COUNT(*) AS issues,
+       SUM(CASE WHEN st.statuscategory = 3 THEN 1 ELSE 0 END) AS done
+FROM AO_60DB71_SPRINT s
+JOIN customfieldvalue cfv ON cfv.stringvalue = CAST(s.ID AS CHAR)
+JOIN jiraissue ji ON ji.id = cfv.issue
+JOIN issuestatus st ON st.id = ji.issuestatus
+WHERE s.CLOSED = 1 AND cfv.customfield = 10101
+GROUP BY s.NAME, s.ID
+ORDER BY s.ID;

sqlmirror/samples/dc_reports/postgres_assigned_to_user.sql

@@ -0,0 +1,6 @@
+-- Postgres: everything assigned to one person, by Data Center username
+SELECT ji.pkey, ji.summary, pr.pname AS priority
+FROM jiraissue ji
+JOIN priority pr ON pr.id = ji.priority
+WHERE ji.assignee = 'jsmith'
+ORDER BY ji.created;

sqlmirror/samples/dc_reports/postgres_customer_impact.sql

@@ -0,0 +1,7 @@
+-- Postgres: critical customer-impact issues, by hard-coded custom field and option ids
+SELECT ji.pkey, ji.summary
+FROM jiraissue ji
+JOIN customfieldvalue cfv ON cfv.issue = ji.id
+WHERE cfv.customfield = 10500
+  AND cfv.stringvalue = '10603'
+ORDER BY ji.pkey;

sqlmirror/samples/dc_reports/postgres_time_logged.sql

@@ -0,0 +1,7 @@
+-- Postgres: hours logged per project this year (works unchanged)
+SELECT p.pkey, round(sum(w.timeworked) / 3600.0, 1) AS hours
+FROM worklog w
+JOIN jiraissue ji ON ji.id = w.issueid
+JOIN project p ON p.id = ji.project
+GROUP BY p.pkey
+ORDER BY p.pkey;

sqlmirror/samples/dc_reports/postgres_workflow_steps.sql

@@ -0,0 +1,4 @@
+-- Postgres: current workflow step per issue (uses workflow engine tables)
+SELECT ji.pkey, cs.step_id
+FROM jiraissue ji
+JOIN os_currentstep cs ON cs.entry_id = ji.workflow_id;

sqlmirror/samples/dc_reports/sqlserver_open_by_status.sql

@@ -0,0 +1,9 @@
+-- SQL Server: open issues per status for one project, last 90 days
+SELECT TOP 20 p.pkey + '-' + CAST(ji.issuenum AS varchar(20)) AS issue_key, s.pname, ji.created
+FROM dbo.jiraissue ji WITH (NOLOCK)
+JOIN dbo.project p ON p.id = ji.project
+JOIN dbo.issuestatus s ON s.id = ji.issuestatus
+WHERE ji.issuestatus IN ('1', '3')
+  AND ji.project = 10100
+  AND DATEDIFF(day, ji.created, GETDATE()) < 90
+ORDER BY ji.created DESC;

sqlmirror/schema.py

@@ -0,0 +1,518 @@
+"""Table definitions for the Data-Center-compatible mirror.
+
+One place defines every table: its columns, primary key, and how rows are
+replaced when an issue changes. DDL for each dialect and the database writer
+are generated from these definitions, so they cannot drift apart.
+
+Column types are logical names mapped per dialect in ``column_type()``
+(Postgres / SQL Server, the types Data Center uses on each):
+  id    -> numeric(18,0)              numeric(18,0)
+  num   -> numeric(18,0)              numeric(18,0)
+  float -> double precision           float
+  str   -> varchar(255)               nvarchar(255)
+  text  -> text                       nvarchar(max)
+  ts    -> timestamp with time zone   datetime (UTC; bookkeeping tables datetime2(6))
+  bool  -> boolean                    bit
+  big   -> bigint                     bigint
+  int   -> integer                    int
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Table:
+    name: str
+    columns: tuple[tuple[str, str], ...]
+    pk: tuple[str, ...]
+    # How rows are replaced:
+    #   "issue"  - all rows for an issue are deleted and re-inserted on every snapshot;
+    #              issue_col names the column holding the issue id.
+    #   "upsert" - insert or update by primary key; null values never overwrite
+    #              existing non-null values.
+    #   "state"  - mirror bookkeeping, managed directly by the writer.
+    mode: str
+    issue_col: str | None = None
+    quoted: bool = False  # Active Objects tables use quoted upper-case names
+    indexes: tuple[tuple[str, ...], ...] = field(default_factory=tuple)
+
+    @property
+    def column_names(self) -> list[str]:
+        return [c for c, _ in self.columns]
+
+    def q(self, name: str) -> str:
+        """Quote an identifier if this table uses quoted names."""
+        return f'"{name}"' if self.quoted else name
+
+    @property
+    def qname(self) -> str:
+        return self.q(self.name)
+
+
+def _cols(*pairs: str) -> tuple[tuple[str, str], ...]:
+    out = []
+    for p in pairs:
+        name, typ = p.split(":")
+        out.append((name, typ))
+    return tuple(out)
+
+
+TABLES: list[Table] = [
+    # ---------------------------------------------------------------- issue data
+    Table(
+        "jiraissue",
+        _cols(
+            "id:id", "pkey:str", "issuenum:num", "project:id", "reporter:str",
+            "assignee:str", "creator:str", "issuetype:str", "summary:str",
+            "description:text", "environment:text", "priority:str", "resolution:str",
+            "issuestatus:str", "created:ts", "updated:ts", "duedate:ts",
+            "resolutiondate:ts", "votes:num", "watches:num", "timeoriginalestimate:num",
+            "timeestimate:num", "timespent:num", "workflow_id:id", "security:id",
+            "fixfor:id", "component:id", "archived:str", "archivedby:str",
+            "archiveddate:ts",
+        ),
+        pk=("id",),
+        mode="issue",
+        issue_col="id",
+        indexes=(("project", "issuenum"), ("issuestatus",), ("assignee",), ("updated",)),
+    ),
+    Table(
+        "changegroup",
+        _cols("id:id", "issueid:id", "author:str", "created:ts"),
+        pk=("id",),
+        mode="issue",
+        issue_col="issueid",
+        indexes=(("issueid",),),
+    ),
+    Table(
+        "changeitem",
+        _cols(
+            "id:id", "groupid:id", "fieldtype:str", "field:str", "oldvalue:text",
+            "oldstring:text", "newvalue:text", "newstring:text",
+        ),
+        pk=("id",),
+        mode="issue",
+        issue_col=None,  # deleted through changegroup.issueid
+        indexes=(("groupid",), ("field",)),
+    ),
+    Table(
+        "jiraaction",
+        _cols(
+            "id:id", "issueid:id", "author:str", "actiontype:str", "actionlevel:str",
+            "rolelevel:id", "actionbody:text", "created:ts", "updateauthor:str",
+            "updated:ts", "actionnum:num",
+        ),
+        pk=("id",),
+        mode="issue",
+        issue_col="issueid",
+        indexes=(("issueid",),),
+    ),
+    Table(
+        "worklog",
+        _cols(
+            "id:id", "issueid:id", "author:str", "grouplevel:str", "rolelevel:id",
+            "worklogbody:text", "created:ts", "updateauthor:str", "updated:ts",
+            "startdate:ts", "timeworked:num",
+        ),
+        pk=("id",),
+        mode="issue",
+        issue_col="issueid",
+        indexes=(("issueid",), ("author",)),
+    ),
+    Table(
+        "customfieldvalue",
+        _cols(
+            "id:id", "issue:id", "customfield:id", "updated:big", "parentkey:str",
+            "stringvalue:str", "numbervalue:float", "textvalue:text", "datevalue:ts",
+            "valuetype:str",
+        ),
+        pk=("id",),
+        mode="issue",
+        issue_col="issue",
+        indexes=(("issue", "customfield"), ("customfield",)),
+    ),
+    Table(
+        "label",
+        _cols("id:id", "fieldid:id", "issue:id", "label:str"),
+        pk=("id",),
+        mode="issue",
+        issue_col="issue",
+        indexes=(("issue",), ("label",)),
+    ),
+    Table(
+        "nodeassociation",
+        _cols(
+            "source_node_id:id", "source_node_entity:str", "sink_node_id:id",
+            "sink_node_entity:str", "association_type:str", "sequence:num",
+        ),
+        pk=("source_node_id", "source_node_entity", "sink_node_id", "sink_node_entity", "association_type"),
+        mode="issue",
+        issue_col="source_node_id",  # only rows with source_node_entity = 'Issue'
+        indexes=(("sink_node_id", "association_type"),),
+    ),
+    Table(
+        "issuelink",
+        _cols("id:id", "linktype:id", "source:id", "destination:id", "sequence:num"),
+        pk=("id",),
+        mode="issue",
+        issue_col=None,  # deleted where source or destination is the issue
+        indexes=(("source",), ("destination",), ("linktype",)),
+    ),
+    Table(
+        "fileattachment",
+        _cols(
+            "id:id", "issueid:id", "mimetype:str", "filename:str", "created:ts",
+            "filesize:num", "author:str", "zip:int", "thumbnailable:int",
+        ),
+        pk=("id",),
+        mode="issue",
+        issue_col="issueid",
+        indexes=(("issueid",),),
+    ),
+    # ------------------------------------------------------------ configuration
+    Table(
+        "project",
+        _cols(
+            "id:id", "pname:str", "url:str", "lead:str", "description:text", "pkey:str",
+            "pcounter:num", "assigneetype:num", "avatar:id", "originalkey:str",
+            "projecttype:str",
+        ),
+        pk=("id",),
+        mode="upsert",
+        indexes=(("pkey",),),
+    ),
+    Table("project_key", _cols("id:id", "project_id:id", "project_key:str"), pk=("id",), mode="upsert"),
+    Table("projectcategory", _cols("id:id", "cname:str", "description:text"), pk=("id",), mode="upsert"),
+    Table(
+        "issuestatus",
+        _cols("id:str", "sequence:num", "pname:str", "description:text", "iconurl:str", "statuscategory:num"),
+        pk=("id",),
+        mode="upsert",
+    ),
+    Table(
+        "issuetype",
+        _cols("id:str", "sequence:num", "pname:str", "pstyle:str", "description:text", "iconurl:str", "avatar:id"),
+        pk=("id",),
+        mode="upsert",
+    ),
+    Table(
+        "priority",
+        _cols("id:str", "sequence:num", "pname:str", "description:text", "iconurl:str", "status_color:str"),
+        pk=("id",),
+        mode="upsert",
+    ),
+    Table(
+        "resolution",
+        _cols("id:str", "sequence:num", "pname:str", "description:text", "iconurl:str"),
+        pk=("id",),
+        mode="upsert",
+    ),
+    Table(
+        "projectversion",
+        _cols(
+            "id:id", "project:id", "vname:str", "description:text", "sequence:num",
+            "released:str", "archived:str", "url:str", "startdate:ts", "releasedate:ts",
+        ),
+        pk=("id",),
+        mode="upsert",
+        indexes=(("project",),),
+    ),
+    Table(
+        "component",
+        _cols(
+            "id:id", "project:id", "cname:str", "description:text", "url:str", "lead:str",
+            "assigneetype:num", "archived:str", "deleted:str",
+        ),
+        pk=("id",),
+        mode="upsert",
+        indexes=(("project",),),
+    ),
+    Table(
+        "customfield",
+        _cols(
+            "id:id", "cfkey:str", "customfieldtypekey:str", "customfieldsearcherkey:str",
+            "cfname:str", "description:text", "defaultvalue:str", "fieldtype:num",
+            "project:id", "issuetype:str",
+        ),
+        pk=("id",),
+        mode="upsert",
+    ),
+    Table(
+        "customfieldoption",
+        _cols(
+            "id:id", "customfield:id", "customfieldconfig:id", "parentoptionid:id",
+            "sequence:num", "customvalue:str", "optiontype:str", "disabled:str",
+        ),
+        pk=("id",),
+        mode="upsert",
+        indexes=(("customfield",),),
+    ),
+    Table(
+        "issuelinktype",
+        _cols("id:id", "linkname:str", "inward:str", "outward:str", "pstyle:str"),
+        pk=("id",),
+        mode="upsert",
+    ),
+    Table(
+        "app_user",
+        _cols("id:id", "user_key:str", "lower_user_name:str"),
+        pk=("id",),
+        mode="upsert",
+        indexes=(("user_key",), ("lower_user_name",)),
+    ),
+    Table(
+        "cwd_user",
+        _cols(
+            "id:id", "directory_id:id", "user_name:str", "lower_user_name:str", "active:int",
+            "created_date:ts", "updated_date:ts", "first_name:str", "lower_first_name:str",
+            "last_name:str", "lower_last_name:str", "display_name:str",
+            "lower_display_name:str", "email_address:str", "lower_email_address:str",
+            "external_id:str",
+        ),
+        pk=("id",),
+        mode="upsert",
+        indexes=(("lower_user_name",),),
+    ),
+    # Jira Software (Active Objects) tables keep their quoted upper-case names,
+    # exactly as on a Data Center Postgres database.
+    Table(
+        "AO_60DB71_SPRINT",
+        _cols(
+            "ID:big", "NAME:str", "GOAL:text", "STARTED:bool", "CLOSED:bool",
+            "START_DATE:big", "END_DATE:big", "COMPLETE_DATE:big", "ACTIVATED_DATE:big",
+            "RAPID_VIEW_ID:big", "SEQUENCE:big",
+        ),
+        pk=("ID",),
+        mode="upsert",
+        quoted=True,
+    ),
+    Table(
+        "AO_60DB71_RAPIDVIEW",
+        _cols("ID:big", "NAME:str", "FILTER_ID:big", "OWNER_USER_NAME:str"),
+        pk=("ID",),
+        mode="upsert",
+        quoted=True,
+    ),
+    # ------------------------------------------------------- mirror bookkeeping
+    Table(
+        "sqlmirror_issue_state",
+        _cols("issue_id:id", "fetched_at:ts", "deleted:bool", "source:str", "applied_at:ts"),
+        pk=("issue_id",),
+        mode="state",
+    ),
+    Table(
+        "sqlmirror_applied_file",
+        _cols("key:text", "records:int", "applied_at:ts"),
+        pk=("key",),
+        mode="state",
+    ),
+    Table("sqlmirror_meta", _cols("key:str", "value:text"), pk=("key",), mode="state"),
+    Table(
+        "sqlmirror_sync_log",
+        _cols(
+            "id:big", "started_at:ts", "finished_at:ts", "kind:str", "source:text", "files:int",
+            "issues:int", "tombstones:int", "skipped:int", "error:text",
+        ),
+        pk=("id",),
+        mode="state",
+        indexes=(("started_at",),),
+    ),
+]
+
+TABLE_BY_NAME: dict[str, Table] = {t.name: t for t in TABLES}
+
+# Tables whose rows belong to a single issue and are replaced on every snapshot.
+ISSUE_TABLES = [t for t in TABLES if t.mode == "issue"]
+UPSERT_TABLES = [t for t in TABLES if t.mode == "upsert"]
+
+SCHEMA_VERSION = "1"
+
+# Data Center tables a report might use that the mirror does not provide,
+# with the reason. Used by the SQL checker.
+UNSUPPORTED_TABLES: dict[str, str] = {
+    "os_wfentry": "workflow engine state; Cloud has no equivalent export",
+    "os_currentstep": "workflow engine state; Cloud has no equivalent export",
+    "os_historystep": "workflow engine state; use changeitem rows where field = 'status' instead",
+    "jiraworkflows": "workflow XML is not available through the Cloud REST API",
+    "workflowscheme": "scheme configuration is not mirrored",
+    "workflowschemeentity": "scheme configuration is not mirrored",
+    "searchrequest": "saved filters are not mirrored yet",
+    "schemepermissions": "permission schemes are not mirrored",
+    "permissionscheme": "permission schemes are not mirrored",
+    "cwd_group": "groups are not mirrored yet",
+    "cwd_membership": "group membership is not mirrored yet",
+    "cwd_directory": "Cloud users live in a single Atlassian directory; directory_id is always 1",
+    "propertyentry": "Data Center property storage has no Cloud equivalent",
+    "propertystring": "Data Center property storage has no Cloud equivalent",
+    "propertynumber": "Data Center property storage has no Cloud equivalent",
+    "propertytext": "Data Center property storage has no Cloud equivalent",
+    "fieldconfiguration": "field configuration schemes are not mirrored",
+    "fieldlayout": "field configuration schemes are not mirrored",
+    "fieldlayoutitem": "field configuration schemes are not mirrored",
+    "fieldscreen": "screens are not mirrored",
+    "configurationcontext": "custom field contexts are not mirrored",
+    "fieldconfigscheme": "custom field contexts are not mirrored",
+    "notificationinstance": "notification schemes are not mirrored",
+    "jiraperms": "permissions are not mirrored",
+    "userassociation": "watchers and voters are not mirrored per user (counts are in jiraissue.watches / votes)",
+    "audit_log": "the Cloud audit log is a separate API",
+    "projectroleactor": "project role membership is not mirrored yet",
+    "projectrole": "project roles are not mirrored yet",
+    "issuesecurityscheme": "issue security schemes are not mirrored",
+    "schemeissuesecuritylevels": "issue security schemes are not mirrored",
+}
+
+# Columns that exist for compatibility but are always NULL in the mirror.
+ALWAYS_NULL_COLUMNS: dict[tuple[str, str], str] = {
+    ("jiraissue", "workflow_id"): "Cloud does not expose workflow instance ids",
+    ("jiraissue", "fixfor"): "legacy column; use nodeassociation with association_type = 'IssueFixVersion'",
+    ("jiraissue", "component"): "legacy column; use nodeassociation with association_type = 'IssueComponent'",
+    ("jiraaction", "actionnum"): "not provided by Cloud",
+    ("customfieldoption", "customfieldconfig"): "custom field contexts are not mirrored",
+    ("customfieldoption", "sequence"): "option order is not available from issue data",
+    ("AO_60DB71_RAPIDVIEW", "NAME"): "board names need Jira Software board scopes (planned)",
+}
+
+_DIALECT_TYPES = {
+    "postgres": {
+        "id": "numeric(18,0)",
+        "num": "numeric(18,0)",
+        "float": "double precision",
+        "str": "varchar(255)",
+        "text": "text",
+        "ts": "timestamp with time zone",
+        "bool": "boolean",
+        "big": "bigint",
+        "int": "integer",
+    },
+    # The column types Jira Data Center itself uses on SQL Server.
+    "tsql": {
+        "id": "numeric(18,0)",
+        "num": "numeric(18,0)",
+        "float": "float",
+        "str": "nvarchar(255)",
+        "text": "nvarchar(max)",
+        "ts": "datetime",
+        "bool": "bit",
+        "big": "bigint",
+        "int": "int",
+    },
+}
+
+DIALECT_ALIASES = {"postgres": "postgres", "postgresql": "postgres", "pg": "postgres",
+                   "tsql": "tsql", "sqlserver": "tsql", "mssql": "tsql", "azuresql": "tsql"}
+
+# SQL Server only: Data Center's own widths for the nodeassociation key columns
+# (keeps the five-column primary key under SQL Server's 900-byte limit).
+_TSQL_COLUMN_TYPES: dict[tuple[str, str], str] = {
+    ("nodeassociation", "source_node_entity"): "nvarchar(60)",
+    ("nodeassociation", "sink_node_entity"): "nvarchar(60)",
+    ("nodeassociation", "association_type"): "nvarchar(60)",
+}
+
+
+# Bucket object keys are case-sensitive; the default SQL Server collation is not.
+_TSQL_BINARY_COLUMNS: dict[tuple[str, str], str] = {("sqlmirror_applied_file", "key"): "Latin1_General_100_BIN2"}
+
+
+def normalize_dialect(dialect: str) -> str:
+    try:
+        return DIALECT_ALIASES[dialect.lower()]
+    except KeyError:
+        raise ValueError(f"unknown database dialect {dialect!r}; use postgres or sqlserver") from None
+
+
+def column_type(t: Table, name: str, typ: str, dialect: str) -> str:
+    """The SQL type of one column in one dialect."""
+    dialect = normalize_dialect(dialect)
+    types = _DIALECT_TYPES[dialect]
+    if dialect == "tsql":
+        if (t.name, name) in _TSQL_COLUMN_TYPES:
+            return _TSQL_COLUMN_TYPES[(t.name, name)]
+        if typ == "ts" and t.mode == "state":
+            # Bookkeeping times must round-trip exactly (newest snapshot wins);
+            # datetime only keeps 1/300 s.
+            return "datetime2(6)"
+    sql_type = types[typ]
+    # Free-text columns that can exceed 255 characters in Cloud data.
+    if typ == "str" and name in _LONG_STR_COLUMNS.get(t.name, ()):
+        sql_type = types["text"]
+    if dialect == "tsql" and sql_type == "nvarchar(max)":
+        # nvarchar(max) can't be part of a key or an index.
+        if name in t.pk:
+            return "nvarchar(450)"  # 900-byte primary key limit
+        if any(name in idx for idx in t.indexes):
+            return "nvarchar(850)"  # 1700-byte index key limit
+    return sql_type
+
+
+def tsql_ident(name: str) -> str:
+    return "[" + name.replace("]", "]]") + "]"
+
+
+def ddl_statements(dialect: str = "postgres", schema: str | None = None) -> list[str]:
+    """CREATE TABLE / CREATE INDEX statements for every table (each one idempotent)."""
+    dialect = normalize_dialect(dialect)
+    if dialect == "tsql":
+        return _tsql_ddl(schema or "dbo")
+    out: list[str] = []
+    for t in TABLES:
+        cols = [f"  {t.q(name)} {column_type(t, name, typ, dialect)}" for name, typ in t.columns]
+        pk = ", ".join(t.q(c) for c in t.pk)
+        cols.append(f"  PRIMARY KEY ({pk})")
+        out.append(f"CREATE TABLE IF NOT EXISTS {t.qname} (\n" + ",\n".join(cols) + "\n);")
+        for idx in t.indexes:
+            idx_name = f"sqlm_{t.name.lower()}_{'_'.join(c.lower() for c in idx)}"
+            out.append(
+                f"CREATE INDEX IF NOT EXISTS {idx_name} ON {t.qname} ({', '.join(t.q(c) for c in idx)});"
+            )
+    return out
+
+
+def _tsql_ddl(schema: str) -> list[str]:
+    q = tsql_ident
+    out: list[str] = []
+    if schema.lower() != "dbo":
+        lit = schema.replace("'", "''")
+        out.append(f"IF SCHEMA_ID(N'{lit}') IS NULL EXEC(N'CREATE SCHEMA {q(schema).replace(chr(39), chr(39) * 2)}');")
+    for t in TABLES:
+        full = f"{q(schema)}.{q(t.name)}"
+        lit = full.replace("'", "''")
+        cols = []
+        for name, typ in t.columns:
+            null = "NOT NULL" if name in t.pk else "NULL"
+            collate = f" COLLATE {_TSQL_BINARY_COLUMNS[(t.name, name)]}" if (t.name, name) in _TSQL_BINARY_COLUMNS else ""
+            cols.append(f"  {q(name)} {column_type(t, name, typ, 'tsql')}{collate} {null}")
+        cols.append(f"  CONSTRAINT {q('pk_sqlm_' + t.name.lower())} PRIMARY KEY ({', '.join(q(c) for c in t.pk)})")
+        out.append(f"IF OBJECT_ID(N'{lit}', N'U') IS NULL\nCREATE TABLE {full} (\n" + ",\n".join(cols) + "\n);")
+        for idx in t.indexes:
+            idx_name = f"sqlm_{t.name.lower()}_{'_'.join(c.lower() for c in idx)}"
+            out.append(
+                f"IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = N'{idx_name}' AND object_id = OBJECT_ID(N'{lit}'))\n"
+                f"CREATE INDEX {q(idx_name)} ON {full} ({', '.join(q(c) for c in idx)});"
+            )
+    return out
+
+
+def ddl(dialect: str = "postgres", schema: str | None = None) -> str:
+    """CREATE TABLE / CREATE INDEX statements for every table (idempotent)."""
+    return "\n".join(ddl_statements(dialect, schema)) + "\n"
+
+
+# varchar(255) in Data Center, but Cloud values can be longer (for example
+# changelog strings and option values); store as text so inserts never fail.
+_LONG_STR_COLUMNS: dict[str, tuple[str, ...]] = {
+    "jiraissue": ("summary",),
+    "customfieldvalue": ("stringvalue",),
+    "customfieldoption": ("customvalue",),
+    "project": ("url",),
+    "projectversion": ("url",),
+    "component": ("url",),
+    "issuestatus": ("iconurl",),
+    "issuetype": ("iconurl",),
+    "priority": ("iconurl",),
+    "resolution": ("iconurl",),
+    "fileattachment": ("filename", "mimetype"),
+    "label": ("label",),
+}