@intentius/sql-yodeler 0.1.0 → 0.3.0

package/schemas/plan.schema.json

@@ -0,0 +1,489 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/plan.schema.json",
+  "title": "yodel plan <env> --json",
+  "description": "Version 1. A project with migrations prints the versioned plan (mode \"versioned\"); a project without prints the declarative plan, chant's diff with the environment and dialect it is of. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/versioned"
+    },
+    {
+      "$ref": "#/$defs/declarative"
+    }
+  ],
+  "$defs": {
+    "declarative": {
+      "description": "chant's diff (chant sql plan --json) with environment, dialect and server added. chant owns the diff's fields: ones beyond those listed may appear.",
+      "type": "object",
+      "required": [
+        "environment",
+        "dialect",
+        "changes",
+        "hints"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "dialect": {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        "server": {
+          "$ref": "common.schema.json#/$defs/server"
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "$ref": "common.schema.json#/$defs/change"
+          }
+        },
+        "hints": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "rebuilds": {
+          "description": "ClickHouse: the changes that need a ClickHouseRebuildOp.",
+          "type": "array",
+          "items": {
+            "$ref": "common.schema.json#/$defs/change"
+          }
+        },
+        "rebuildOps": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "refused": {
+          "description": "Postgres: the changes that need a PostgresMigrationOp.",
+          "type": "array",
+          "items": {
+            "$ref": "common.schema.json#/$defs/change"
+          }
+        },
+        "migrationOps": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "mode": false
+      }
+    },
+    "stepChange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rule",
+        "class",
+        "field"
+      ],
+      "properties": {
+        "rule": {
+          "type": "string"
+        },
+        "class": {
+          "type": "string"
+        },
+        "field": {
+          "type": "string"
+        },
+        "destructive": {
+          "const": true
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "index",
+        "kind",
+        "object",
+        "name",
+        "done"
+      ],
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "kind": {
+          "enum": [
+            "statement",
+            "op",
+            "manual"
+          ]
+        },
+        "object": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "rule": {
+          "type": "string"
+        },
+        "class": {
+          "type": "string"
+        },
+        "destructive": {
+          "const": true
+        },
+        "changes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/stepChange"
+          }
+        },
+        "sql": {
+          "description": "A statement step's SQL, with passwords, secrets and tokens redacted.",
+          "type": "string"
+        },
+        "detail": {
+          "type": "string"
+        },
+        "op": {
+          "type": "string"
+        },
+        "applyRuns": {
+          "description": "An Op or manual step: whether yodel apply runs it.",
+          "type": "boolean"
+        },
+        "refused": {
+          "description": "Why yodel apply does not run this step.",
+          "type": "string"
+        },
+        "done": {
+          "description": "It succeeded in an earlier run and is not sent again.",
+          "type": "boolean"
+        }
+      }
+    },
+    "moved": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "part",
+          "message"
+        ],
+        "properties": {
+          "part": {
+            "enum": [
+              "environment",
+              "history",
+              "pending",
+              "live"
+            ]
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "versioned": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "environment",
+        "dialect",
+        "mode",
+        "applied",
+        "pending",
+        "problems",
+        "notes"
+      ],
+      "properties": {
+        "environment": {
+          "type": "string"
+        },
+        "dialect": {
+          "$ref": "common.schema.json#/$defs/dialect"
+        },
+        "mode": {
+          "const": "versioned"
+        },
+        "server": {
+          "$ref": "common.schema.json#/$defs/server"
+        },
+        "history": {
+          "description": "<database>.history, and on ClickHouse the topology and where it came from.",
+          "type": "string"
+        },
+        "applied": {
+          "description": "How many migrations the history records applied.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "pending": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "outOfOrder",
+              "steps"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "outOfOrder": {
+                "type": "boolean"
+              },
+              "resumeAt": {
+                "type": "integer"
+              },
+              "checks": {
+                "type": "array",
+                "items": {
+                  "$ref": "common.schema.json#/$defs/check"
+                }
+              },
+              "steps": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/step"
+                }
+              }
+            }
+          }
+        },
+        "problems": {
+          "description": "Directory problems, checksum mismatches, out-of-order migrations.",
+          "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "refusal": {
+          "$ref": "common.schema.json#/$defs/refusal"
+        },
+        "planDigest": {
+          "description": "The digest the migrations Op's gate binds; absent when apply would refuse or has nothing to do.",
+          "type": "string"
+        },
+        "policy": {
+          "$ref": "common.schema.json#/$defs/policy"
+        },
+        "op": {
+          "description": "The migrations Op.",
+          "type": "string"
+        },
+        "gate": {
+          "description": "The Op's gate.",
+          "type": "string"
+        },
+        "approve": {
+          "description": "The command a person runs to approve this plan. An agent prints it and never runs it.",
+          "type": "string"
+        },
+        "approval": {
+          "description": "The newest approval of the gate in chant's ledger.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "by",
+            "at",
+            "holds",
+            "sameDigest"
+          ],
+          "properties": {
+            "digest": {
+              "type": "string"
+            },
+            "by": {
+              "type": "string"
+            },
+            "at": {
+              "type": "string"
+            },
+            "holds": {
+              "type": "boolean"
+            },
+            "sameDigest": {
+              "type": "boolean"
+            },
+            "askedAgain": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "at"
+              ],
+              "properties": {
+                "at": {
+                  "type": "string"
+                },
+                "digest": {
+                  "type": "string"
+                }
+              }
+            },
+            "moved": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "confirmed",
+                "changes"
+              ],
+              "properties": {
+                "confirmed": {
+                  "type": "boolean"
+                },
+                "changes": {
+                  "$ref": "#/$defs/moved"
+                }
+              }
+            }
+          }
+        },
+        "opMissing": {
+          "description": "The project declares no migrations Op for the environment: the first line of how to declare one.",
+          "type": "string"
+        },
+        "wave": {
+          "description": "The environment's wave of the apply pipeline, when yodel.config.ts declares waves and names it.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "wave",
+            "gate",
+            "base",
+            "baseSource",
+            "destructiveSteps",
+            "waits",
+            "planDigest",
+            "digest",
+            "approve",
+            "promotions",
+            "blocked"
+          ],
+          "properties": {
+            "wave": {
+              "description": "1-based, in yodel.config.ts waves.",
+              "type": "integer",
+              "minimum": 1
+            },
+            "gate": {
+              "description": "The gate policy at the base commit.",
+              "enum": [
+                "always",
+                "on-destructive",
+                "never"
+              ]
+            },
+            "base": {
+              "type": "string"
+            },
+            "baseSource": {
+              "type": "string"
+            },
+            "destructiveSteps": {
+              "type": "array",
+              "items": {
+                "$ref": "apply.schema.json#/$defs/destructiveStep"
+              }
+            },
+            "waits": {
+              "description": "Under that gate, the wave waits for an approval of this plan.",
+              "type": "boolean"
+            },
+            "planDigest": {
+              "description": "The wave plan digest.",
+              "type": "string"
+            },
+            "digest": {
+              "description": "The set digest the wave's gate binds.",
+              "type": "string"
+            },
+            "approve": {
+              "description": "The chant approve command for the wave, for a person to run.",
+              "type": "string"
+            },
+            "promotions": {
+              "description": "Each environment this one requires (waves[].requires) and what its history records of each pending migration.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "env",
+                  "from",
+                  "migrations"
+                ],
+                "properties": {
+                  "env": {
+                    "type": "string"
+                  },
+                  "from": {
+                    "description": "Where the requirement is declared: yodel.config.ts, at the base commit, or both.",
+                    "type": "string"
+                  },
+                  "migrations": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": [
+                        "id",
+                        "checksum",
+                        "ran"
+                      ],
+                      "properties": {
+                        "id": {
+                          "type": "string"
+                        },
+                        "checksum": {
+                          "type": "string"
+                        },
+                        "ran": {
+                          "enum": [
+                            "applied",
+                            "not applied",
+                            "applied with another checksum"
+                          ]
+                        },
+                        "recorded": {
+                          "description": "The checksum the required environment recorded, when it differs.",
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "blocked": {
+              "description": "A pending migration has not run where it must first: the wave refuses it until it has.",
+              "type": "boolean"
+            }
+          }
+        },
+        "sinceLast": {
+          "description": "The pull request comment this plan replaces showed another digest: what moved since.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "digest",
+            "confirmed",
+            "changes"
+          ],
+          "properties": {
+            "digest": {
+              "type": "string"
+            },
+            "confirmed": {
+              "type": "boolean"
+            },
+            "changes": {
+              "$ref": "#/$defs/moved"
+            }
+          }
+        },
+        "notes": {
+          "$ref": "common.schema.json#/$defs/stringList"
+        }
+      }
+    }
+  }
+}

