postgresai 0.16.0-rc.4 → 0.16.0

package/schemas/M002.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "M002 report schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["checkId", "checkTitle", "timestamptz", "nodes", "results"],
+  "properties": {
+    "contract_version": { "type": ["string", "null"] },
+    "summary": { "type": "object", "additionalProperties": false, "required": ["status", "message"], "properties": { "status": { "enum": ["ok", "warning", "info"] }, "message": { "type": "string" } } },
+    "version": { "type": ["string", "null"] },
+    "build_ts": { "type": ["string", "null"] },
+    "generation_mode": { "type": ["string", "null"] },
+    "checkId": { "const": "M002" },
+    "checkTitle": { "const": "Top queries by rows (I/O intensity)" },
+    "timestamptz": { "type": "string" },
+    "nodes": { "$ref": "#/$defs/nodes" },
+    "results": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/nodeResult" }
+    }
+  },
+  "$defs": {
+    "nodes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "standbys"],
+      "properties": {
+        "primary": { "type": "string" },
+        "standbys": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "postgresVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "server_version_num", "server_major_ver", "server_minor_ver"],
+      "properties": {
+        "version": { "type": "string" },
+        "server_version_num": { "type": "string" },
+        "server_major_ver": { "type": "string" },
+        "server_minor_ver": { "type": "string" }
+      }
+    },
+    "timeline": {
+      "type": "array",
+      "items": { "type": "integer" }
+    },
+    "hourlyNumbers": {
+      "type": "array",
+      "items": { "type": "number" }
+    },
+    "queryEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["queryid", "total_rows", "hourly_rows"],
+      "properties": {
+        "queryid": { "type": "string" },
+        "total_rows": { "type": "number" },
+        "hourly_rows": { "$ref": "#/$defs/hourlyNumbers" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "queries_returned",
+        "total_rows",
+        "total_rows_tracked_queries",
+        "total_rows_other",
+        "time_range_hours",
+        "hourly_timestamps",
+        "limit"
+      ],
+      "properties": {
+        "queries_returned": { "type": "integer" },
+        "total_rows": { "type": "number" },
+        "total_rows_tracked_queries": { "type": "number" },
+        "total_rows_other": { "type": "number" },
+        "time_range_hours": { "type": "integer" },
+        "hourly_timestamps": { "$ref": "#/$defs/timeline" },
+        "limit": { "type": "integer" }
+      }
+    },
+    "dbEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["top_queries", "other_rows_hourly", "summary"],
+      "properties": {
+        "top_queries": { "type": "array", "items": { "$ref": "#/$defs/queryEntry" } },
+        "other_rows_hourly": { "$ref": "#/$defs/hourlyNumbers" },
+        "summary": { "$ref": "#/$defs/summary" }
+      }
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/dbEntry" }
+    },
+    "nodeResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["data"],
+      "properties": {
+        "data": { "$ref": "#/$defs/data" },
+        "postgres_version": { "$ref": "#/$defs/postgresVersion" }
+      }
+    }
+  }
+}
+
+

