@intentius/sql-yodeler 0.1.0 → 0.3.0

package/schemas/revert.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/revert.schema.json",
+  "title": "yodel revert <env> <id> --json",
+  "description": "Version 1. The revert of a migration: the statements that take the schema from its recorded schema back to its parent's (a hand-written revert step's first), the digest its gate binds, and what happened: planned (--dry-run), denied by a policy rule, gated (waiting for approval), reverted, or failed. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["environment", "migration", "to", "planDigest", "statements", "dataSteps", "status"],
+  "properties": {
+    "environment": { "type": "string" },
+    "migration": { "type": "string" },
+    "to": { "description": "The migration it goes back to; null when the first migration is reverted.", "type": ["string", "null"] },
+    "planDigest": { "type": "string" },
+    "statements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["index", "source", "sql", "rule", "class", "done"],
+        "properties": {
+          "index": { "type": "integer", "minimum": 0 },
+          "source": { "description": "step: the hand-written revert step; reverse: diffed from the recorded schemas.", "enum": ["step", "reverse"] },
+          "sql": { "type": "string" },
+          "rule": { "type": "string" },
+          "class": { "type": "string" },
+          "destructive": { "const": true },
+          "done": { "description": "It succeeded in an earlier run of this revert and is not sent again.", "type": "boolean" }
+        }
+      }
+    },
+    "dataSteps": { "description": "The migration's data steps, which the hand-written revert step undoes.", "$ref": "common.schema.json#/$defs/stringList" },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "sha", "statements"],
+      "properties": { "file": { "type": "string" }, "sha": { "type": "string" }, "statements": { "type": "integer", "minimum": 1 } }
+    },
+    "status": { "enum": ["planned", "denied", "gated", "reverted", "failed"] },
+    "policy": {
+      "description": "Each policy rule's outcome over the revert, the policy as the base commit has it; denied when a rule denies the revert and no override is recorded for its digest.",
+      "$ref": "common.schema.json#/$defs/policy"
+    },
+    "wave": {
+      "description": "When yodel.config.ts waves names the environment: the wave's gate policy at the base commit, the revert's statements it counts as destructive, and whether it asks for an approval of the revert. The revert waits at the migrations Op's gate either way.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gate", "base", "destructiveSteps", "policyWaits"],
+      "properties": {
+        "gate": { "enum": ["always", "on-destructive", "never"] },
+        "base": { "type": "string" },
+        "destructiveSteps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["migration", "step", "what", "why"],
+            "properties": { "migration": { "type": "string" }, "step": { "type": "integer", "minimum": 0 }, "what": { "type": "string" }, "why": { "type": "string" } }
+          }
+        },
+        "policyWaits": { "type": "boolean" }
+      }
+    },
+    "op": { "type": "string" },
+    "gate": { "type": "string" },
+    "approve": { "description": "The chant approve command that approves this revert.", "type": "string" },
+    "gatePlanDigest": { "type": "string" },
+    "exitCode": { "type": "integer" }
+  }
+}

package/schemas/status.schema.json

