Skip to content

armgit / dbx

Public Imported from GitHub
0

25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。

11.1 KB
Raw Blame
use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use crate::types::{ColumnInfo, ForeignKeyInfo, IndexInfo};

/// The normalized description of a relational schema. Every documentation
/// output (DBML, HTML, future changelog records) is a serializer over this.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SchemaSnapshot {
    /// Guards viewer/data skew. Always 1 for now; bump only on a breaking
    /// change to this model.
    pub format_version: u32,
    pub project: ProjectMeta,
    pub tables: Vec<DocTable>,
    pub relationships: Vec<Relationship>,
    #[serde(default)]
    pub groups: Vec<TableGroup>,
    #[serde(default)]
    pub enums: Vec<DocEnum>,
    #[serde(default)]
    pub warnings: Vec<SnapshotWarning>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ProjectMeta {
    pub name: String,
    pub database_type: String,
    pub database: Option<String>,
    pub schemas: Vec<String>,
    /// RFC3339.
    pub generated_at: String,
    /// Markdown. Rendered as the documentation landing page.
    pub note: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DocTable {
    pub schema: Option<String>,
    pub name: String,
    pub kind: TableKind,
    pub columns: Vec<ColumnInfo>,
    pub indexes: Vec<IndexInfo>,
    pub foreign_keys: Vec<ForeignKeyInfo>,
    /// References `TableGroup::id`. Populated in Part 2.
    pub group_id: Option<String>,
    /// Merged note: local annotation, else database comment.
    pub note: Option<String>,
    pub note_source: NoteSource,
    /// The database comment a local note is overriding, if any. Shown on
    /// hover so a later `COMMENT ON` improvement is never invisible.
    pub shadowed_note: Option<String>,
    #[serde(default)]
    pub column_notes: BTreeMap<String, ColumnNote>,
    pub estimated_rows: Option<i64>,
    pub view_definition: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct TableGroup {
    /// Stable slug. Survives a display-name change.
    pub id: String,
    pub name: String,
    /// 0..=359. Lightness and chroma are theme-controlled in CSS, so any
    /// hue is legible on both grounds by construction.
    pub hue: u16,
    pub note: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ColumnNote {
    pub note: String,
    pub source: NoteSource,
    pub shadowed: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DocEnum {
    pub schema: Option<String>,
    pub name: String,
    pub values: Vec<String>,
    pub note: Option<String>,
    /// True when synthesized from a MySQL inline `ENUM(...)` column rather
    /// than read from a named database type.
    #[serde(default)]
    pub synthesized: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Relationship {
    pub id: String,
    pub name: Option<String>,
    pub from: FieldRef,
    pub to: FieldRef,
    pub cardinality: Cardinality,
    pub on_update: Option<String>,
    pub on_delete: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FieldRef {
    pub schema: Option<String>,
    pub table: String,
    pub column: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum TableKind {
    Table,
    View,
    MaterializedView,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum NoteSource {
    /// Read from a database COMMENT.
    Database,
    /// Authored in DBX, stored in the notes file.
    Local,
    None,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum Cardinality {
    OneToOne,
    ManyToOne,
}

/// Why a snapshot is less complete than it looks. Rendered as a dismissible
/// banner rather than left for the reader to discover.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", tag = "kind")]
pub enum SnapshotWarning {
    TableSkipped { table: String, reason: String },
    NoForeignKeyMetadata { engine: String },
    CommentsUnsupported { engine: String },
    OrphanedNotes { count: usize },
    DbmlOmitted { table: String, item: String, reason: String },
}

/// Human-readable warning text for headless callers.
///
/// The viewer translates these through its own `docs.warnings` namespace; the
/// CLI has no i18n runtime, so the English prose lives here. Without it the
/// only thing to print is the derived `Debug` form, which exposes the struct
/// shape and reads like a panic rather than like advice.
impl std::fmt::Display for SnapshotWarning {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::TableSkipped { table, reason } => {
                write!(formatter, "{table} was skipped: {reason}. It is missing from this documentation.")
            }
            Self::NoForeignKeyMetadata { engine } => {
                write!(
                    formatter,
                    "{engine} does not report foreign key metadata, so no relationships could be derived."
                )
            }
            Self::CommentsUnsupported { engine } => write!(
                formatter,
                "{engine} does not support table or column comments, so every description comes from your own notes."
            ),
            Self::OrphanedNotes { count } => write!(
                formatter,
                "{count} note(s) refer to a table or column that no longer exists. Nothing was deleted."
            ),
            Self::DbmlOmitted { table, item, reason } => {
                write!(formatter, "{item} on {table} is documented but omitted from the DBML: {reason}.")
            }
        }
    }
}

impl DocTable {
    /// `schema.name` when a schema is present, otherwise bare `name`.
    pub fn qualified_name(&self) -> String {
        match &self.schema {
            Some(schema) if !schema.is_empty() => format!("{schema}.{}", self.name),
            _ => self.name.clone(),
        }
    }
}

impl FieldRef {
    pub fn qualified_table(&self) -> String {
        match &self.schema {
            Some(schema) if !schema.is_empty() => format!("{schema}.{}", self.table),
            _ => self.table.clone(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample() -> SchemaSnapshot {
        SchemaSnapshot {
            format_version: 1,
            project: ProjectMeta {
                name: "Ecommerce".to_string(),
                database_type: "PostgreSQL".to_string(),
                database: Some("shop".to_string()),
                schemas: vec!["public".to_string()],
                generated_at: "2026-08-02T12:00:00Z".to_string(),
                note: None,
            },
            tables: vec![DocTable {
                schema: Some("public".to_string()),
                name: "orders".to_string(),
                kind: TableKind::Table,
                columns: vec![],
                indexes: vec![],
                foreign_keys: vec![],
                group_id: None,
                note: Some("Checkout rows.".to_string()),
                note_source: NoteSource::Database,
                shadowed_note: None,
                column_notes: BTreeMap::new(),
                estimated_rows: Some(2_400_000),
                view_definition: None,
            }],
            relationships: vec![],
            groups: vec![],
            enums: vec![],
            warnings: vec![],
        }
    }

    #[test]
    fn snapshot_round_trips_through_json() {
        let original = sample();
        let json = serde_json::to_string(&original).expect("serialize");
        let parsed: SchemaSnapshot = serde_json::from_str(&json).expect("deserialize");

        assert_eq!(parsed.format_version, 1);
        assert_eq!(parsed.project.name, "Ecommerce");
        assert_eq!(parsed.tables.len(), 1);
        assert_eq!(parsed.tables[0].name, "orders");
        assert_eq!(parsed.tables[0].note.as_deref(), Some("Checkout rows."));
        assert_eq!(parsed.tables[0].estimated_rows, Some(2_400_000));
    }

    #[test]
    fn snapshot_json_uses_camel_case_keys() {
        let json = serde_json::to_string(&sample()).expect("serialize");
        assert!(json.contains("\"formatVersion\""), "got: {json}");
        assert!(json.contains("\"generatedAt\""), "got: {json}");
        assert!(json.contains("\"noteSource\""), "got: {json}");
    }

    #[test]
    fn table_kind_serializes_as_screaming_snake_case() {
        let json = serde_json::to_string(&TableKind::MaterializedView).expect("serialize");
        assert_eq!(json, "\"MATERIALIZED_VIEW\"");
    }

    #[test]
    fn every_warning_renders_as_prose() {
        // `dbx dbml` prints these to stderr. The derived Debug form leaks the
        // struct shape (`DbmlOmitted { table: "public.t", .. }`), which reads
        // as a crash report rather than as advice, so Display is what the CLI
        // must use. The wording tracks the viewer's own warning strings.
        let cases = [
            (
                SnapshotWarning::TableSkipped { table: "public.orders".into(), reason: "permission denied".into() },
                "public.orders was skipped: permission denied. It is missing from this documentation.",
            ),
            (
                SnapshotWarning::NoForeignKeyMetadata { engine: "ClickHouse".into() },
                "ClickHouse does not report foreign key metadata, so no relationships could be derived.",
            ),
            (
                SnapshotWarning::CommentsUnsupported { engine: "SQLite".into() },
                "SQLite does not support table or column comments, so every description comes from your own notes.",
            ),
            (
                SnapshotWarning::OrphanedNotes { count: 3 },
                "3 note(s) refer to a table or column that no longer exists. Nothing was deleted.",
            ),
            (
                SnapshotWarning::DbmlOmitted {
                    table: "public.orders".into(),
                    item: "idx_partial".into(),
                    reason: "partial index filter has no DBML equivalent".into(),
                },
                "idx_partial on public.orders is documented but omitted from the DBML: partial index filter has no DBML equivalent.",
            ),
        ];

        for (warning, expected) in cases {
            assert_eq!(warning.to_string(), expected);
        }
    }

    #[test]
    fn a_warning_never_renders_as_its_debug_form() {
        // The regression this guards: reverting the CLI to `{warning:?}` is a
        // one-character edit that still compiles and still prints something.
        let warning = SnapshotWarning::OrphanedNotes { count: 1 };
        assert!(!warning.to_string().contains('{'), "got: {warning}");
        assert_ne!(warning.to_string(), format!("{warning:?}"));
    }
}