package/schemas/M003.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "M003 report schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["checkId", "checkTitle", "timestamptz", "nodes", "results"],
+  "properties": {
+    "contract_version": { "type": ["string", "null"] },
+    "summary": { "type": "object", "additionalProperties": false, "required": ["status", "message"], "properties": { "status": { "enum": ["ok", "warning", "info"] }, "message": { "type": "string" } } },
+    "version": { "type": ["string", "null"] },
+    "build_ts": { "type": ["string", "null"] },
+    "generation_mode": { "type": ["string", "null"] },
+    "checkId": { "const": "M003" },
+    "checkTitle": { "const": "Top queries by I/O time" },
+    "timestamptz": { "type": "string" },
+    "nodes": { "$ref": "#/$defs/nodes" },
+    "results": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/nodeResult" }
+    }
+  },
+  "$defs": {
+    "nodes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "standbys"],
+      "properties": {
+        "primary": { "type": "string" },
+        "standbys": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "postgresVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "server_version_num", "server_major_ver", "server_minor_ver"],
+      "properties": {
+        "version": { "type": "string" },
+        "server_version_num": { "type": "string" },
+        "server_major_ver": { "type": "string" },
+        "server_minor_ver": { "type": "string" }
+      }
+    },
+    "timeline": {
+      "type": "array",
+      "items": { "type": "integer" }
+    },
+    "hourlyNumbers": {
+      "type": "array",
+      "items": { "type": "number" }
+    },
+    "queryEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "queryid",
+        "total_io_time_ms",
+        "total_read_time_ms",
+        "total_write_time_ms",
+        "hourly_io_time_ms",
+        "hourly_read_time_ms",
+        "hourly_write_time_ms"
+      ],
+      "properties": {
+        "queryid": { "type": "string" },
+        "total_io_time_ms": { "type": "number" },
+        "total_read_time_ms": { "type": "number" },
+        "total_write_time_ms": { "type": "number" },
+        "hourly_io_time_ms": { "$ref": "#/$defs/hourlyNumbers" },
+        "hourly_read_time_ms": { "$ref": "#/$defs/hourlyNumbers" },
+        "hourly_write_time_ms": { "$ref": "#/$defs/hourlyNumbers" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "queries_returned",
+        "total_io_time_tracked_queries_ms",
+        "total_io_time_other_ms",
+        "time_range_hours",
+        "hourly_timestamps",
+        "limit"
+      ],
+      "properties": {
+        "queries_returned": { "type": "integer" },
+        "total_io_time_tracked_queries_ms": { "type": "number" },
+        "total_io_time_other_ms": { "type": "number" },
+        "time_range_hours": { "type": "integer" },
+        "hourly_timestamps": { "$ref": "#/$defs/timeline" },
+        "limit": { "type": "integer" }
+      }
+    },
+    "dbEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "top_queries",
+        "other_io_time_hourly",
+        "other_read_time_hourly",
+        "other_write_time_hourly",
+        "summary"
+      ],
+      "properties": {
+        "top_queries": { "type": "array", "items": { "$ref": "#/$defs/queryEntry" } },
+        "other_io_time_hourly": { "$ref": "#/$defs/hourlyNumbers" },
+        "other_read_time_hourly": { "$ref": "#/$defs/hourlyNumbers" },
+        "other_write_time_hourly": { "$ref": "#/$defs/hourlyNumbers" },
+        "summary": { "$ref": "#/$defs/summary" }
+      }
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/dbEntry" }
+    },
+    "nodeResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["data"],
+      "properties": {
+        "data": { "$ref": "#/$defs/data" },
+        "postgres_version": { "$ref": "#/$defs/postgresVersion" }
+      }
+    }
+  }
+}
+
+

