Skip to main content

yang_base/database/schema_sync/
sync.rs

1use super::super::DatabaseInitializer;
2use super::driver::SchemaConnection;
3use super::driver::{OwnedSchemaConnection, SchemaDriver};
4use super::plan::{plan_locked, report_tables};
5use super::preflight::{format_violations, preflight_locked};
6use super::{SchemaPreflightReport, SchemaSyncChangeKind, SchemaSyncReport};
7use crate::error::BaseError;
8#[cfg(feature = "mysql")]
9use crate::table::SchemaColumn;
10use crate::table::{SchemaValidationReport, TableDefinition};
11
12impl DatabaseInitializer {
13    /// 从数据库读取当前列并验证表定义的运行期字段契约。
14    ///
15    /// 本方法只读,不生成或执行 ALTER;数据库额外列不视为问题。
16    pub async fn validate_table_definition(
17        &self,
18        table: &TableDefinition,
19    ) -> Result<SchemaValidationReport, BaseError> {
20        let driver = self.schema_driver()?;
21        match driver {
22            #[cfg(feature = "mysql")]
23            SchemaDriver::MySql => {
24                #[derive(sqlx::FromRow)]
25                struct ColumnRow {
26                    column_name: String,
27                    data_type: String,
28                    column_type: String,
29                    is_nullable: String,
30                    character_maximum_length: Option<i64>,
31                    column_default: Option<String>,
32                    extra: String,
33                }
34
35                let database = self.db().as_mysql().ok_or_else(|| {
36                    BaseError::DatabaseInitFailed(
37                        "DatabaseInitializer 未持有 MySQL 后端".to_string(),
38                    )
39                })?;
40                let rows: Vec<ColumnRow> = database
41                    .query_with_params(
42                        "SELECT CAST(COLUMN_NAME AS CHAR) AS column_name, CAST(DATA_TYPE AS CHAR) AS data_type, CAST(COLUMN_TYPE AS CHAR) AS column_type, CAST(IS_NULLABLE AS CHAR) AS is_nullable, CAST(CHARACTER_MAXIMUM_LENGTH AS SIGNED) AS character_maximum_length, CAST(COLUMN_DEFAULT AS CHAR) AS column_default, CAST(EXTRA AS CHAR) AS extra FROM information_schema.columns WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? ORDER BY ORDINAL_POSITION",
43                        vec![serde_json::Value::String(table.name().to_string())],
44                    )
45                    .await
46                    .map_err(BaseError::DatabaseQueryFailed)?;
47                let columns = rows
48                    .into_iter()
49                    .map(|row| {
50                        SchemaColumn::new(
51                            row.column_name,
52                            row.data_type,
53                            row.column_type,
54                            row.is_nullable.eq_ignore_ascii_case("YES"),
55                            row.character_maximum_length
56                                .and_then(|length| u64::try_from(length).ok()),
57                            row.column_default,
58                        )
59                        .with_auto_increment(
60                            row.extra
61                                .split_whitespace()
62                                .any(|part| part.eq_ignore_ascii_case("auto_increment")),
63                        )
64                    })
65                    .collect::<Vec<_>>();
66                Ok(table.validate_schema(&columns))
67            }
68            #[cfg(feature = "postgres")]
69            SchemaDriver::PostgreSql => {
70                let mut owned = self.acquire_schema_connection().await?;
71                let mut connection = owned.as_schema();
72                let existing = driver.introspect(&mut connection, table).await?;
73                let config = table.shared_config();
74                Ok(driver.dialect().validate_schema(config.as_ref(), &existing))
75            }
76        }
77    }
78
79    /// 只读取当前数据库 schema 并计算待执行变更,不获取同步锁、不执行 DDL。
80    ///
81    /// 适用于生产启动门禁:返回非空 `changes` 表示数据库尚未与定义对齐;不兼容
82    /// 变更仍返回错误。调用方若要实际应用变更,应使用 [`Self::sync_table_definitions`]。
83    pub async fn plan_table_definitions(
84        &self,
85        definitions: &[&TableDefinition],
86    ) -> Result<SchemaSyncReport, BaseError> {
87        let driver = self.schema_driver()?;
88        let definitions = driver.dialect().normalize_definitions(definitions)?;
89        if definitions.is_empty() {
90            return Ok(SchemaSyncReport::default());
91        }
92        let mut owned = self.acquire_schema_connection().await?;
93        let mut connection = owned.as_schema();
94        let plans = plan_locked(driver, &mut connection, &definitions).await?;
95        let (statements, deferred_statements) = plan_statements(&plans);
96        Ok(SchemaSyncReport {
97            tables: report_tables(&definitions),
98            changes: plans.into_iter().flat_map(|plan| plan.changes).collect(),
99            statements,
100            deferred_statements,
101            bindings: Vec::new(),
102        })
103    }
104
105    /// 只读预检结构计划及会阻止新约束生效的旧数据。
106    pub async fn preflight_table_definitions(
107        &self,
108        definitions: &[&TableDefinition],
109    ) -> Result<SchemaPreflightReport, BaseError> {
110        let driver = self.schema_driver()?;
111        let definitions = driver.dialect().normalize_definitions(definitions)?;
112        if definitions.is_empty() {
113            return Ok(SchemaPreflightReport::default());
114        }
115        let mut owned = self.acquire_schema_connection().await?;
116        let mut connection = owned.as_schema();
117        let plans = plan_locked(driver, &mut connection, &definitions).await?;
118        let (statements, deferred_statements) = plan_statements(&plans);
119        let violations =
120            preflight_locked(driver.dialect(), &mut connection, &definitions, &plans).await?;
121        Ok(SchemaPreflightReport {
122            plan: SchemaSyncReport {
123                tables: report_tables(&definitions),
124                changes: plans
125                    .iter()
126                    .flat_map(|plan| plan.changes.iter().cloned())
127                    .collect(),
128                statements,
129                deferred_statements,
130                bindings: Vec::new(),
131            },
132            violations,
133        })
134    }
135
136    /// 同步一组不可变表定义。
137    ///
138    /// 多实例启动使用数据库级 advisory lock 串行化:MySQL 用 `GET_LOCK`,
139    /// PostgreSQL 用 `pg_advisory_lock(bigint)`(session 级)。PostgreSQL 按阶段
140    /// 执行:地基 DDL(建表/加列)→ 同事务预检 → 其余事务步骤 → 提交 →
141    /// 并发索引与非外键 `VALIDATE CONSTRAINT` → 外键事务(`ADD ... NOT VALID`)→
142    /// 提交后执行外键 `VALIDATE CONSTRAINT`。
143    ///
144    /// Foundation 与 Main 阶段共享同一事务,整体提交或回滚;Concurrent 与外键阶段
145    /// 在提交后以 autocommit 执行,失败不会回滚已提交的 DDL,只会留下可重试状态
146    /// (INVALID 索引 / `NOT VALID` 约束),下次同步会自动自愈。
147    pub async fn sync_table_definitions(
148        &self,
149        definitions: &[&TableDefinition],
150    ) -> Result<SchemaSyncReport, BaseError> {
151        let driver = self.schema_driver()?;
152        let definitions = driver.dialect().normalize_definitions(definitions)?;
153        if definitions.is_empty() {
154            return Ok(SchemaSyncReport::default());
155        }
156        if let Some(definition) = definitions.iter().find(|definition| {
157            definition
158                .name()
159                .rsplit('.')
160                .next()
161                .is_some_and(|name| name == super::binding::BINDING_TABLE)
162        }) {
163            return Err(BaseError::ConfigError(format!(
164                "表 {} 是框架保留的系统表,不能由模块声明",
165                definition.name()
166            )));
167        }
168        let datasource = self.db().id().clone();
169
170        let mut owned = self.acquire_schema_connection().await?;
171        let mut connection = owned.as_schema();
172        let lock = driver.lock(&mut connection).await?;
173        let result = sync_locked(driver, &mut connection, &definitions, &datasource).await;
174        // 复位会话级 lock_timeout:连接归还池后会被业务查询复用。
175        let reset_result = driver.reset_session(&mut connection).await;
176        let release_result = driver.unlock(&mut connection, &lock).await;
177
178        let result = match result {
179            Ok(report) => reset_result.map(|()| report),
180            Err(error) => {
181                // 同步失败时保留原始错误;复位失败只记录(连接随后仍会归还池)。
182                if let Err(reset_error) = &reset_result {
183                    tracing::warn!(
184                        error = %reset_error,
185                        "schema 同步失败后复位会话参数失败"
186                    );
187                }
188                Err(error)
189            }
190        };
191
192        match (result, release_result) {
193            (Err(error), _) => Err(error),
194            (Ok(_), Err(error)) => Err(error),
195            (Ok(report), Ok(())) => Ok(report),
196        }
197    }
198
199    /// 选择当前后端的 schema 驱动。
200    pub(crate) fn schema_driver(&self) -> Result<SchemaDriver, BaseError> {
201        SchemaDriver::for_backend(self.db().backend())
202    }
203
204    /// 从 [`super::super::AnyDatabase`] 借出一个 schema 同步连接。
205    pub(crate) async fn acquire_schema_connection(
206        &self,
207    ) -> Result<OwnedSchemaConnection, BaseError> {
208        #[cfg(feature = "mysql")]
209        if let Some(database) = self.db().as_mysql() {
210            let connection = database
211                .pool()
212                .acquire()
213                .await
214                .map_err(|error| BaseError::DatabaseConnectionDbError(error.into()))?;
215            return Ok(OwnedSchemaConnection::MySql(connection));
216        }
217        #[cfg(feature = "postgres")]
218        if let Some(database) = self.db().as_postgres() {
219            let connection = database
220                .pool()
221                .acquire()
222                .await
223                .map_err(|error| BaseError::DatabaseConnectionDbError(error.into()))?;
224            return Ok(OwnedSchemaConnection::PostgreSql(connection));
225        }
226        Err(BaseError::DatabaseInitFailed(
227            "DatabaseInitializer 未持有可用的数据库后端".to_string(),
228        ))
229    }
230}
231
232/// 步骤的执行阶段。
233#[derive(Debug, Clone, Copy, PartialEq, Eq)]
234enum StepPhase {
235    /// 地基步骤(建表/加列):必须先落地,预检 SQL 才能看到新列。
236    Foundation,
237    /// 其余事务内、非外键步骤。
238    Main,
239    /// 事务提交后以 autocommit 执行:并发索引 + 非外键步骤的 deferred 语句。
240    Concurrent,
241    /// 外键事务(`ADD ... NOT VALID`)。
242    ForeignKeys,
243    /// 外键事务提交后执行 FK 步骤的 deferred 语句(`VALIDATE CONSTRAINT`)。
244    PostForeignKeys,
245    /// MySQL:全部非外键步骤(预检先于 DDL,无需地基阶段)。
246    AllNonForeignKey,
247}
248
249impl StepPhase {
250    /// 本阶段是否执行该步骤的 `statements`。
251    fn runs_statements(self, step: &super::model::PlanStep) -> bool {
252        let is_foreign_key = matches!(
253            step.change.kind,
254            SchemaSyncChangeKind::AddedForeignKey | SchemaSyncChangeKind::ValidatedForeignKey
255        );
256        match self {
257            Self::Foundation => {
258                !step.concurrent
259                    && !is_foreign_key
260                    && matches!(
261                        step.change.kind,
262                        SchemaSyncChangeKind::CreatedTable
263                            | SchemaSyncChangeKind::AddedColumn
264                            | SchemaSyncChangeKind::CreatedEnumType
265                            | SchemaSyncChangeKind::AddedEnumValue
266                    )
267            }
268            Self::Main => {
269                !step.concurrent
270                    && !is_foreign_key
271                    && !matches!(
272                        step.change.kind,
273                        SchemaSyncChangeKind::CreatedTable
274                            | SchemaSyncChangeKind::AddedColumn
275                            | SchemaSyncChangeKind::CreatedEnumType
276                            | SchemaSyncChangeKind::AddedEnumValue
277                    )
278            }
279            Self::Concurrent => step.concurrent,
280            Self::ForeignKeys => !step.concurrent && is_foreign_key,
281            Self::PostForeignKeys => false,
282            Self::AllNonForeignKey => !step.concurrent && !is_foreign_key,
283        }
284    }
285
286    /// 本阶段是否执行该步骤的 deferred 语句(仅提交后阶段)。
287    ///
288    /// `Concurrent` 只处理非外键步骤;外键的 `VALIDATE` 属于 `PostForeignKeys`,
289    /// 在外键事务提交后单独执行。
290    fn runs_deferred(self, step: &super::model::PlanStep) -> bool {
291        if step.deferred_statements.is_empty() {
292            return false;
293        }
294        let is_foreign_key = matches!(
295            step.change.kind,
296            SchemaSyncChangeKind::AddedForeignKey | SchemaSyncChangeKind::ValidatedForeignKey
297        );
298        match self {
299            Self::Concurrent => !is_foreign_key,
300            Self::PostForeignKeys => is_foreign_key,
301            _ => false,
302        }
303    }
304}
305
306async fn sync_locked(
307    driver: SchemaDriver,
308    connection: &mut SchemaConnection<'_>,
309    definitions: &[&TableDefinition],
310    datasource: &crate::datasource::DatasourceId,
311) -> Result<SchemaSyncReport, BaseError> {
312    driver.configure_session(connection).await?;
313    let plans = plan_locked(driver, connection, definitions).await?;
314
315    // 所有权绑定必须先于 DDL 落库:MySQL 的 DDL 隐式提交、PostgreSQL 的并发索引
316    // 也在主事务提交后执行;若等 DDL 成功后再写绑定,进程中断或后续步骤失败会
317    // 让框架建的表在下次启动时被误判为 adopted。
318    super::binding::ensure_binding_table(driver, connection).await?;
319    let existing_bindings = super::binding::load_bindings(connection, datasource).await?;
320    let planned_changes = plans
321        .iter()
322        .flat_map(|plan| plan.changes.iter().cloned())
323        .collect::<Vec<_>>();
324    let binding_updates =
325        binding_updates(driver, definitions, &existing_bindings, &planned_changes)?;
326    super::binding::upsert_bindings(connection, datasource, &binding_updates).await?;
327
328    if driver.transactional_ddl() {
329        // PostgreSQL:地基步骤 -> 同事务内预检(能看到新列)-> 其余事务步骤
330        // -> 提交 -> 并发索引与 deferred VALIDATE -> 外键事务。
331        connection.begin().await?;
332        let transaction = async {
333            execute_steps(connection, &plans, StepPhase::Foundation).await?;
334            let violations = driver.preflight(connection, definitions, &plans).await?;
335            if !violations.is_empty() {
336                return Err(BaseError::DatabaseInitFailed(format_violations(
337                    &violations,
338                )));
339            }
340            execute_steps(connection, &plans, StepPhase::Main).await
341        }
342        .await;
343        match transaction {
344            Ok(()) => connection.commit().await?,
345            Err(error) => {
346                // 回滚失败不覆盖原始 DDL/预检错误,调用方应优先处理根因。
347                let _ = connection.rollback().await;
348                return Err(error);
349            }
350        }
351        // CREATE/DROP INDEX CONCURRENTLY 不能在事务块内执行;非外键步骤的
352        // deferred `VALIDATE CONSTRAINT`(CHECK 等)也在此阶段以 autocommit 执行。
353        execute_steps(connection, &plans, StepPhase::Concurrent).await?;
354        // 外键最后执行,确保它依赖的唯一索引(可能刚并发创建)已存在。
355        if plans
356            .iter()
357            .flat_map(|plan| &plan.steps)
358            .any(|step| step.change.kind == SchemaSyncChangeKind::AddedForeignKey)
359        {
360            connection.begin().await?;
361            match execute_steps(connection, &plans, StepPhase::ForeignKeys).await {
362                Ok(()) => connection.commit().await?,
363                Err(error) => {
364                    let _ = connection.rollback().await;
365                    return Err(error);
366                }
367            }
368        }
369        // 外键事务提交后再 VALIDATE,避免 ADD 的 ShareRowExclusiveLock 持有到验证结束;
370        // 仅需自愈验证的既有外键也会在这里执行。
371        execute_steps(connection, &plans, StepPhase::PostForeignKeys).await?;
372    } else {
373        // MySQL:保持既有顺序,预检先于全部 DDL。
374        let violations = driver.preflight(connection, definitions, &plans).await?;
375        if !violations.is_empty() {
376            return Err(BaseError::DatabaseInitFailed(format_violations(
377                &violations,
378            )));
379        }
380        execute_steps(connection, &plans, StepPhase::AllNonForeignKey).await?;
381        execute_steps(connection, &plans, StepPhase::ForeignKeys).await?;
382    }
383
384    // 报告按计划顺序生成,保证每个 step 恰好一条且顺序稳定(与执行阶段无关)。
385    let (statements, deferred_statements) = plan_statements(&plans);
386    Ok(SchemaSyncReport {
387        tables: report_tables(definitions),
388        changes: plans
389            .iter()
390            .flat_map(|plan| plan.steps.iter().map(|step| step.change.clone()))
391            .collect(),
392        statements,
393        deferred_statements,
394        bindings: binding_updates
395            .iter()
396            .map(|update| super::SchemaBindingChange {
397                datasource: datasource.clone(),
398                table: update.table.clone(),
399                mode: update.mode,
400                newly_bound: update.newly_bound,
401            })
402            .collect(),
403    })
404}
405
406/// 汇总计划中的事务内与 deferred DDL 文本,供同步/dry-run 报告审计。
407fn plan_statements(plans: &[super::model::TableSyncPlan]) -> (Vec<String>, Vec<String>) {
408    let mut statements = Vec::new();
409    let mut deferred_statements = Vec::new();
410    for plan in plans {
411        for step in &plan.steps {
412            statements.extend(step.statements.iter().cloned());
413            deferred_statements.extend(step.deferred_statements.iter().cloned());
414        }
415    }
416    (statements, deferred_statements)
417}
418
419/// 计算本轮需要写入的所有权绑定。
420///
421/// - 首次登记时:本轮由框架建表 → `managed`;表已存在 → `adopted`。
422/// - 已登记为 `adopted` 的表一旦被框架实际演进,即进入 `managed`。
423fn binding_updates(
424    driver: SchemaDriver,
425    definitions: &[&TableDefinition],
426    existing: &std::collections::BTreeMap<String, super::binding::BindingRecord>,
427    changes: &[super::SchemaSyncChange],
428) -> Result<Vec<super::binding::BindingUpdate>, BaseError> {
429    let changed = changes
430        .iter()
431        .map(|change| change.table.as_str())
432        .collect::<std::collections::BTreeSet<_>>();
433    let now = super::binding::now_unix_seconds();
434    let mut updates = Vec::new();
435    for definition in definitions {
436        let table = definition.name().to_string();
437        let fingerprint = super::binding::table_fingerprint(driver, definition)?;
438        let record = existing.get(&table);
439        let (mode, newly_bound) = match record {
440            Some(record) => {
441                let mode = if record.mode == super::SchemaBindingMode::Adopted
442                    && changed.contains(table.as_str())
443                {
444                    super::SchemaBindingMode::Managed
445                } else {
446                    record.mode
447                };
448                (mode, false)
449            }
450            // 首次登记:框架本轮建表或演进过的表直接归 managed;完全未动的
451            // 存量表先记为 adopted,等待下一次实际演进或在报告中人工确认。
452            None if changed.contains(table.as_str()) => (super::SchemaBindingMode::Managed, true),
453            None => (super::SchemaBindingMode::Adopted, true),
454        };
455        let needs_write = record.map_or(true, |record| {
456            record.mode != mode || record.fingerprint != fingerprint
457        });
458        if needs_write {
459            updates.push(super::binding::BindingUpdate {
460                table,
461                mode,
462                fingerprint,
463                adopted_at: now,
464                newly_bound,
465            });
466        }
467    }
468    Ok(updates)
469}
470
471async fn execute_steps(
472    connection: &mut SchemaConnection<'_>,
473    plans: &[super::model::TableSyncPlan],
474    phase: StepPhase,
475) -> Result<(), BaseError> {
476    for plan in plans {
477        for step in &plan.steps {
478            let run_statements = phase.runs_statements(step);
479            let run_deferred = phase.runs_deferred(step);
480            if !run_statements && !run_deferred {
481                continue;
482            }
483            if run_statements {
484                for statement in &step.statements {
485                    connection.execute(statement).await?;
486                }
487            }
488            if run_deferred {
489                for statement in &step.deferred_statements {
490                    connection.execute(statement).await?;
491                }
492            }
493            tracing::info!(
494                table = %step.change.table,
495                object = %step.change.object,
496                kind = ?step.change.kind,
497                phase = ?phase,
498                "数据库 schema 已同步"
499            );
500        }
501    }
502    Ok(())
503}