package/schemas/rebase.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/rebase.schema.json",
+  "title": "yodel rebase --json",
+  "description": "Version 1. The migration moved onto its new parent and every migration rewritten, or rebased false when there was nothing to move. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rebased"],
+      "properties": { "rebased": { "const": false } }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rebased", "moved", "from", "onto", "historiesChecked", "rewritten"],
+      "properties": {
+        "rebased": { "const": true },
+        "moved": { "type": "string" },
+        "from": { "type": ["string", "null"] },
+        "onto": { "type": "string" },
+        "historiesChecked": { "description": "The environments (--env) whose histories were checked so a migration that ran is never moved.", "$ref": "common.schema.json#/$defs/stringList" },
+        "rewritten": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "path", "oldParent", "parent", "oldChecksum", "checksum", "statements", "refused", "silences", "handEdited"],
+            "properties": {
+              "id": { "type": "string" },
+              "path": { "type": "string" },
+              "oldParent": { "type": ["string", "null"] },
+              "parent": { "type": ["string", "null"] },
+              "oldChecksum": { "type": "string" },
+              "checksum": { "type": "string" },
+              "statements": { "type": "integer", "minimum": 0 },
+              "refused": { "type": "boolean" },
+              "silences": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["step", "rule", "reason", "line"],
+                  "properties": { "step": { "type": "integer" }, "rule": { "type": "string" }, "reason": { "type": "string" }, "line": { "type": "integer" } }
+                }
+              },
+              "handEdited": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/schemas/repair.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/repair.schema.json",
+  "title": "yodel repair <env> <id> --reason <text> --json",
+  "description": "Version 1. The checksum recorded for an applied migration, with the reason, and whether migration.json's own checksum field was written again. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["repaired", "id", "environment", "oldChecksum", "newChecksum", "reason", "seq", "runId", "migrationJsonUpdated"],
+  "properties": {
+    "repaired": { "const": true },
+    "id": { "type": "string" },
+    "environment": { "type": "string" },
+    "oldChecksum": { "type": "string" },
+    "newChecksum": { "type": "string" },
+    "reason": { "type": "string" },
+    "seq": { "type": "integer" },
+    "runId": { "type": "string" },
+    "migrationJsonUpdated": { "type": "boolean" }
+  }
+}

