Skip to main content

appstruct_migrate/
schema.rs

1use appstruct_ir::{
2    AppIr, DatabaseProvider, FieldTypeIr, GeneratedValueIr, IrValidationErrors, OnDeleteIr,
3    validate_app_ir,
4};
5use serde::{Deserialize, Serialize};
6
7mod audit;
8mod auth;
9mod file;
10mod jobs;
11mod mail;
12mod tenant;
13
14pub const SCHEMA_VERSION: u32 = appstruct_contracts::DATABASE_SCHEMA.current;
15pub const MIN_COMPATIBLE_SCHEMA_VERSION: u32 = appstruct_contracts::DATABASE_SCHEMA.minimum;
16
17#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
18pub struct DatabaseSchema {
19    pub schema_version: u32,
20    pub provider: DatabaseProvider,
21    pub tables: Vec<TableSchema>,
22    #[serde(default)]
23    pub unique_constraints: Vec<UniqueConstraintSchema>,
24    #[serde(default, skip_serializing_if = "Vec::is_empty")]
25    pub indexes: Vec<IndexSchema>,
26    #[serde(default, skip_serializing_if = "Vec::is_empty")]
27    pub seeds: Vec<SeedSchema>,
28    pub foreign_keys: Vec<ForeignKeySchema>,
29}
30
31#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
32pub struct TableSchema {
33    pub id: String,
34    pub name: String,
35    pub columns: Vec<ColumnSchema>,
36}
37
38#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
39pub struct ColumnSchema {
40    pub id: String,
41    pub name: String,
42    pub data_type: DatabaseType,
43    pub nullable: bool,
44    pub primary_key: bool,
45    pub unique: bool,
46    pub default: Option<String>,
47    pub generated: Option<GeneratedValueIr>,
48}
49
50#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
51#[serde(tag = "kind", rename_all = "snake_case")]
52pub enum DatabaseType {
53    Uuid,
54    Text,
55    Integer,
56    Bigint,
57    Decimal,
58    Boolean,
59    Date,
60    Datetime,
61    Json,
62    Enum { values: Vec<String> },
63}
64
65#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
66pub struct ForeignKeySchema {
67    pub id: String,
68    pub source_table: String,
69    #[serde(alias = "source_column", deserialize_with = "one_or_many")]
70    pub source_columns: Vec<String>,
71    pub target_table: String,
72    #[serde(alias = "target_column", deserialize_with = "one_or_many")]
73    pub target_columns: Vec<String>,
74    pub unique: bool,
75    pub on_delete: OnDeleteIr,
76}
77
78#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
79pub struct UniqueConstraintSchema {
80    pub id: String,
81    pub table: String,
82    pub columns: Vec<String>,
83}
84
85#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
86pub struct IndexSchema {
87    pub id: String,
88    pub table: String,
89    pub columns: Vec<String>,
90    pub unique: bool,
91    #[serde(default, skip_serializing_if = "Option::is_none")]
92    pub predicate: Option<String>,
93}
94
95#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
96pub struct SeedSchema {
97    pub id: String,
98    pub table: String,
99    pub values: Vec<SeedValueSchema>,
100}
101
102#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
103pub struct SeedValueSchema {
104    pub column: String,
105    pub value: String,
106    pub data_type: DatabaseType,
107}
108
109/// Extract a database schema from semantically valid IR.
110///
111/// # Errors
112///
113/// Returns all IR invariant violations before schema traversal begins.
114pub fn extract(ir: &AppIr) -> Result<DatabaseSchema, IrValidationErrors> {
115    validate_app_ir(ir)?;
116    let mut tables = ir
117        .entities
118        .iter()
119        .map(|entity| TableSchema {
120            id: entity.id.0.clone(),
121            name: entity.table_name.clone(),
122            columns: entity
123                .fields
124                .iter()
125                .map(|field| ColumnSchema {
126                    id: field.id.0.clone(),
127                    name: field.column_name.clone(),
128                    data_type: database_type(ir, &field.ty),
129                    nullable: field.nullable,
130                    primary_key: field.primary_key,
131                    unique: field.unique,
132                    default: field.default.clone(),
133                    generated: field.generated,
134                })
135                .collect(),
136        })
137        .collect::<Vec<_>>();
138    let unique_constraints = ir
139        .entities
140        .iter()
141        .filter(|entity| entity.tenant_scoped)
142        .map(tenant_unique_constraint)
143        .collect::<Vec<_>>();
144    let indexes = entity_indexes(ir);
145    let seeds = entity_seeds(ir);
146    let mut foreign_keys = ir
147        .relations
148        .iter()
149        .map(|relation| foreign_key(ir, relation))
150        .collect::<Vec<_>>();
151    if ir.auth.enabled {
152        tables.extend(auth::tables());
153        foreign_keys.extend(auth::foreign_keys(ir));
154    }
155    if ir.tenant.enabled {
156        tables.extend(tenant::tables());
157        foreign_keys.extend(tenant::foreign_keys(ir));
158    }
159    if ir.audit.enabled {
160        tables.extend(audit::tables());
161        foreign_keys.extend(audit::foreign_keys(ir));
162    }
163    if ir.mail.enabled {
164        tables.extend(mail::tables());
165        foreign_keys.extend(mail::foreign_keys(ir));
166    }
167    if ir.jobs.enabled {
168        tables.extend(jobs::tables());
169        foreign_keys.extend(jobs::foreign_keys(ir));
170    }
171    if ir.file.enabled {
172        tables.extend(file::tables());
173        foreign_keys.extend(file::foreign_keys(ir));
174    }
175    Ok(DatabaseSchema {
176        schema_version: SCHEMA_VERSION,
177        provider: ir.database.provider,
178        tables,
179        unique_constraints,
180        indexes,
181        seeds,
182        foreign_keys,
183    })
184}
185
186fn entity_indexes(ir: &AppIr) -> Vec<IndexSchema> {
187    ir.entities
188        .iter()
189        .flat_map(|entity| {
190            entity.indexes.iter().map(|index| IndexSchema {
191                id: index.id.clone(),
192                table: entity.table_name.clone(),
193                columns: index
194                    .fields
195                    .iter()
196                    .filter_map(|field_id| {
197                        entity
198                            .fields
199                            .iter()
200                            .find(|field| field.id == *field_id)
201                            .map(|field| field.column_name.clone())
202                    })
203                    .collect(),
204                unique: index.unique,
205                predicate: index.predicate.clone(),
206            })
207        })
208        .collect()
209}
210
211fn entity_seeds(ir: &AppIr) -> Vec<SeedSchema> {
212    ir.seeds
213        .iter()
214        .filter_map(|seed| {
215            let entity = ir.entities.iter().find(|entity| entity.id == seed.entity)?;
216            let values = seed
217                .values
218                .iter()
219                .filter_map(|(field_name, value)| {
220                    let field = entity.fields.iter().find(|field| {
221                        field.api_name == *field_name || field.rust_name == *field_name
222                    })?;
223                    Some(SeedValueSchema {
224                        column: field.column_name.clone(),
225                        value: value.clone(),
226                        data_type: database_type(ir, &field.ty),
227                    })
228                })
229                .collect::<Vec<_>>();
230            (!values.is_empty()).then_some(SeedSchema {
231                id: seed.id.clone(),
232                table: entity.table_name.clone(),
233                values,
234            })
235        })
236        .collect()
237}
238
239fn tenant_unique_constraint(entity: &appstruct_ir::EntityIr) -> UniqueConstraintSchema {
240    let key = entity
241        .fields
242        .iter()
243        .find(|field| field.primary_key)
244        .expect("compiler validated primary key");
245    UniqueConstraintSchema {
246        id: format!("{}.tenant_key", entity.id),
247        table: entity.table_name.clone(),
248        columns: vec!["tenant_id".to_owned(), key.column_name.clone()],
249    }
250}
251
252fn database_type(ir: &AppIr, field_type: &FieldTypeIr) -> DatabaseType {
253    match field_type {
254        FieldTypeIr::Uuid => DatabaseType::Uuid,
255        FieldTypeIr::String | FieldTypeIr::Text => DatabaseType::Text,
256        FieldTypeIr::Integer => DatabaseType::Integer,
257        FieldTypeIr::Bigint => DatabaseType::Bigint,
258        FieldTypeIr::Decimal => DatabaseType::Decimal,
259        FieldTypeIr::Boolean => DatabaseType::Boolean,
260        FieldTypeIr::Date => DatabaseType::Date,
261        FieldTypeIr::Datetime => DatabaseType::Datetime,
262        FieldTypeIr::Json => DatabaseType::Json,
263        FieldTypeIr::Enum { values } => DatabaseType::Enum {
264            values: values.clone(),
265        },
266        FieldTypeIr::Relation { target } => {
267            let target = ir
268                .entities
269                .iter()
270                .find(|entity| entity.id == *target)
271                .expect("compiler resolved relation target");
272            let key = target
273                .fields
274                .iter()
275                .find(|field| field.primary_key)
276                .expect("compiler validated primary key");
277            database_type(ir, &key.ty)
278        }
279    }
280}
281
282fn foreign_key(ir: &AppIr, relation: &appstruct_ir::RelationIr) -> ForeignKeySchema {
283    let source = ir
284        .entities
285        .iter()
286        .find(|entity| entity.id == relation.source)
287        .expect("compiler resolved relation source");
288    let target = ir
289        .entities
290        .iter()
291        .find(|entity| entity.id == relation.target)
292        .expect("compiler resolved relation target");
293    let source_field = source
294        .fields
295        .iter()
296        .find(|field| relation.foreign_key_fields.contains(&field.id))
297        .expect("compiler resolved relation field");
298    let target_field = target
299        .fields
300        .iter()
301        .find(|field| field.primary_key)
302        .expect("compiler validated target key");
303    let tenant_relation = source.tenant_scoped && target.tenant_scoped;
304    ForeignKeySchema {
305        id: relation.id.0.clone(),
306        source_table: source.table_name.clone(),
307        source_columns: if tenant_relation {
308            vec!["tenant_id".to_owned(), source_field.column_name.clone()]
309        } else {
310            vec![source_field.column_name.clone()]
311        },
312        target_table: target.table_name.clone(),
313        target_columns: if tenant_relation {
314            vec!["tenant_id".to_owned(), target_field.column_name.clone()]
315        } else {
316            vec![target_field.column_name.clone()]
317        },
318        unique: relation.unique,
319        on_delete: relation.on_delete,
320    }
321}
322
323fn one_or_many<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error>
324where
325    D: serde::Deserializer<'de>,
326{
327    #[derive(Deserialize)]
328    #[serde(untagged)]
329    enum Columns {
330        One(String),
331        Many(Vec<String>),
332    }
333
334    Ok(match Columns::deserialize(deserializer)? {
335        Columns::One(column) => vec![column],
336        Columns::Many(columns) => columns,
337    })
338}
339
340/// Serialize a canonical schema snapshot.
341///
342/// # Errors
343///
344/// Returns an error if JSON serialization unexpectedly fails.
345pub fn to_json(schema: &DatabaseSchema) -> Result<String, serde_json::Error> {
346    let mut value = serde_json::to_string_pretty(schema)?;
347    value.push('\n');
348    Ok(value)
349}
350
351/// Parse a schema snapshot.
352///
353/// # Errors
354///
355/// Returns an error if the snapshot is invalid or incompatible JSON.
356pub fn from_json(source: &str) -> Result<DatabaseSchema, serde_json::Error> {
357    let mut schema: DatabaseSchema = serde_json::from_str(source)?;
358    match schema.schema_version {
359        SCHEMA_VERSION => Ok(schema),
360        MIN_COMPATIBLE_SCHEMA_VERSION => {
361            schema.schema_version = SCHEMA_VERSION;
362            Ok(schema)
363        }
364        found => Err(serde_json::Error::io(std::io::Error::new(
365            std::io::ErrorKind::InvalidData,
366            format!(
367                "unsupported schema snapshot version {found}; supported versions are {MIN_COMPATIBLE_SCHEMA_VERSION} through {SCHEMA_VERSION}"
368            ),
369        ))),
370    }
371}