@intentius/sql-yodeler 0.2.0 → 0.4.0

package/schemas/lint.schema.json

@@ -152,6 +152,10 @@
         },
         "skipped": {
           "$ref": "common.schema.json#/$defs/stringList"
+        },
+        "checkpoint": {
+          "description": "A checkpoint, replayed on its own into an empty database after the chain.",
+          "const": true
         }
       }
     },

package/schemas/new.schema.json

@@ -24,7 +24,13 @@
             "type": "object",
             "additionalProperties": false,
             "required": ["op", "object", "name", "rules"],
-            "properties": { "op": { "type": "string" }, "object": { "type": "string" }, "name": { "type": "string" }, "rules": { "$ref": "common.schema.json#/$defs/stringList" } }
+            "properties": {
+              "op": { "type": "string" },
+              "object": { "type": "string" },
+              "name": { "type": "string" },
+              "rules": { "$ref": "common.schema.json#/$defs/stringList" },
+              "retain": { "description": "A column rename or type change, or a rebuild: how long it keeps the old column or table after the switch (--retain).", "type": "string" }
+            }
           }
         },
         "manual": {
@@ -38,11 +44,43 @@
           }
         },
         "hints": { "$ref": "common.schema.json#/$defs/stringList" },
-        "checks": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/check" } }
+        "checks": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/check" } },
+        "prechecks": {
+          "description": "Postgres: the statements that can fail on the rows already there, each with the pre-check yodel apply runs before the first statement; it must return 0.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "step", "sql", "detail"],
+            "properties": {
+              "name": { "type": "string" },
+              "step": { "type": "integer", "minimum": 0 },
+              "sql": { "type": "string" },
+              "detail": { "type": "string" }
+            }
+          }
+        },
+        "access": {
+          "description": "The steps about access control (Postgres: policies, row-level security, roles, grants, revokes, default privileges; ClickHouse: users, roles, row policies, grants, revokes), each with its rule and class; takesAway says why one takes access away.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["step", "object", "name"],
+            "properties": {
+              "step": { "type": "integer", "minimum": 0 },
+              "object": { "type": "string" },
+              "name": { "type": "string" },
+              "rule": { "type": "string" },
+              "class": { "type": "string" },
+              "takesAway": { "type": "string" }
+            }
+          }
+        }
       }
     },
     "template": {
-      "description": "--backfill named a file that is not there: the template was written to it, and no migration.",
+      "description": "--backfill's form (backfills/<name>.json, or the file it names) is not there: the template was written to it, and no migration.",
       "type": "object",
       "additionalProperties": false,
       "required": ["written", "template"],

package/schemas/plan.schema.json

@@ -66,6 +66,33 @@
             "type": "object"
           }
         },
+        "access": {
+          "description": "Whether access control is managed in the environment (environments.<env>.access in yodel.config.ts, else sql.profiles.<env>.access) and the plan's access changes: on Postgres policies, row-level security, roles and privileges; on ClickHouse users, roles, row policies and grants. byHand marks a revoke of a privilege no declaration grants: one granted by hand (or whose declaration was deleted), which the apply takes away. On ClickHouse every revoke is one.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["managed", "source", "changes"],
+          "properties": {
+            "managed": { "type": "boolean" },
+            "source": { "type": "string" },
+            "changes": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["object", "rule", "class", "field"],
+                "properties": {
+                  "object": { "type": "string" },
+                  "rule": { "type": "string" },
+                  "class": { "type": "string" },
+                  "field": { "type": "string" },
+                  "before": {},
+                  "after": {},
+                  "byHand": { "const": true }
+                }
+              }
+            }
+          }
+        },
         "mode": false
       }
     },
@@ -278,6 +305,10 @@
           "description": "The command a person runs to approve this plan. An agent prints it and never runs it.",
           "type": "string"
         },
+        "approvalMode": {
+          "description": "Which approvals of the migrations Op's gate count, as yodel.config.ts at the base commit has it, when not ledger: sealed counts only an approval sealed by a key the signers file at base lists for its approver.",
+          "enum": ["sealed"]
+        },
         "approval": {
           "description": "The newest approval of the gate in chant's ledger.",
           "type": "object",
@@ -334,6 +365,10 @@
                   "$ref": "#/$defs/moved"
                 }
               }
+            },
+            "uncounted": {
+              "description": "The gate's approval mode does not count it (under sealed, it is not sealed by a signer at the base commit), and why.",
+              "type": "string"
             }
           }
         },
@@ -341,6 +376,128 @@
           "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"
+            },
+            "approval": {
+              "description": "Which approvals of the wave's digest count, as yodel.config.ts at the base commit has the wave, when not ledger.",
+              "enum": ["pr-review", "sealed"]
+            },
+            "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",

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", "step"] },
+        "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" }
+      }
+    }
+  }
+}

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

@@ -2,10 +2,18 @@
   "$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. 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).",
+  "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",
-  "$ref": "#/$defs/report",
-  "unevaluatedProperties": false,
+  "oneOf": [
+    {
+      "type": "object",
+      "$ref": "#/$defs/report",
+      "unevaluatedProperties": false
+    },
+    {
+      "$ref": "#/$defs/tenants"
+    }
+  ],
   "$defs": {
     "step": {
       "type": "object",
@@ -164,6 +172,13 @@
               "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": [
                   {
@@ -297,6 +312,20 @@
             }
           }
         },
+        "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"
@@ -305,6 +334,38 @@
           "$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
+        }
+      }
     }
   }
 }

package/schemas/test.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/sql-yodeler/schemas/v1/test.schema.json",
+  "title": "yodel test --json",
+  "description": "Version 1. The cases of tests/*.test.ts, each run on a database built from the migrations on a throwaway server: what passed, what failed and why. Within a version, fields are only added; a reader ignores fields it does not know.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["files", "summary", "cases"],
+  "properties": {
+    "environment": { "description": "The throwaway server's profile.", "type": "string" },
+    "dialect": { "enum": ["clickhouse", "postgres"] },
+    "where": { "description": "The server, without credentials.", "type": "string" },
+    "scope": { "description": "The databases (ClickHouse) or schemas (Postgres) each case empties and builds.", "$ref": "common.schema.json#/$defs/stringList" },
+    "reset": { "description": "The target held what the history names, and was emptied first (--reset).", "type": "boolean" },
+    "files": { "description": "The test files, relative to the project directory.", "$ref": "common.schema.json#/$defs/stringList" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["passed", "failed", "errors"],
+      "properties": { "passed": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 }, "errors": { "type": "integer", "minimum": 0 } }
+    },
+    "cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["file", "name", "status", "ms", "failures", "before", "after"],
+        "properties": {
+          "file": { "type": "string" },
+          "name": { "type": "string" },
+          "status": { "description": "passed: every expectation held. failed: one did not. error: the case could not run (a migration or seed statement failed, an unknown migration id).", "enum": ["passed", "failed", "error"] },
+          "ms": { "type": "integer", "minimum": 0 },
+          "failures": { "description": "The expectations that did not hold, one line each.", "$ref": "common.schema.json#/$defs/stringList" },
+          "error": { "type": "string" },
+          "before": { "description": "The migrations replayed before the seed.", "$ref": "common.schema.json#/$defs/stringList" },
+          "after": { "description": "The migrations run after the seed, with their steps.", "$ref": "common.schema.json#/$defs/stringList" }
+        }
+      }
+    }
+  }
+}