1use 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 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 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 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}