package/schemas/N001.schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "N001 report schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["checkId", "checkTitle", "timestamptz", "nodes", "results"],
+  "properties": {
+    "contract_version": { "type": ["string", "null"] },
+    "summary": { "type": "object", "additionalProperties": false, "required": ["status", "message"], "properties": { "status": { "enum": ["ok", "warning", "info"] }, "message": { "type": "string" } } },
+    "version": { "type": ["string", "null"] },
+    "build_ts": { "type": ["string", "null"] },
+    "generation_mode": { "type": ["string", "null"] },
+    "checkId": { "const": "N001" },
+    "checkTitle": { "const": "Wait events grouped by type and query" },
+    "timestamptz": { "type": "string" },
+    "nodes": { "$ref": "#/$defs/nodes" },
+    "results": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/nodeResult" }
+    }
+  },
+  "$defs": {
+    "nodes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "standbys"],
+      "properties": {
+        "primary": { "type": "string" },
+        "standbys": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "postgresVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "server_version_num", "server_major_ver", "server_minor_ver"],
+      "properties": {
+        "version": { "type": "string" },
+        "server_version_num": { "type": "string" },
+        "server_major_ver": { "type": "string" },
+        "server_minor_ver": { "type": "string" }
+      }
+    },
+    "timeline": {
+      "type": "array",
+      "description": "End timestamps for the one-hour buckets. Each value describes the preceding hour.",
+      "items": { "type": "integer" }
+    },
+    "hourlyIntegers": {
+      "type": "array",
+      "description": "Sampled active-session ticks per hour, not distinct wait-event starts.",
+      "items": { "type": "integer" }
+    },
+    "waitEventEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["occurrences"],
+      "properties": {
+        "occurrences": {
+          "type": "integer",
+          "description": "Sampled active-session ticks, not distinct wait-event starts."
+        }
+      }
+    },
+    "queryEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["query_id", "occurrences", "hourly_occurrences", "wait_events"],
+      "properties": {
+        "query_id": { "type": "string" },
+        "occurrences": {
+          "type": "integer",
+          "description": "Sampled active-session ticks, not distinct wait-event starts."
+        },
+        "hourly_occurrences": { "$ref": "#/$defs/hourlyIntegers" },
+        "wait_events": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/waitEventEntry" }
+        }
+      }
+    },
+    "waitTypeEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total_occurrences", "unique_queries", "queries_list"],
+      "properties": {
+        "total_occurrences": {
+          "type": "integer",
+          "description": "Sampled active-session ticks, not distinct wait-event starts."
+        },
+        "unique_queries": { "type": "integer" },
+        "queries_list": { "type": "array", "items": { "$ref": "#/$defs/queryEntry" } }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "time_range_hours",
+        "start_time",
+        "end_time",
+        "wait_event_types_count",
+        "total_occurrences",
+        "hourly_timestamps",
+        "sampling_semantics",
+        "sampling_note"
+      ],
+      "properties": {
+        "time_range_hours": { "type": "integer" },
+        "start_time": {
+          "type": "string",
+          "description": "Start of the first one-hour bucket."
+        },
+        "end_time": {
+          "type": "string",
+          "description": "End of the final one-hour bucket."
+        },
+        "wait_event_types_count": { "type": "integer" },
+        "total_occurrences": {
+          "type": "integer",
+          "description": "Sampled active-session ticks, not distinct wait-event starts."
+        },
+        "hourly_timestamps": { "$ref": "#/$defs/timeline" },
+        "sampling_semantics": {
+          "const": "sampled_active_session_ticks",
+          "description": "Identifies the cadence-dependent measurement represented by occurrence fields."
+        },
+        "sampling_note": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Explains cadence, scrape-gap, and non-event-count limitations."
+        }
+      }
+    },
+    "dbEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["wait_event_types", "summary"],
+      "properties": {
+        "wait_event_types": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/waitTypeEntry" }
+        },
+        "summary": { "$ref": "#/$defs/summary" }
+      }
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/dbEntry" }
+    },
+    "nodeResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["data"],
+      "properties": {
+        "data": { "$ref": "#/$defs/data" },
+        "postgres_version": { "$ref": "#/$defs/postgresVersion" }
+      }
+    }
+  }
+}

package/schemas/query.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Per-query report file schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["cluster_id", "query_id", "query_text", "nodes", "results", "timestamptz"],
+  "properties": {
+    "cluster_id": { "type": "string", "minLength": 1 },
+    "query_id": { "type": "string", "minLength": 1 },
+    "query_text": { "type": ["string", "null"] },
+    "nodes": { "$ref": "#/$defs/nodes" },
+    "results": { "$ref": "#/$defs/results" },
+    "time_range": { "$ref": "#/$defs/timeRange" },
+    "timestamptz": { "type": "string" }
+  },
+  "$defs": {
+    "nodes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primary", "standbys"],
+      "properties": {
+        "primary": { "type": ["string", "null"] },
+        "standbys": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "timeRange": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["hours", "start_time", "end_time"],
+      "properties": {
+        "hours": { "type": "integer", "minimum": 1 },
+        "start_time": { "type": "string" },
+        "end_time": { "type": "string" }
+      }
+    },
+    "metricValue": { "type": ["number", "integer"] },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/metricValue" }
+    },
+    "dbEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["metrics"],
+      "properties": {
+        "metrics": { "$ref": "#/$defs/metrics" }
+      }
+    },
+    "nodeEntry": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/dbEntry" }
+    },
+    "results": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/nodeEntry" }
+    }
+  }
+}
+
+

package/CHANGELOG.md

@@ -1,11 +0,0 @@
-# Changelog
-
-## Unreleased
-
-### Fixed
-
-- `checkup --markdown` previously performed server-side conversion and sent the
-  full report JSON to the PostgresAI API even when `--no-upload` was set. The
-  flags are now mutually exclusive, and `--no-upload` prevents report data from
-  being sent to the PostgresAI API. Use `--json` or `--output` for local-only
-  output.