Skip to main content

gaman_core/
offline_planner.rs

1//! Offline migration planner for replaying committed migrations and generating the next migration.
2//!
3//! The planner owns the offline lifecycle: replay baseline, normalize schemas, clarify risky
4//! operations, canonicalize through dialect preparation, diff, and render SQL on request.
5
6use thiserror::Error;
7
8use crate::clarifier::{
9    Clarifier, ClarifyError, ClarifyResult, Decision, TypeResolution, non_type_decisions,
10    resolve_unknown_types,
11};
12use crate::dialects::{Dialect, DialectError};
13use crate::diff::{DiffEngine, DiffError};
14use crate::graphs::{GraphError, MigrationGraph};
15use crate::migrations::Migration;
16use crate::replay::{ReplayEngine, ReplaySources, compute_deps, deterministic_name_from_ops};
17use crate::sql_plan::{SqlPlanError, SqlPlanRenderer};
18use crate::states::{ReplayError, Schema};
19
20#[derive(Debug, Error)]
21pub enum OfflineError {
22    #[error(transparent)]
23    Graph(#[from] GraphError),
24    #[error(transparent)]
25    Diff(#[from] DiffError),
26    #[error(transparent)]
27    Clarifier(#[from] ClarifyError),
28    #[error("clarification needed for migration generation")]
29    NeedsInput(Vec<crate::clarifier::Clarification>),
30    #[error(transparent)]
31    Dialect(#[from] DialectError),
32    #[error(transparent)]
33    Replay(#[from] ReplayError),
34    #[error(transparent)]
35    SqlPlan(#[from] SqlPlanError),
36    #[error("schema validation failed: {0}")]
37    Schema(String),
38}
39
40#[derive(Debug, Clone)]
41pub struct OfflinePlanner {
42    dialect: Dialect,
43    migrations: Vec<Migration>,
44}
45
46#[derive(Copy, Clone)]
47pub struct EmbeddedMigrations {
48    pub files: &'static [(&'static str, &'static str)],
49    pub dir: &'static str,
50    pub children: &'static [(&'static str, &'static EmbeddedMigrations)],
51}
52
53impl OfflinePlanner {
54    pub fn new(dialect: Dialect) -> Self {
55        Self {
56            dialect,
57            migrations: Vec::new(),
58        }
59    }
60
61    pub fn from_migrations(mut self, migrations: Vec<Migration>) -> Self {
62        self.migrations = migrations;
63        self
64    }
65
66    pub fn replay(&self) -> Result<Schema, OfflineError> {
67        self.replay_with_sources()?
68            .schema
69            .prepare(self.dialect)
70            .map_err(|err| OfflineError::Schema(err.to_string()))
71    }
72
73    pub fn make_migration(
74        &self,
75        desired_schema: Schema,
76        decisions: &[Decision],
77    ) -> Result<Option<Migration>, OfflineError> {
78        self.make_named_migration_filtered(desired_schema, None, decisions, &[])
79    }
80
81    /// Generates one migration containing only roots selected by invocation-scoped filters.
82    pub fn make_migration_filtered(
83        &self,
84        desired_schema: Schema,
85        decisions: &[Decision],
86        filters: &[crate::EntityFilter],
87    ) -> Result<Option<Migration>, OfflineError> {
88        self.make_named_migration_filtered(desired_schema, None, decisions, filters)
89    }
90
91    /// Generates one migration using an optional caller-selected descriptive suffix.
92    pub fn make_named_migration(
93        &self,
94        desired_schema: Schema,
95        name: Option<&str>,
96        decisions: &[Decision],
97    ) -> Result<Option<Migration>, OfflineError> {
98        self.make_named_migration_filtered(desired_schema, name, decisions, &[])
99    }
100
101    /// Generates one optionally named migration for selected root entities and dependencies.
102    pub fn make_named_migration_filtered(
103        &self,
104        desired_schema: Schema,
105        name: Option<&str>,
106        decisions: &[Decision],
107        filters: &[crate::EntityFilter],
108    ) -> Result<Option<Migration>, OfflineError> {
109        let replay = self.replay_with_sources()?;
110        let previous = replay
111            .schema
112            .prepare(self.dialect)
113            .map_err(|err| OfflineError::Schema(err.to_string()))?;
114        let desired_schema = desired_schema
115            .prepare(self.dialect)
116            .map_err(|err| OfflineError::Schema(err.to_string()))?;
117        let selected_tables = if filters.is_empty() {
118            None
119        } else {
120            let preliminary = DiffEngine::new().diff(&desired_schema, &previous, &self.dialect)?;
121            let selected = crate::migration_filter::filter_operations(
122                &preliminary,
123                filters,
124                &desired_schema,
125                &previous,
126            )
127            .map_err(OfflineError::Schema)?;
128            if selected.operations.is_empty() {
129                return Ok(None);
130            }
131            Some(selected.table_roots)
132        };
133        let type_resolution = match &selected_tables {
134            Some(tables) => crate::clarifier::resolve_unknown_types_for_tables(
135                self.dialect,
136                desired_schema,
137                &previous,
138                decisions,
139                tables,
140            )?,
141            None => resolve_unknown_types(self.dialect, desired_schema, &previous, decisions)?,
142        };
143        let desired_schema = match type_resolution {
144            TypeResolution::Resolved(schema) => schema,
145            TypeResolution::NeedsInput(clarifications) => {
146                return Err(OfflineError::NeedsInput(clarifications));
147            }
148        }
149        .prepare(self.dialect)
150        .map_err(|err| OfflineError::Schema(err.to_string()))?;
151        let raw_ops = DiffEngine::new().diff(&desired_schema, &previous, &self.dialect)?;
152        let raw_ops = if filters.is_empty() {
153            raw_ops
154        } else {
155            crate::migration_filter::filter_operations(
156                &raw_ops,
157                filters,
158                &desired_schema,
159                &previous,
160            )
161            .map_err(OfflineError::Schema)?
162            .operations
163        };
164        if raw_ops.is_empty() {
165            return Ok(None);
166        }
167        let op_decisions = non_type_decisions(decisions);
168        let ops = match Clarifier.process(&raw_ops, &op_decisions)? {
169            ClarifyResult::NeedsInput(clarifications) => {
170                return Err(OfflineError::NeedsInput(clarifications));
171            }
172            ClarifyResult::Resolved(ops) => ops,
173        };
174        let ops = self.dialect.reorder(ops, &previous, &desired_schema);
175        let suffix = name
176            .filter(|name| !name.trim().is_empty())
177            .map(str::to_string)
178            .unwrap_or_else(|| deterministic_name_from_ops(&ops));
179        let id = format!("{:04}_{suffix}", self.next_number());
180        MigrationGraph::validate_id(&id)?;
181        let migration = Migration {
182            id,
183            dependencies: compute_deps(&ops, &replay.last_per_ns, &replay.entity_ns),
184            operations: ops,
185            atomic: self.dialect.supports_transactional_ddl(),
186        };
187        let migration = migration.canonicalized()?;
188        if !filters.is_empty() {
189            let mut candidate = previous.clone();
190            crate::replay::ReplayEngine::apply_migration(&mut candidate, &migration)?;
191        }
192        Ok(Some(migration))
193    }
194
195    pub fn sql_migrate(&self, migrations: &[Migration]) -> Result<Vec<String>, OfflineError> {
196        Ok(SqlPlanRenderer::new(self.dialect, self.migrations.clone())?
197            .render_migrations(migrations)?)
198    }
199
200    fn graph(&self) -> Result<(MigrationGraph, Vec<String>), OfflineError> {
201        let mut graph = MigrationGraph::new();
202        for migration in self.migrations.clone() {
203            graph.add(migration)?;
204        }
205        let ordered_ids = graph
206            .topological_order()?
207            .into_iter()
208            .map(str::to_string)
209            .collect();
210        Ok((graph, ordered_ids))
211    }
212
213    fn next_number(&self) -> u32 {
214        self.migrations
215            .iter()
216            .filter(|migration| !migration.id.contains('/'))
217            .filter_map(|migration| migration.id.split('_').next()?.parse::<u32>().ok())
218            .max()
219            .map(|number| number + 1)
220            .unwrap_or(1)
221    }
222
223    fn replay_with_sources(&self) -> Result<ReplaySources, OfflineError> {
224        let (graph, ordered_ids) = self.graph()?;
225        Ok(ReplayEngine::new(&graph).replay_with_sources(&ordered_ids)?)
226    }
227}
228
229#[cfg(test)]
230mod tests {
231    use super::*;
232    use crate::clarifier::{Answer, ClarificationKind, Decision};
233    use crate::operations::Operation;
234    use crate::states::{Column, Schema, Table};
235
236    fn users_table(columns: Vec<Column>) -> Table {
237        Table {
238            name: "users".to_string(),
239            schema: None,
240            primary_key: None,
241            columns,
242            foreign_keys: vec![],
243            indexes: vec![],
244            constraints: vec![],
245            triggers: vec![],
246            options: Default::default(),
247        }
248    }
249
250    fn id_col() -> Column {
251        Column {
252            name: "id".to_string(),
253            col_type: "integer".to_string(),
254            nullable: false,
255            default: None,
256            primary_key: true,
257            references: None,
258            check: None,
259            generated: None,
260            generated_storage: None,
261            dialect_options: Default::default(),
262        }
263    }
264
265    fn email_col() -> Column {
266        Column {
267            name: "email".to_string(),
268            col_type: "text".to_string(),
269            nullable: true,
270            default: None,
271            primary_key: false,
272            references: None,
273            check: None,
274            generated: None,
275            generated_storage: None,
276            dialect_options: Default::default(),
277        }
278    }
279
280    fn col(name: &str, col_type: &str) -> Column {
281        Column {
282            name: name.to_string(),
283            col_type: col_type.to_string(),
284            nullable: true,
285            default: None,
286            primary_key: false,
287            references: None,
288            check: None,
289            generated: None,
290            generated_storage: None,
291            dialect_options: Default::default(),
292        }
293    }
294
295    #[test]
296    fn offline_planner_generates_migration_without_database_driver() {
297        let mut desired = Schema::default();
298        desired.tables.insert(
299            "users".to_string(),
300            users_table(vec![id_col(), email_col()]),
301        );
302
303        let migration = OfflinePlanner::new(Dialect::Postgres)
304            .make_migration(desired, &[])
305            .expect("offline planning should succeed")
306            .expect("migration should be generated");
307
308        assert_eq!(migration.id, "0001_users");
309        assert!(migration.dependencies.is_empty());
310        assert!(matches!(
311            migration.operations.as_slice(),
312            [Operation::CreateTable { table }] if table.name == "users"
313        ));
314    }
315
316    #[test]
317    fn offline_replay_is_deterministic() {
318        let migration = Migration {
319            id: "0001_users".to_string(),
320            dependencies: vec![],
321            operations: vec![Operation::CreateTable {
322                table: users_table(vec![id_col()]),
323            }],
324            atomic: true,
325        };
326        let planner = OfflinePlanner::new(Dialect::Postgres).from_migrations(vec![migration]);
327
328        let first = planner.replay().expect("first replay should succeed");
329        let second = planner.replay().expect("second replay should succeed");
330
331        assert_eq!(first, second);
332        assert!(first.tables.contains_key("users"));
333    }
334
335    #[test]
336    fn migration_yaml_round_trips_from_strings() {
337        let migration = Migration {
338            id: "0001_users".to_string(),
339            dependencies: vec![],
340            operations: vec![Operation::CreateTable {
341                table: users_table(vec![id_col()]),
342            }],
343            atomic: true,
344        };
345
346        let yaml = migration.to_yaml_string().expect("serialize migration");
347        let mut parsed = Migration::from_yaml_str(&yaml).expect("parse migration");
348        parsed.id = migration.id.clone();
349
350        assert_eq!(parsed.id, migration.id);
351        assert_eq!(parsed.operations, migration.operations);
352    }
353
354    #[test]
355    fn make_migration_asks_for_new_unknown_type_before_diff() {
356        let mut desired = Schema::default();
357        desired.tables.insert(
358            "users".to_string(),
359            users_table(vec![id_col(), col("age", "intger")]),
360        );
361
362        let err = OfflinePlanner::new(Dialect::Postgres)
363            .make_migration(desired, &[])
364            .unwrap_err();
365        let OfflineError::NeedsInput(clarifications) = err else {
366            panic!("expected needs input");
367        };
368
369        assert_eq!(clarifications.len(), 1);
370        assert!(matches!(
371            &clarifications[0].kind,
372            ClarificationKind::UnknownType { type_name, suggested, .. }
373                if type_name == "intger" && suggested.contains(&"integer".to_string())
374        ));
375    }
376
377    #[test]
378    fn make_migration_type_decision_rewrites_desired_schema() {
379        let mut desired = Schema::default();
380        desired.tables.insert(
381            "users".to_string(),
382            users_table(vec![id_col(), col("age", "intger")]),
383        );
384        let decisions = vec![Decision {
385            clarification_id: "unknown_type:users:age".to_string(),
386            answer: Answer::UseType("integer".to_string()),
387        }];
388
389        let migration = OfflinePlanner::new(Dialect::Postgres)
390            .make_migration(desired, &decisions)
391            .expect("planning should succeed")
392            .expect("migration should be generated");
393        let Operation::CreateTable { table } = &migration.operations[0] else {
394            panic!("expected create table");
395        };
396
397        assert_eq!(table.columns[1].col_type, "integer");
398    }
399
400    #[test]
401    fn make_migration_trusts_unknown_type_from_replay() {
402        let previous = Migration {
403            id: "0001_users".to_string(),
404            dependencies: vec![],
405            operations: vec![Operation::CreateTable {
406                table: users_table(vec![id_col(), col("code", "project_code")]),
407            }],
408            atomic: true,
409        };
410        let mut desired = Schema::default();
411        desired.tables.insert(
412            "users".to_string(),
413            users_table(vec![
414                id_col(),
415                col("code", "project_code"),
416                col("other_code", "project_code"),
417            ]),
418        );
419
420        let migration = OfflinePlanner::new(Dialect::Postgres)
421            .from_migrations(vec![previous])
422            .make_migration(desired, &[])
423            .expect("trusted replay type should not ask")
424            .expect("migration should be generated");
425
426        assert!(matches!(
427            migration.operations.as_slice(),
428            [Operation::AddColumn { column, .. }] if column.col_type == "project_code"
429        ));
430    }
431
432    #[test]
433    fn make_migration_accepts_known_extension_type_without_prompt() {
434        let mut desired = Schema::default();
435        desired.tables.insert(
436            "users".to_string(),
437            users_table(vec![id_col(), col("email", "citext")]),
438        );
439
440        let migration = OfflinePlanner::new(Dialect::Postgres)
441            .make_migration(desired, &[])
442            .expect("known extension type should not ask")
443            .expect("migration should be generated");
444
445        assert!(matches!(
446            migration.operations.as_slice(),
447            [Operation::CreateTable { table }] if table.columns[1].col_type == "citext"
448        ));
449    }
450}