Skip to main content

qail_workflow_postgres/
tables.rs

1use qail_core::ast::{Constraint, Expr, Qail, TableConstraint};
2
3/// Table names used by [`crate::PgWorkflowStore`].
4#[derive(Debug, Clone, PartialEq, Eq)]
5pub struct PgWorkflowTables {
6    /// Persisted workflow context table.
7    pub states: String,
8    /// Per-workflow lease table.
9    pub leases: String,
10    /// Workflow operation idempotency table.
11    pub operations: String,
12    /// Side-effect idempotency table.
13    pub side_effects: String,
14}
15
16impl Default for PgWorkflowTables {
17    fn default() -> Self {
18        Self {
19            states: "qail_workflow_states".to_string(),
20            leases: "qail_workflow_leases".to_string(),
21            operations: "qail_workflow_operations".to_string(),
22            side_effects: "qail_workflow_side_effects".to_string(),
23        }
24    }
25}
26
27impl PgWorkflowTables {
28    /// Return QAIL AST commands that create the workflow storage tables.
29    ///
30    /// These commands are intentionally plain `CREATE TABLE` ASTs. Run them in
31    /// a migration or fresh database bootstrap path; existing installations
32    /// should use normal QAIL migrations for schema changes.
33    pub fn schema_commands(&self) -> Vec<Qail> {
34        vec![
35            states_schema(&self.states),
36            leases_schema(&self.leases),
37            operations_schema(&self.operations),
38            side_effects_schema(&self.side_effects),
39        ]
40    }
41}
42
43fn states_schema(table: &str) -> Qail {
44    Qail::make(table).columns_expr([
45        def_pk("workflow_id", "text"),
46        def_nullable("definition_name", "text"),
47        def_nullable("definition_version", "text"),
48        def("current_state", "text"),
49        def("context", "jsonb"),
50        def_nullable("wait_event", "text"),
51        def_nullable("wait_deadline_at", "text"),
52        def_nullable("timeout_claimed_until", "text"),
53        def("created_at", "text"),
54        def("updated_at", "text"),
55    ])
56}
57
58fn leases_schema(table: &str) -> Qail {
59    Qail::make(table).columns_expr([
60        def_pk("workflow_id", "text"),
61        def("owner", "text"),
62        def("expires_at", "text"),
63        def("updated_at", "text"),
64    ])
65}
66
67fn operations_schema(table: &str) -> Qail {
68    let mut cmd = Qail::make(table).columns_expr([
69        def("workflow_name", "text"),
70        def("workflow_id", "text"),
71        def("idempotency_key", "text"),
72        def("kind", "text"),
73        def("status", "text"),
74        def_nullable("state", "text"),
75        def_nullable("error", "text"),
76        def("created_at", "text"),
77        def("updated_at", "text"),
78    ]);
79    cmd.table_constraints.push(TableConstraint::PrimaryKey(vec![
80        "workflow_id".to_string(),
81        "idempotency_key".to_string(),
82    ]));
83    cmd
84}
85
86fn side_effects_schema(table: &str) -> Qail {
87    Qail::make(table).columns_expr([
88        def_pk("operation_id", "text"),
89        def("workflow_id", "text"),
90        def("state", "text"),
91        def("step_path", "text"),
92        def("kind", "text"),
93        def("status", "text"),
94        def_nullable("result", "jsonb"),
95        def_nullable("error", "text"),
96        def("created_at", "text"),
97        def("updated_at", "text"),
98    ])
99}
100
101fn def(name: &str, data_type: &str) -> Expr {
102    Expr::Def {
103        name: name.to_string(),
104        data_type: data_type.to_string(),
105        constraints: Vec::new(),
106    }
107}
108
109fn def_pk(name: &str, data_type: &str) -> Expr {
110    Expr::Def {
111        name: name.to_string(),
112        data_type: data_type.to_string(),
113        constraints: vec![Constraint::PrimaryKey],
114    }
115}
116
117fn def_nullable(name: &str, data_type: &str) -> Expr {
118    Expr::Def {
119        name: name.to_string(),
120        data_type: data_type.to_string(),
121        constraints: vec![Constraint::Nullable],
122    }
123}
124
125#[cfg(test)]
126mod tests {
127    use super::*;
128
129    #[test]
130    fn schema_commands_cover_runtime_tables() {
131        let tables = PgWorkflowTables::default();
132        let commands = tables.schema_commands();
133
134        assert_eq!(commands.len(), 4);
135        assert_eq!(commands[0].table, "qail_workflow_states");
136        assert_eq!(commands[1].table, "qail_workflow_leases");
137        assert_eq!(commands[2].table, "qail_workflow_operations");
138        assert_eq!(commands[3].table, "qail_workflow_side_effects");
139    }
140
141    #[test]
142    fn operations_schema_uses_composite_operation_key() {
143        let tables = PgWorkflowTables::default();
144        let commands = tables.schema_commands();
145
146        assert_eq!(
147            commands[2].table_constraints,
148            vec![TableConstraint::PrimaryKey(vec![
149                "workflow_id".to_string(),
150                "idempotency_key".to_string()
151            ])]
152        );
153    }
154
155    #[test]
156    fn schema_commands_encode_through_pg_ast_encoder() {
157        for cmd in PgWorkflowTables::default().schema_commands() {
158            qail_pg::protocol::AstEncoder::encode_cmd_sql(&cmd)
159                .expect("workflow schema command must encode through the AST path");
160        }
161    }
162}