use crate::structure::data::explain::Explain;
use crate::structure::raw::{schema_profile_from_hint, PostgresSchemaProfile, RawExplain, RawPlan};
use crate::structure::tree::PlanTree;
use crate::VisualizeError;
#[derive(Debug, Clone, Default)]
pub struct ParseOptions {
pub postgres_version_hint: Option<String>,
}
impl ParseOptions {
pub fn new() -> Self {
Self::default()
}
pub fn with_postgres_version_hint(mut self, hint: impl Into<String>) -> Self {
self.postgres_version_hint = Some(hint.into());
self
}
pub fn schema_profile_hint(&self) -> Option<PostgresSchemaProfile> {
self.postgres_version_hint
.as_deref()
.and_then(schema_profile_from_hint)
}
}
pub fn parse_raw_explains(input: &str) -> Result<Vec<RawExplain>, VisualizeError> {
serde_json::from_str(input).map_err(VisualizeError::InvalidJson)
}
pub fn build_domain_explain(raw: RawExplain) -> Result<Explain, VisualizeError> {
raw.into_domain()
}
pub fn build_domain_explain_with(
raw: RawExplain,
options: &ParseOptions,
) -> Result<Explain, VisualizeError> {
let mut effective_profile = raw.schema_profile();
if effective_profile == PostgresSchemaProfile::Unknown {
if let Some(hinted) = options.schema_profile_hint() {
effective_profile = hinted;
}
}
let RawExplain { metadata, plan } = raw;
let plan = plan
.ok_or(VisualizeError::MissingPlan)?
.into_domain(effective_profile)?;
let postgres_version = metadata
.postgres_version
.clone()
.or_else(|| options.postgres_version_hint.clone());
Ok(Explain {
plan,
postgres_version,
planning_time: metadata.planning_time,
execution_time: metadata.execution_time,
..Default::default()
})
}
pub fn validate_plan_tree(explain: Explain) -> Result<Explain, VisualizeError> {
let tree = PlanTree::new(explain.plan.clone())?;
Ok(Explain {
plan: tree.into_root(),
..explain
})
}
pub fn parse_explain_document(input: &str) -> Result<Explain, VisualizeError> {
parse_explain_document_with(input, &ParseOptions::default())
}
pub fn parse_explain_document_with(
input: &str,
options: &ParseOptions,
) -> Result<Explain, VisualizeError> {
let raw_explain = parse_raw_explains(input)?
.into_iter()
.next()
.ok_or(VisualizeError::EmptyExplainArray)?;
let mut explain = build_domain_explain_with(raw_explain.clone(), options)?;
if raw_explain.schema_profile() == PostgresSchemaProfile::Unknown
&& options.schema_profile_hint().is_none()
{
explain.postgres_version = None;
}
validate_plan_tree(explain)
}
#[allow(dead_code)]
fn _ensure_raw_plan_visible(_: &RawPlan) {}
#[cfg(test)]
mod tests {
use super::*;
const PG12_PAYLOAD_NO_VERSION: &str = r#"[{"Plan":{"Node Type":"Seq Scan","Total Cost":1.0,"Actual Total Time":0.5,"Actual Rows":1,"Actual Loops":1,"IO Read Time":1.5}}]"#;
#[test]
fn version_hint_picks_legacy_io_timing_for_pg12() {
let options = ParseOptions::new().with_postgres_version_hint("12");
let explain = parse_explain_document_with(PG12_PAYLOAD_NO_VERSION, &options)
.expect("parse with hint");
assert!((explain.plan.io_timing.io_read_time - 1.5).abs() < 1e-9);
assert_eq!(explain.postgres_version.as_deref(), Some("12"));
}
#[test]
fn version_hint_picks_modern_io_timing_for_pg13_plus() {
let options = ParseOptions::new().with_postgres_version_hint("PostgreSQL 16.1");
let explain = parse_explain_document_with(PG12_PAYLOAD_NO_VERSION, &options)
.expect("parse with hint");
assert!((explain.plan.io_timing.io_read_time - 1.5).abs() < 1e-9);
assert_eq!(explain.postgres_version.as_deref(), Some("PostgreSQL 16.1"));
}
#[test]
fn metadata_version_in_payload_wins_over_hint() {
let payload = r#"[{"PostgreSQL Version":"PostgreSQL 12","Plan":{"Node Type":"Seq Scan","Total Cost":1.0,"Actual Total Time":0.5,"Actual Rows":1,"Actual Loops":1}}]"#;
let options = ParseOptions::new().with_postgres_version_hint("PostgreSQL 16.1");
let explain = parse_explain_document_with(payload, &options).expect("parse");
assert_eq!(explain.postgres_version.as_deref(), Some("PostgreSQL 12"));
}
#[test]
fn invalid_hint_is_ignored_and_does_not_error() {
let options = ParseOptions::new().with_postgres_version_hint("not-a-version");
let explain = parse_explain_document_with(PG12_PAYLOAD_NO_VERSION, &options)
.expect("parse with bad hint");
assert!(explain.postgres_version.is_none());
}
#[test]
fn no_hint_preserves_existing_unknown_profile_behavior() {
let explain = parse_explain_document(PG12_PAYLOAD_NO_VERSION).expect("parse no hint");
assert!(explain.postgres_version.is_none());
}
}