Skip to main content

type_bridge_migration/
executor.rs

1//! Async migration executor.
2//!
3//! Runs an [`ExecutionPlan`] produced by the planner over a [`Database`],
4//! committing each step in its own transaction.  The executor is
5//! runtime-agnostic: the caller (`PyMigrationRunner` in Phase 3) drives it by
6//! `block_on`-ing the returned future on the shared `Arc<Runtime>`.
7//!
8//! # Per-step commit contract
9//!
10//! TypeDB forbids multiple `define` blocks per transaction.  Each
11//! [`ExecutionStep`](crate::plan::ExecutionStep) is executed in its own
12//! transaction and committed
13//! independently.  When a step fails, earlier committed steps in the same
14//! migration are **not** rolled back (there is no cross-step atomicity).
15//! This matches the current Python per-statement-commit behavior and is the
16//! documented contract for this boundary.
17
18use serde::{Deserialize, Serialize};
19use std::collections::BTreeMap;
20use type_bridge_orm::Database;
21
22use crate::backfill::{BackfillResult, execute_backfill};
23use crate::plan::{ExecutionPlan, MigrationAction, MigrationExecution, StepKind};
24use crate::state::{
25    MigrationExecutorInfo, MigrationStateStore, finished_run_record, require_legacy_writer_open,
26    require_legacy_writer_open_in_transaction, started_run_record,
27};
28
29/// Result of executing a single migration (one entry per attempted migration).
30#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
31pub struct MigrationResult {
32    /// Application or package label.
33    pub app_label: String,
34    /// Migration file stem, e.g. `0001_initial`.
35    pub name: String,
36    /// Whether this was an apply or a rollback.
37    pub action: MigrationAction,
38    /// `true` when all steps completed and committed successfully.
39    pub success: bool,
40    /// Human-readable failure reason, present only when `success` is `false`.
41    pub error: Option<String>,
42    /// Per-step backfill counts, present only when the migration contained at
43    /// least one [`StepKind::Backfill`] step.  `None` for pure-schema migrations
44    /// so the field does not appear in JSON output (no bloat — D2a).
45    #[serde(default, skip_serializing_if = "Option::is_none")]
46    pub backfill: Option<Vec<BackfillResult>>,
47}
48
49/// Execute a [`ExecutionPlan`] against `db`.
50///
51/// Rollbacks are processed first (already in reverse order from the planner),
52/// then applies.  The run halts at the first failed migration and returns all
53/// results accumulated so far including the failure.
54///
55/// Returns one [`MigrationResult`] per attempted migration, in execution order
56/// (rollbacks then applies).
57pub async fn execute_plan(db: &Database, plan: ExecutionPlan) -> Vec<MigrationResult> {
58    let mut results: Vec<MigrationResult> = Vec::new();
59
60    // Process rollbacks before applies (planner already reverse-ordered them).
61    for migration in plan.to_rollback {
62        let result = execute_migration(db, &migration).await;
63        let should_halt = !result.success;
64        results.push(result);
65        if should_halt {
66            return results;
67        }
68    }
69
70    // Process applies.
71    for migration in plan.to_apply {
72        let result = execute_migration(db, &migration).await;
73        let should_halt = !result.success;
74        results.push(result);
75        if should_halt {
76            return results;
77        }
78    }
79
80    results
81}
82
83/// Execute a plan while writing one DB-backed run-log row per attempted migration.
84pub async fn execute_plan_with_run_log<S: MigrationStateStore>(
85    db: &Database,
86    store: &S,
87    plan: ExecutionPlan,
88    checksums: &BTreeMap<(String, String), String>,
89    executor: &MigrationExecutorInfo,
90) -> crate::Result<Vec<MigrationResult>> {
91    let mut results: Vec<MigrationResult> = Vec::new();
92
93    for migration in plan.to_rollback {
94        let result = execute_logged_migration(db, store, &migration, checksums, executor).await?;
95        let should_halt = !result.success;
96        results.push(result);
97        if should_halt {
98            return Ok(results);
99        }
100    }
101
102    for migration in plan.to_apply {
103        let result = execute_logged_migration(db, store, &migration, checksums, executor).await?;
104        let should_halt = !result.success;
105        results.push(result);
106        if should_halt {
107            return Ok(results);
108        }
109    }
110
111    Ok(results)
112}
113
114async fn execute_logged_migration<S: MigrationStateStore>(
115    db: &Database,
116    store: &S,
117    migration: &MigrationExecution,
118    checksums: &BTreeMap<(String, String), String>,
119    executor: &MigrationExecutorInfo,
120) -> crate::Result<MigrationResult> {
121    // External state stores cannot share the target transaction, so reject an
122    // already-cut-over target before touching their run log.  Each target
123    // mutation repeats the check in its own transaction below.
124    require_legacy_writer_open(db).await?;
125    let checksum = checksums
126        .get(&(migration.app_label.clone(), migration.name.clone()))
127        .cloned()
128        .unwrap_or_default();
129    let run = started_run_record(migration, checksum, executor);
130    store.record_run(run.clone()).await?;
131
132    let result = execute_migration(db, migration).await;
133    let status = if result.success {
134        "succeeded"
135    } else {
136        "failed"
137    };
138    let finished = finished_run_record(run, status, result.error.clone());
139    store.record_run(finished).await?;
140    Ok(result)
141}
142
143/// Execute a single [`MigrationExecution`].
144///
145/// Returns one [`MigrationResult`] for this attempted migration.
146pub async fn execute_migration(db: &Database, migration: &MigrationExecution) -> MigrationResult {
147    // Non-reversible rollback: fail immediately without opening a transaction.
148    if migration.action == MigrationAction::Rollback && !migration.reversible {
149        return MigrationResult {
150            app_label: migration.app_label.clone(),
151            name: migration.name.clone(),
152            action: migration.action,
153            success: false,
154            error: Some(format!("{} is not reversible", migration.name)),
155            backfill: None,
156        };
157    }
158
159    if let Err(error) = require_legacy_writer_open(db).await {
160        return MigrationResult {
161            app_label: migration.app_label.clone(),
162            name: migration.name.clone(),
163            action: migration.action,
164            success: false,
165            error: Some(error.to_string()),
166            backfill: None,
167        };
168    }
169
170    let mut backfill_results: Vec<BackfillResult> = Vec::new();
171
172    for (step_index, step) in migration.steps.iter().enumerate() {
173        // Backfill steps are routed through the count-deriving path.
174        if step.kind == StepKind::Backfill && migration.action == MigrationAction::Apply {
175            match execute_backfill(db, step, step_index).await {
176                Ok(bf_result) => {
177                    backfill_results.push(bf_result);
178                    // Backfill execution committed internally; continue.
179                    continue;
180                }
181                Err(e) => {
182                    return MigrationResult {
183                        app_label: migration.app_label.clone(),
184                        name: migration.name.clone(),
185                        action: migration.action,
186                        success: false,
187                        error: Some(format!("backfill step {step_index} failed: {e}")),
188                        backfill: None,
189                    };
190                }
191            }
192        }
193
194        // Choose forward or reverse TypeQL based on the action.
195        let typeql: &str = match migration.action {
196            MigrationAction::Apply => &step.forward,
197            MigrationAction::Rollback => {
198                // reversible was true above, so every step has a reverse.
199                // Unwrap is safe here — the planner guarantees this when
200                // `migration.reversible == true`.
201                step.reverse.as_deref().unwrap_or(&step.forward)
202            }
203        };
204
205        // Version-gate annotation-bearing schema DDL before opening a
206        // transaction: pre-3.12 servers reject @doc/@meta with a syntax
207        // error; the gate produces an actionable versioned error instead.
208        if let Err(e) = db.check_schema_annotation_support(typeql) {
209            return MigrationResult {
210                app_label: migration.app_label.clone(),
211                name: migration.name.clone(),
212                action: migration.action,
213                success: false,
214                error: Some(e.to_string()),
215                backfill: None,
216            };
217        }
218
219        // Open a transaction for this step.
220        let ctx = match db.transaction_context(step.tx_type).await {
221            Ok(ctx) => ctx,
222            Err(e) => {
223                return MigrationResult {
224                    app_label: migration.app_label.clone(),
225                    name: migration.name.clone(),
226                    action: migration.action,
227                    success: false,
228                    error: Some(format!("failed to open transaction: {e}")),
229                    backfill: None,
230                };
231            }
232        };
233
234        if let Err(error) = require_legacy_writer_open_in_transaction(&ctx).await {
235            let _ = ctx.rollback().await;
236            let _ = ctx.close().await;
237            return MigrationResult {
238                app_label: migration.app_label.clone(),
239                name: migration.name.clone(),
240                action: migration.action,
241                success: false,
242                error: Some(error.to_string()),
243                backfill: None,
244            };
245        }
246
247        // Execute the query.
248        if let Err(e) = ctx.query(typeql).await {
249            // Best-effort rollback; ignore its error.
250            let _ = ctx.rollback().await;
251            let _ = ctx.close().await;
252            return MigrationResult {
253                app_label: migration.app_label.clone(),
254                name: migration.name.clone(),
255                action: migration.action,
256                success: false,
257                error: Some(format!("query failed: {e}")),
258                backfill: None,
259            };
260        }
261
262        // Commit the step.
263        if let Err(e) = ctx.commit().await {
264            return MigrationResult {
265                app_label: migration.app_label.clone(),
266                name: migration.name.clone(),
267                action: migration.action,
268                success: false,
269                error: Some(format!("commit failed: {e}")),
270                backfill: None,
271            };
272        }
273    }
274
275    // All steps succeeded.
276    let backfill = if backfill_results.is_empty() {
277        None
278    } else {
279        Some(backfill_results)
280    };
281    MigrationResult {
282        app_label: migration.app_label.clone(),
283        name: migration.name.clone(),
284        action: migration.action,
285        success: true,
286        error: None,
287        backfill,
288    }
289}
290
291#[cfg(test)]
292mod tests {
293    use super::*;
294    use crate::plan::ExecutionStep;
295    use crate::state::InMemoryStateStore;
296    use crate::testing::{MockEvent, MockMigrationBackend};
297    use type_bridge_orm::{Database, TxType};
298
299    // ── helpers ───────────────────────────────────────────────────────────────
300
301    fn schema_step(forward: &str, reverse: Option<&str>) -> ExecutionStep {
302        ExecutionStep {
303            tx_type: TxType::Schema,
304            kind: crate::plan::StepKind::Schema,
305            operation_kind: crate::plan::OperationKind::RunTypeql,
306            forward: forward.to_string(),
307            reverse: reverse.map(str::to_string),
308        }
309    }
310
311    fn apply_migration(name: &str, steps: Vec<ExecutionStep>) -> MigrationExecution {
312        let reversible = steps.iter().all(|s| s.reverse.is_some());
313        MigrationExecution {
314            app_label: "app".to_string(),
315            name: name.to_string(),
316            action: MigrationAction::Apply,
317            steps,
318            reversible,
319        }
320    }
321
322    fn rollback_migration(
323        name: &str,
324        steps: Vec<ExecutionStep>,
325        reversible: bool,
326    ) -> MigrationExecution {
327        MigrationExecution {
328            app_label: "app".to_string(),
329            name: name.to_string(),
330            action: MigrationAction::Rollback,
331            steps,
332            reversible,
333        }
334    }
335
336    #[tokio::test]
337    async fn cutover_rejects_before_executor_typeql_or_run_log_mutation() {
338        let (backend, log) = MockMigrationBackend::with_legacy_cutover();
339        let db = Database::with_backend(Box::new(backend), "test");
340        let migration = apply_migration(
341            "0001_blocked",
342            vec![schema_step("define entity must-not-run;", None)],
343        );
344        let plan = ExecutionPlan {
345            to_apply: vec![migration.clone()],
346            to_rollback: Vec::new(),
347        };
348
349        let results = execute_plan(&db, plan).await;
350        assert_eq!(results.len(), 1);
351        assert!(!results[0].success);
352        assert!(
353            results[0]
354                .error
355                .as_deref()
356                .is_some_and(|error| error.contains(crate::LEGACY_WRITER_CUTOVER_MESSAGE))
357        );
358        assert_eq!(
359            *log.lock().unwrap(),
360            vec![MockEvent::OpenTx(TxType::Read), MockEvent::Close]
361        );
362
363        let store = InMemoryStateStore::new();
364        let logged = execute_plan_with_run_log(
365            &db,
366            &store,
367            ExecutionPlan {
368                to_apply: vec![migration],
369                to_rollback: Vec::new(),
370            },
371            &BTreeMap::new(),
372            &MigrationExecutorInfo::default(),
373        )
374        .await
375        .expect_err("cutover must reject before the external run log");
376        assert!(
377            logged
378                .to_string()
379                .contains(crate::LEGACY_WRITER_CUTOVER_MESSAGE)
380        );
381        assert!(store.load_runs().await.unwrap().is_empty());
382    }
383
384    // ── test: apply-only plan ─────────────────────────────────────────────────
385
386    #[tokio::test]
387    async fn apply_only_executes_steps_in_order_under_schema_tx() {
388        let (backend, log) = MockMigrationBackend::new(None);
389        let db = Database::with_backend(Box::new(backend), "test");
390
391        let plan = ExecutionPlan {
392            to_apply: vec![
393                apply_migration(
394                    "0001_initial",
395                    vec![schema_step("define attribute a, value string;", None)],
396                ),
397                apply_migration(
398                    "0002_add",
399                    vec![schema_step(
400                        "define attribute b, value string;",
401                        Some("undefine attribute b;"),
402                    )],
403                ),
404            ],
405            to_rollback: Vec::new(),
406        };
407
408        let results = execute_plan(&db, plan).await;
409
410        assert_eq!(results.len(), 2);
411        assert!(results[0].success);
412        assert_eq!(results[0].name, "0001_initial");
413        assert!(results[1].success);
414        assert_eq!(results[1].name, "0002_add");
415
416        // Each migration first performs the read-only cutover preflight, then
417        // executes its step under the intended schema transaction.
418        let events = log.lock().unwrap();
419        assert_eq!(
420            *events,
421            vec![
422                MockEvent::OpenTx(TxType::Read),
423                MockEvent::Close,
424                MockEvent::OpenTx(TxType::Schema),
425                MockEvent::Query(
426                    TxType::Schema,
427                    "define attribute a, value string;".to_string()
428                ),
429                MockEvent::Commit,
430                MockEvent::OpenTx(TxType::Read),
431                MockEvent::Close,
432                MockEvent::OpenTx(TxType::Schema),
433                MockEvent::Query(
434                    TxType::Schema,
435                    "define attribute b, value string;".to_string()
436                ),
437                MockEvent::Commit,
438            ]
439        );
440    }
441
442    #[tokio::test]
443    async fn execute_plan_with_run_log_records_started_and_finished_rows() {
444        let (backend, _log) = MockMigrationBackend::new(None);
445        let db = Database::with_backend(Box::new(backend), "test");
446        let store = InMemoryStateStore::new();
447        let mut checksums = BTreeMap::new();
448        checksums.insert(
449            ("app".to_string(), "0001_initial".to_string()),
450            "checksum-1".to_string(),
451        );
452        let executor = MigrationExecutorInfo {
453            ip: Some("127.0.0.1".to_string()),
454            mac: Some("00:11:22:33:44:55".to_string()),
455        };
456        let plan = ExecutionPlan {
457            to_apply: vec![apply_migration(
458                "0001_initial",
459                vec![schema_step("define attribute a, value string;", None)],
460            )],
461            to_rollback: Vec::new(),
462        };
463
464        let results = execute_plan_with_run_log(&db, &store, plan, &checksums, &executor)
465            .await
466            .unwrap();
467
468        assert_eq!(results.len(), 1);
469        assert!(results[0].success);
470        let runs = store.load_runs().await.unwrap();
471        assert_eq!(runs.len(), 1);
472        assert_eq!(runs[0].name, "0001_initial");
473        assert_eq!(runs[0].checksum, "checksum-1");
474        assert_eq!(runs[0].direction, "apply");
475        assert_eq!(runs[0].status, "succeeded");
476        assert!(runs[0].finished_at.is_some());
477        assert_eq!(runs[0].executor_ip.as_deref(), Some("127.0.0.1"));
478        assert_eq!(runs[0].executor_mac.as_deref(), Some("00:11:22:33:44:55"));
479    }
480
481    // ── test: rollback path ───────────────────────────────────────────────────
482
483    #[tokio::test]
484    async fn rollback_executes_reverse_typeql_under_schema_tx() {
485        let (backend, log) = MockMigrationBackend::new(None);
486        let db = Database::with_backend(Box::new(backend), "test");
487
488        let plan = ExecutionPlan {
489            to_apply: Vec::new(),
490            to_rollback: vec![rollback_migration(
491                "0002_add",
492                vec![schema_step(
493                    "define attribute b, value string;",
494                    Some("undefine attribute b;"),
495                )],
496                true,
497            )],
498        };
499
500        let results = execute_plan(&db, plan).await;
501
502        assert_eq!(results.len(), 1);
503        assert!(results[0].success);
504        assert_eq!(results[0].action, MigrationAction::Rollback);
505
506        let events = log.lock().unwrap();
507        assert_eq!(
508            *events,
509            vec![
510                MockEvent::OpenTx(TxType::Read),
511                MockEvent::Close,
512                MockEvent::OpenTx(TxType::Schema),
513                // Reverse TypeQL is used for rollback.
514                MockEvent::Query(TxType::Schema, "undefine attribute b;".to_string()),
515                MockEvent::Commit,
516            ]
517        );
518    }
519
520    // ── test: per-step-commit / no atomicity (oracle risk 1) ──────────────────
521    //
522    // A migration with 3 steps where the mock fails the 2nd query:
523    //   - Step 1: Query + Commit (durable)
524    //   - Step 2: Query fails → Rollback
525    //   - Step 3: never opened
526    //   - Run halts after the failure
527    //   - Result: success=false
528
529    #[tokio::test]
530    async fn middle_step_failure_commits_prior_steps_and_halts() {
531        // Fail the 2nd query (0-indexed: index 1).
532        let (backend, log) = MockMigrationBackend::new(Some(1));
533        let db = Database::with_backend(Box::new(backend), "test");
534
535        let plan = ExecutionPlan {
536            to_apply: vec![apply_migration(
537                "0001_three_steps",
538                vec![
539                    schema_step("define attribute a, value string;", None),
540                    schema_step("define attribute b, value string;", None),
541                    schema_step("define attribute c, value string;", None),
542                ],
543            )],
544            to_rollback: Vec::new(),
545        };
546
547        let results = execute_plan(&db, plan).await;
548
549        // Only one migration attempted; it failed.
550        assert_eq!(results.len(), 1);
551        assert!(!results[0].success);
552        assert!(results[0].error.is_some());
553
554        let events = log.lock().unwrap();
555
556        // Migration entry: read-only cutover guard, then close the snapshot.
557        assert!(matches!(events[0], MockEvent::OpenTx(TxType::Read)));
558        assert!(matches!(events[1], MockEvent::Close));
559
560        // Step 1: OpenTx → Query → Commit (durable)
561        assert!(matches!(events[2], MockEvent::OpenTx(TxType::Schema)));
562        assert!(
563            matches!(&events[3], MockEvent::Query(TxType::Schema, q) if q == "define attribute a, value string;")
564        );
565        assert!(matches!(events[4], MockEvent::Commit));
566
567        // Step 2: OpenTx → Query (fails) → Rollback → Close
568        assert!(matches!(events[5], MockEvent::OpenTx(TxType::Schema)));
569        assert!(
570            matches!(&events[6], MockEvent::Query(TxType::Schema, q) if q == "define attribute b, value string;")
571        );
572        assert!(matches!(events[7], MockEvent::Rollback));
573
574        assert!(matches!(events[8], MockEvent::Close));
575
576        // Step 3 must NOT appear — run halted after step 2 failure.
577        assert_eq!(events.len(), 9, "step 3 must not be opened");
578    }
579
580    // ── test: non-reversible rollback ─────────────────────────────────────────
581
582    #[tokio::test]
583    async fn non_reversible_rollback_returns_failed_result_without_opening_tx() {
584        let (backend, log) = MockMigrationBackend::new(None);
585        let db = Database::with_backend(Box::new(backend), "test");
586
587        let plan = ExecutionPlan {
588            to_apply: Vec::new(),
589            to_rollback: vec![rollback_migration(
590                "0001_initial",
591                // Steps carry no reverse — this migration is non-reversible.
592                vec![schema_step("define attribute a, value string;", None)],
593                false,
594            )],
595        };
596
597        let results = execute_plan(&db, plan).await;
598
599        assert_eq!(results.len(), 1);
600        assert!(!results[0].success);
601        assert!(
602            results[0]
603                .error
604                .as_deref()
605                .unwrap_or("")
606                .contains("not reversible"),
607            "error message must mention 'not reversible'; got: {:?}",
608            results[0].error
609        );
610
611        // No transaction was opened.
612        let events = log.lock().unwrap();
613        assert!(
614            events.is_empty(),
615            "no events expected for non-reversible rollback; got: {events:?}"
616        );
617    }
618
619    // ── test: results are in execution order (rollbacks then applies) ─────────
620
621    #[tokio::test]
622    async fn results_are_in_execution_order_rollbacks_first() {
623        let (backend, _log) = MockMigrationBackend::new(None);
624        let db = Database::with_backend(Box::new(backend), "test");
625
626        let plan = ExecutionPlan {
627            to_apply: vec![apply_migration(
628                "0003_apply",
629                vec![schema_step("define attribute c, value string;", None)],
630            )],
631            to_rollback: vec![rollback_migration(
632                "0002_rollback",
633                vec![schema_step(
634                    "define attribute b, value string;",
635                    Some("undefine attribute b;"),
636                )],
637                true,
638            )],
639        };
640
641        let results = execute_plan(&db, plan).await;
642
643        assert_eq!(results.len(), 2);
644        // Rollback comes first in results.
645        assert_eq!(results[0].name, "0002_rollback");
646        assert_eq!(results[0].action, MigrationAction::Rollback);
647        assert_eq!(results[1].name, "0003_apply");
648        assert_eq!(results[1].action, MigrationAction::Apply);
649    }
650
651    // ── test: failure halts remaining migrations ──────────────────────────────
652
653    #[tokio::test]
654    async fn failure_in_first_migration_halts_remaining() {
655        // Fail the very first query.
656        let (backend, _log) = MockMigrationBackend::new(Some(0));
657        let db = Database::with_backend(Box::new(backend), "test");
658
659        let plan = ExecutionPlan {
660            to_apply: vec![
661                apply_migration(
662                    "0001_fail",
663                    vec![schema_step("define attribute a, value string;", None)],
664                ),
665                apply_migration(
666                    "0002_skipped",
667                    vec![schema_step("define attribute b, value string;", None)],
668                ),
669            ],
670            to_rollback: Vec::new(),
671        };
672
673        let results = execute_plan(&db, plan).await;
674
675        // Only the first migration result is returned; the second is never attempted.
676        assert_eq!(results.len(), 1);
677        assert!(!results[0].success);
678        assert_eq!(results[0].name, "0001_fail");
679    }
680}