package/schemas/report.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/report.schema.json",
+  "title": "yodel report [<env>...] --json",
+  "description": "Version 1. Every environment's migrations side by side, the audit log derived from each environment's history table and chant's gate ledger, and the gaps those sources show. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generatedAt", "project", "dialect", "migrations", "environments", "audit", "gaps"],
+  "properties": {
+    "version": { "const": 1 },
+    "generatedAt": { "type": "string", "description": "When the report was read, ISO 8601 UTC." },
+    "project": { "type": "string", "description": "The project directory." },
+    "dialect": { "enum": ["clickhouse", "postgres"] },
+    "migrations": { "type": "array", "items": { "type": "string" }, "description": "The migrations in chain order, then any an environment applied that the directory no longer has." },
+    "environments": { "type": "array", "items": { "$ref": "#/$defs/environment" } },
+    "audit": { "type": "array", "items": { "$ref": "#/$defs/entry" }, "description": "Every environment's audit entries, oldest first." },
+    "gaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } },
+    "auditFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "appended", "missing"],
+      "description": "With --audit: the file, how many entries were appended (0 with --check), and the entries of the file the sources no longer give.",
+      "properties": {
+        "path": { "type": "string" },
+        "appended": { "type": "integer", "minimum": 0 },
+        "missing": { "type": "array", "items": { "$ref": "#/$defs/entry" } }
+      }
+    }
+  },
+  "$defs": {
+    "environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "notes", "migrations"],
+      "properties": {
+        "name": { "type": "string" },
+        "history": { "type": "string", "description": "<database>.history" },
+        "op": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "gate"],
+          "properties": { "name": { "type": "string" }, "gate": { "type": "string" } }
+        },
+        "error": { "type": "string", "description": "Why the environment could not be read." },
+        "notes": { "type": "array", "items": { "type": "string" } },
+        "migrations": { "type": "array", "items": { "$ref": "#/$defs/migration" } }
+      }
+    },
+    "migration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "state", "inDirectory"],
+      "properties": {
+        "id": { "type": "string" },
+        "state": { "enum": ["applied", "pending", "failed", "started", "reverted"] },
+        "inDirectory": { "type": "boolean" },
+        "at": { "type": "string" },
+        "by": { "type": "string" },
+        "digest": { "type": "string" },
+        "approvedBy": { "type": "string" },
+        "approvedAt": { "type": "string" }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "at", "environment", "kind", "source"],
+      "description": "One audit entry; audit.jsonl holds one per line.",
+      "properties": {
+        "id": { "type": "string", "description": "A hash of the entry and its source: the same sources give the same id." },
+        "at": { "type": "string" },
+        "environment": { "type": "string" },
+        "kind": { "enum": ["approval-requested", "approved", "override", "silenced", "applied", "refused", "failed", "repaired", "reverted"] },
+        "by": { "type": "string" },
+        "migration": { "type": "string" },
+        "digest": { "type": "string" },
+        "detail": { "type": "string" },
+        "wave": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["gate", "digest", "status"],
+          "description": "On an applied entry a wave of the apply pipeline applied: the wave's gate, its set digest, and whether the wave was approved or its policy at the base needed no approval.",
+          "properties": { "gate": { "type": "string" }, "digest": { "type": "string" }, "status": { "enum": ["approved", "not-required"] } }
+        },
+        "source": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["ledger", "op", "gate"],
+              "properties": { "ledger": { "type": "string" }, "op": { "type": "string" }, "gate": { "type": "string" } }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["history", "seq", "run"],
+              "properties": { "history": { "type": "string" }, "seq": { "type": "integer", "minimum": 1 }, "run": { "type": "string" } }
+            }
+          ]
+        }
+      }
+    },
+    "gap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environment", "kind", "detail"],
+      "properties": {
+        "environment": { "type": "string" },
+        "kind": { "enum": ["history-row", "approval"] },
+        "detail": { "type": "string" }
+      }
+    }
+  }
+}