@@ -0,0 +1,371 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/status.schema.json",
+  "title": "yodel status <env> --json",
+  "description": "Version 1. The environment's migrations against its history; for an environment with a tenant set (yodel.config.ts environments.<env>.tenants), each tenant's, against its own history. Within a version, fields are only added; a reader ignores fields it does not know. yodel apply --json carries the same fields (apply.schema.json).",
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "$ref": "#/$defs/report",
+      "unevaluatedProperties": false
+    },
+    {
+      "$ref": "#/$defs/tenants"
+    }
+  ],
+  "$defs": {
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "index",
+        "kind",
+        "object",
+        "name"
+      ],
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "kind": {
+          "enum": [
+            "op",
+            "manual"
+          ]
+        },
+        "object": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "op": {
+          "type": "string"
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "report": {
+      "type": "object",
+      "required": [
+        "environment",
+        "history",
+        "applied",
+        "pending",
+        "outOfOrder",
+        "partWay",
+        "mismatches"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "server": {
+          "$ref": "common.schema.json#/$defs/server"
+        },
+        "history": {
+          "description": "Where the history table is: its database (ClickHouse) or schema (Postgres), and on ClickHouse the history's own topology.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "database"
+          ],
+          "properties": {
+            "database": {
+              "type": "string"
+            },
+            "topology": {
+              "type": "string"
+            }
+          }
+        },
+        "topology": {
+          "description": "ClickHouse only: the topology statements are rendered for, and where it came from.",
+          "type": "string"
+        },
+        "applied": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "checksum",
+              "appliedBy",
+              "recordedAt",
+              "planDigest",
+              "inDirectory"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "checksum": {
+                "type": "string"
+              },
+              "appliedBy": {
+                "type": "string"
+              },
+              "recordedAt": {
+                "type": "string"
+              },
+              "planDigest": {
+                "type": "string"
+              },
+              "inDirectory": {
+                "type": "boolean"
+              },
+              "repairs": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "checksum",
+                    "by",
+                    "at",
+                    "reason"
+                  ],
+                  "properties": {
+                    "checksum": {
+                      "type": "string"
+                    },
+                    "by": {
+                      "type": "string"
+                    },
+                    "at": {
+                      "type": "string"
+                    },
+                    "reason": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "pending": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "checksum",
+              "outOfOrder",
+              "partWay",
+              "opSteps",
+              "refusedSteps"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "checksum": {
+                "type": "string"
+              },
+              "outOfOrder": {
+                "type": "boolean"
+              },
+              "reverted": {
+                "description": "It was applied, then yodel revert undid it: who reverted it and when. Applied again, every statement runs again.",
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["by", "at"],
+                "properties": { "by": { "type": "string" }, "at": { "type": "string" } }
+              },
+              "partWay": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "status",
+                      "resumeAt",
+                      "error",
+                      "done",
+                      "edited"
+                    ],
+                    "properties": {
+                      "status": {
+                        "enum": [
+                          "failed",
+                          "started"
+                        ]
+                      },
+                      "resumeAt": {
+                        "type": "integer"
+                      },
+                      "failedStatement": {
+                        "type": "integer"
+                      },
+                      "error": {
+                        "type": "string"
+                      },
+                      "done": {
+                        "type": "array",
+                        "items": {
+                          "type": "integer"
+                        }
+                      },
+                      "edited": {
+                        "type": "boolean"
+                      }
+                    }
+                  }
+                ]
+              },
+              "opSteps": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/step"
+                }
+              },
+              "refusedSteps": {
+                "type": "array",
+                "items": {
+                  "allOf": [
+                    {
+                      "$ref": "#/$defs/step"
+                    },
+                    {
+                      "required": [
+                        "reason"
+                      ],
+                      "type": "object"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        },
+        "outOfOrder": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "partWay": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "failedStatement"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "resumeAt": {
+                "type": "integer"
+              },
+              "failedStatement": {
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              }
+            }
+          }
+        },
+        "mismatches": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "kind",
+              "id",
+              "message"
+            ],
+            "properties": {
+              "kind": {
+                "enum": [
+                  "applied",
+                  "part-way",
+                  "missing"
+                ]
+              },
+              "id": {
+                "type": "string"
+              },
+              "recorded": {
+                "type": "string"
+              },
+              "actual": {
+                "type": "string"
+              },
+              "statement": {
+                "type": "integer"
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "skipped": {
+          "description": "The migrations a checkpoint leaves out in this environment, in chain order: covered (before the checkpoint the environment starts from, named) or checkpoint (a checkpoint the environment does not start from). Absent when there are none.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "reason"],
+            "properties": {
+              "id": { "type": "string" },
+              "reason": { "enum": ["covered", "checkpoint"] },
+              "checkpoint": { "type": "string" }
+            }
+          }
+        },
+        "planDigest": {
+          "description": "The digest yodel apply would ask approval for, when it would not refuse.",
+          "type": "string"
+        },
+        "refusal": {
+          "$ref": "common.schema.json#/$defs/refusal"
+        }
+      }
+    },
+    "tenants": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "environment",
+        "tenants",
+        "upToDate",
+        "total"
+      ],
+      "description": "A tenant set: each tenant's status, named <env>/<tenant>, and how many are up to date.",
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "tenants": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/$defs/report",
+            "unevaluatedProperties": false
+          }
+        },
+        "upToDate": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}