Skip to main content

appstruct_migrate/
lint.rs

1use crate::{ExecutionRisk, MigrationPlan, SchemaChange, SchemaRisk};
2use serde::Serialize;
3
4#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
5#[serde(rename_all = "snake_case")]
6pub enum LintSeverity {
7    Warning,
8    Error,
9}
10
11#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
12pub struct MigrationLint {
13    pub code: &'static str,
14    pub severity: LintSeverity,
15    pub message: String,
16}
17
18#[must_use]
19pub fn lint_plan(plan: &MigrationPlan) -> Vec<MigrationLint> {
20    let mut issues = Vec::new();
21    for planned in &plan.changes {
22        let label = change_label(&planned.change);
23        if planned.risk.schema == SchemaRisk::Destructive {
24            issues.push(MigrationLint {
25                code: "AS4201",
26                severity: LintSeverity::Error,
27                message: format!("{label} is destructive; write and review a manual migration"),
28            });
29        } else if planned.risk.execution == ExecutionRisk::MayLock {
30            issues.push(MigrationLint {
31                code: "AS4202",
32                severity: LintSeverity::Warning,
33                message: format!(
34                    "{label} may lock existing rows; schedule it outside peak traffic"
35                ),
36            });
37        } else if planned.risk.execution == ExecutionRisk::ManualReview {
38            issues.push(MigrationLint {
39                code: "AS4203",
40                severity: LintSeverity::Error,
41                message: format!("{label} requires manual SQL review before applying"),
42            });
43        }
44        if let SchemaChange::AddColumn { table, column } = &planned.change
45            && !column.nullable
46            && column.default.is_none()
47            && column.generated.is_none()
48        {
49            issues.push(MigrationLint {
50                code: "AS4204",
51                severity: LintSeverity::Error,
52                message: format!(
53                    "adding non-null column `{}.{}` without a default can fail on existing rows",
54                    table, column.name
55                ),
56            });
57        }
58    }
59    issues.sort_by(|left, right| {
60        left.code
61            .cmp(right.code)
62            .then(left.message.cmp(&right.message))
63    });
64    issues
65}
66
67fn change_label(change: &SchemaChange) -> String {
68    match change {
69        SchemaChange::AddTable { table } => format!("add table `{}`", table.name),
70        SchemaChange::RemoveTable { table } => format!("remove table `{}`", table.name),
71        SchemaChange::RenameTable { before, after } => {
72            format!("rename table `{}` to `{}`", before.name, after.name)
73        }
74        SchemaChange::AddColumn { table, column } => {
75            format!("add column `{table}.{}`", column.name)
76        }
77        SchemaChange::RemoveColumn { table, column } => {
78            format!("remove column `{table}.{}`", column.name)
79        }
80        SchemaChange::AlterColumn { table, after, .. } => {
81            format!("alter column `{table}.{}`", after.name)
82        }
83        SchemaChange::AddUniqueConstraint { constraint } => {
84            format!("add unique constraint `{}`", constraint.id)
85        }
86        SchemaChange::RemoveUniqueConstraint { constraint } => {
87            format!("remove unique constraint `{}`", constraint.id)
88        }
89        SchemaChange::AddIndex { index } => format!("add index `{}`", index.id),
90        SchemaChange::RemoveIndex { index } => format!("remove index `{}`", index.id),
91        SchemaChange::AddSeed { seed } => format!("add seed `{}`", seed.id),
92        SchemaChange::RemoveSeed { seed } => format!("remove seed `{}`", seed.id),
93        SchemaChange::AddForeignKey { foreign_key } => {
94            format!("add foreign key `{}`", foreign_key.id)
95        }
96        SchemaChange::RemoveForeignKey { foreign_key } => {
97            format!("remove foreign key `{}`", foreign_key.id)
98        }
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105    use crate::{
106        ChangeRisk, ColumnSchema, DatabaseType, ExecutionRisk, ForeignKeySchema, IndexSchema,
107        PlannedChange, SchemaRisk, SeedSchema, TableSchema, UniqueConstraintSchema,
108    };
109    use appstruct_ir::OnDeleteIr;
110
111    fn table() -> TableSchema {
112        TableSchema {
113            id: "notes".to_owned(),
114            name: "notes".to_owned(),
115            columns: Vec::new(),
116        }
117    }
118
119    fn column() -> ColumnSchema {
120        ColumnSchema {
121            id: "notes.id".to_owned(),
122            name: "id".to_owned(),
123            data_type: DatabaseType::Uuid,
124            nullable: false,
125            primary_key: true,
126            unique: false,
127            default: None,
128            generated: None,
129        }
130    }
131
132    #[test]
133    #[allow(clippy::too_many_lines)]
134    fn labels_and_risk_classes_cover_every_change_kind() {
135        let table = table();
136        let column = column();
137        let constraint = UniqueConstraintSchema {
138            id: "notes.email".to_owned(),
139            table: "notes".to_owned(),
140            columns: vec!["email".to_owned()],
141        };
142        let index = IndexSchema {
143            id: "notes.email".to_owned(),
144            table: "notes".to_owned(),
145            columns: vec!["email".to_owned()],
146            unique: false,
147            method: appstruct_ir::IndexMethod::Btree,
148            operator_class: None,
149            predicate: None,
150        };
151        let seed = SeedSchema {
152            id: "notes.demo".to_owned(),
153            table: "notes".to_owned(),
154            values: Vec::new(),
155        };
156        let foreign_key = ForeignKeySchema {
157            id: "notes.author".to_owned(),
158            source_table: "notes".to_owned(),
159            source_columns: vec!["author_id".to_owned()],
160            target_table: "users".to_owned(),
161            target_columns: vec!["id".to_owned()],
162            unique: false,
163            on_delete: OnDeleteIr::Restrict,
164        };
165        let changes = [
166            SchemaChange::AddTable {
167                table: table.clone(),
168            },
169            SchemaChange::RemoveTable {
170                table: table.clone(),
171            },
172            SchemaChange::RenameTable {
173                before: table.clone(),
174                after: table,
175            },
176            SchemaChange::AddColumn {
177                table: "notes".to_owned(),
178                column: column.clone(),
179            },
180            SchemaChange::RemoveColumn {
181                table: "notes".to_owned(),
182                column: column.clone(),
183            },
184            SchemaChange::AlterColumn {
185                table: "notes".to_owned(),
186                before: column.clone(),
187                after: column,
188            },
189            SchemaChange::AddUniqueConstraint {
190                constraint: constraint.clone(),
191            },
192            SchemaChange::RemoveUniqueConstraint { constraint },
193            SchemaChange::AddIndex {
194                index: index.clone(),
195            },
196            SchemaChange::RemoveIndex { index },
197            SchemaChange::AddSeed { seed: seed.clone() },
198            SchemaChange::RemoveSeed { seed },
199            SchemaChange::AddForeignKey {
200                foreign_key: foreign_key.clone(),
201            },
202            SchemaChange::RemoveForeignKey { foreign_key },
203        ];
204        let plan = MigrationPlan {
205            changes: changes
206                .into_iter()
207                .enumerate()
208                .map(|(index, change)| PlannedChange {
209                    change,
210                    risk: ChangeRisk {
211                        schema: if index == 0 {
212                            SchemaRisk::Destructive
213                        } else if index == 1 {
214                            SchemaRisk::RequiresInput
215                        } else {
216                            SchemaRisk::NonDestructive
217                        },
218                        execution: if index == 1 {
219                            ExecutionRisk::ManualReview
220                        } else if index == 2 {
221                            ExecutionRisk::MayLock
222                        } else {
223                            ExecutionRisk::Online
224                        },
225                    },
226                })
227                .collect(),
228        };
229        let issues = lint_plan(&plan);
230        assert!(issues.iter().any(|issue| issue.code == "AS4201"));
231        assert!(issues.iter().any(|issue| issue.code == "AS4202"));
232        assert!(issues.iter().any(|issue| issue.code == "AS4203"));
233        for change in &plan.changes {
234            assert_ne!(change_label(&change.change), "");
235        }
236    }
237}