yang-base 0.6.0

个人使用构建后端服务器
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
use super::super::DatabaseInitializer;
use super::driver::SchemaConnection;
use super::driver::{OwnedSchemaConnection, SchemaDriver};
use super::plan::{plan_locked, report_tables};
use super::preflight::{format_violations, preflight_locked};
use super::{SchemaPreflightReport, SchemaSyncChangeKind, SchemaSyncReport};
use crate::error::BaseError;
#[cfg(feature = "mysql")]
use crate::table::SchemaColumn;
use crate::table::{SchemaValidationReport, TableDefinition};

impl DatabaseInitializer {
    /// 从数据库读取当前列并验证表定义的运行期字段契约。
    ///
    /// 本方法只读,不生成或执行 ALTER;数据库额外列不视为问题。
    pub async fn validate_table_definition(
        &self,
        table: &TableDefinition,
    ) -> Result<SchemaValidationReport, BaseError> {
        let driver = self.schema_driver()?;
        match driver {
            #[cfg(feature = "mysql")]
            SchemaDriver::MySql => {
                #[derive(sqlx::FromRow)]
                struct ColumnRow {
                    column_name: String,
                    data_type: String,
                    column_type: String,
                    is_nullable: String,
                    character_maximum_length: Option<i64>,
                    column_default: Option<String>,
                    extra: String,
                }

                let database = self.db().as_mysql().ok_or_else(|| {
                    BaseError::DatabaseInitFailed(
                        "DatabaseInitializer 未持有 MySQL 后端".to_string(),
                    )
                })?;
                let rows: Vec<ColumnRow> = database
                    .query_with_params(
                        "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",
                        vec![serde_json::Value::String(table.name().to_string())],
                    )
                    .await
                    .map_err(BaseError::DatabaseQueryFailed)?;
                let columns = rows
                    .into_iter()
                    .map(|row| {
                        SchemaColumn::new(
                            row.column_name,
                            row.data_type,
                            row.column_type,
                            row.is_nullable.eq_ignore_ascii_case("YES"),
                            row.character_maximum_length
                                .and_then(|length| u64::try_from(length).ok()),
                            row.column_default,
                        )
                        .with_auto_increment(
                            row.extra
                                .split_whitespace()
                                .any(|part| part.eq_ignore_ascii_case("auto_increment")),
                        )
                    })
                    .collect::<Vec<_>>();
                Ok(table.validate_schema(&columns))
            }
            #[cfg(feature = "postgres")]
            SchemaDriver::PostgreSql => {
                let mut owned = self.acquire_schema_connection().await?;
                let mut connection = owned.as_schema();
                let existing = driver.introspect(&mut connection, table).await?;
                let config = table.shared_config();
                Ok(driver.dialect().validate_schema(config.as_ref(), &existing))
            }
        }
    }

    /// 只读取当前数据库 schema 并计算待执行变更,不获取同步锁、不执行 DDL。
    ///
    /// 适用于生产启动门禁:返回非空 `changes` 表示数据库尚未与定义对齐;不兼容
    /// 变更仍返回错误。调用方若要实际应用变更,应使用 [`Self::sync_table_definitions`]。
    pub async fn plan_table_definitions(
        &self,
        definitions: &[&TableDefinition],
    ) -> Result<SchemaSyncReport, BaseError> {
        let driver = self.schema_driver()?;
        let definitions = driver.dialect().normalize_definitions(definitions)?;
        if definitions.is_empty() {
            return Ok(SchemaSyncReport::default());
        }
        let mut owned = self.acquire_schema_connection().await?;
        let mut connection = owned.as_schema();
        let plans = plan_locked(driver, &mut connection, &definitions).await?;
        let (statements, deferred_statements) = plan_statements(&plans);
        Ok(SchemaSyncReport {
            tables: report_tables(&definitions),
            changes: plans.into_iter().flat_map(|plan| plan.changes).collect(),
            statements,
            deferred_statements,
            bindings: Vec::new(),
        })
    }

    /// 只读预检结构计划及会阻止新约束生效的旧数据。
    pub async fn preflight_table_definitions(
        &self,
        definitions: &[&TableDefinition],
    ) -> Result<SchemaPreflightReport, BaseError> {
        let driver = self.schema_driver()?;
        let definitions = driver.dialect().normalize_definitions(definitions)?;
        if definitions.is_empty() {
            return Ok(SchemaPreflightReport::default());
        }
        let mut owned = self.acquire_schema_connection().await?;
        let mut connection = owned.as_schema();
        let plans = plan_locked(driver, &mut connection, &definitions).await?;
        let (statements, deferred_statements) = plan_statements(&plans);
        let violations =
            preflight_locked(driver.dialect(), &mut connection, &definitions, &plans).await?;
        Ok(SchemaPreflightReport {
            plan: SchemaSyncReport {
                tables: report_tables(&definitions),
                changes: plans
                    .iter()
                    .flat_map(|plan| plan.changes.iter().cloned())
                    .collect(),
                statements,
                deferred_statements,
                bindings: Vec::new(),
            },
            violations,
        })
    }

    /// 同步一组不可变表定义。
    ///
    /// 多实例启动使用数据库级 advisory lock 串行化:MySQL 用 `GET_LOCK`,
    /// PostgreSQL 用 `pg_advisory_lock(bigint)`(session 级)。PostgreSQL 按阶段
    /// 执行:地基 DDL(建表/加列)→ 同事务预检 → 其余事务步骤 → 提交 →
    /// 并发索引与非外键 `VALIDATE CONSTRAINT` → 外键事务(`ADD ... NOT VALID`)→
    /// 提交后执行外键 `VALIDATE CONSTRAINT`。
    ///
    /// Foundation 与 Main 阶段共享同一事务,整体提交或回滚;Concurrent 与外键阶段
    /// 在提交后以 autocommit 执行,失败不会回滚已提交的 DDL,只会留下可重试状态
    /// (INVALID 索引 / `NOT VALID` 约束),下次同步会自动自愈。
    pub async fn sync_table_definitions(
        &self,
        definitions: &[&TableDefinition],
    ) -> Result<SchemaSyncReport, BaseError> {
        let driver = self.schema_driver()?;
        let definitions = driver.dialect().normalize_definitions(definitions)?;
        if definitions.is_empty() {
            return Ok(SchemaSyncReport::default());
        }
        if let Some(definition) = definitions.iter().find(|definition| {
            definition
                .name()
                .rsplit('.')
                .next()
                .is_some_and(|name| name == super::binding::BINDING_TABLE)
        }) {
            return Err(BaseError::ConfigError(format!(
                "表 {} 是框架保留的系统表,不能由模块声明",
                definition.name()
            )));
        }
        let datasource = self.db().id().clone();

        let mut owned = self.acquire_schema_connection().await?;
        let mut connection = owned.as_schema();
        let lock = driver.lock(&mut connection).await?;
        let result = sync_locked(driver, &mut connection, &definitions, &datasource).await;
        // 复位会话级 lock_timeout:连接归还池后会被业务查询复用。
        let reset_result = driver.reset_session(&mut connection).await;
        let release_result = driver.unlock(&mut connection, &lock).await;

        let result = match result {
            Ok(report) => reset_result.map(|()| report),
            Err(error) => {
                // 同步失败时保留原始错误;复位失败只记录(连接随后仍会归还池)。
                if let Err(reset_error) = &reset_result {
                    tracing::warn!(
                        error = %reset_error,
                        "schema 同步失败后复位会话参数失败"
                    );
                }
                Err(error)
            }
        };

        match (result, release_result) {
            (Err(error), _) => Err(error),
            (Ok(_), Err(error)) => Err(error),
            (Ok(report), Ok(())) => Ok(report),
        }
    }

    /// 选择当前后端的 schema 驱动。
    pub(crate) fn schema_driver(&self) -> Result<SchemaDriver, BaseError> {
        SchemaDriver::for_backend(self.db().backend())
    }

    /// 从 [`super::super::AnyDatabase`] 借出一个 schema 同步连接。
    pub(crate) async fn acquire_schema_connection(
        &self,
    ) -> Result<OwnedSchemaConnection, BaseError> {
        #[cfg(feature = "mysql")]
        if let Some(database) = self.db().as_mysql() {
            let connection = database
                .pool()
                .acquire()
                .await
                .map_err(|error| BaseError::DatabaseConnectionDbError(error.into()))?;
            return Ok(OwnedSchemaConnection::MySql(connection));
        }
        #[cfg(feature = "postgres")]
        if let Some(database) = self.db().as_postgres() {
            let connection = database
                .pool()
                .acquire()
                .await
                .map_err(|error| BaseError::DatabaseConnectionDbError(error.into()))?;
            return Ok(OwnedSchemaConnection::PostgreSql(connection));
        }
        Err(BaseError::DatabaseInitFailed(
            "DatabaseInitializer 未持有可用的数据库后端".to_string(),
        ))
    }
}

/// 步骤的执行阶段。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum StepPhase {
    /// 地基步骤(建表/加列):必须先落地,预检 SQL 才能看到新列。
    Foundation,
    /// 其余事务内、非外键步骤。
    Main,
    /// 事务提交后以 autocommit 执行:并发索引 + 非外键步骤的 deferred 语句。
    Concurrent,
    /// 外键事务(`ADD ... NOT VALID`)。
    ForeignKeys,
    /// 外键事务提交后执行 FK 步骤的 deferred 语句(`VALIDATE CONSTRAINT`)。
    PostForeignKeys,
    /// MySQL:全部非外键步骤(预检先于 DDL,无需地基阶段)。
    AllNonForeignKey,
}

impl StepPhase {
    /// 本阶段是否执行该步骤的 `statements`。
    fn runs_statements(self, step: &super::model::PlanStep) -> bool {
        let is_foreign_key = matches!(
            step.change.kind,
            SchemaSyncChangeKind::AddedForeignKey | SchemaSyncChangeKind::ValidatedForeignKey
        );
        match self {
            Self::Foundation => {
                !step.concurrent
                    && !is_foreign_key
                    && matches!(
                        step.change.kind,
                        SchemaSyncChangeKind::CreatedTable
                            | SchemaSyncChangeKind::AddedColumn
                            | SchemaSyncChangeKind::CreatedEnumType
                            | SchemaSyncChangeKind::AddedEnumValue
                    )
            }
            Self::Main => {
                !step.concurrent
                    && !is_foreign_key
                    && !matches!(
                        step.change.kind,
                        SchemaSyncChangeKind::CreatedTable
                            | SchemaSyncChangeKind::AddedColumn
                            | SchemaSyncChangeKind::CreatedEnumType
                            | SchemaSyncChangeKind::AddedEnumValue
                    )
            }
            Self::Concurrent => step.concurrent,
            Self::ForeignKeys => !step.concurrent && is_foreign_key,
            Self::PostForeignKeys => false,
            Self::AllNonForeignKey => !step.concurrent && !is_foreign_key,
        }
    }

    /// 本阶段是否执行该步骤的 deferred 语句(仅提交后阶段)。
    ///
    /// `Concurrent` 只处理非外键步骤;外键的 `VALIDATE` 属于 `PostForeignKeys`,
    /// 在外键事务提交后单独执行。
    fn runs_deferred(self, step: &super::model::PlanStep) -> bool {
        if step.deferred_statements.is_empty() {
            return false;
        }
        let is_foreign_key = matches!(
            step.change.kind,
            SchemaSyncChangeKind::AddedForeignKey | SchemaSyncChangeKind::ValidatedForeignKey
        );
        match self {
            Self::Concurrent => !is_foreign_key,
            Self::PostForeignKeys => is_foreign_key,
            _ => false,
        }
    }
}

async fn sync_locked(
    driver: SchemaDriver,
    connection: &mut SchemaConnection<'_>,
    definitions: &[&TableDefinition],
    datasource: &crate::datasource::DatasourceId,
) -> Result<SchemaSyncReport, BaseError> {
    driver.configure_session(connection).await?;
    let plans = plan_locked(driver, connection, definitions).await?;

    // 所有权绑定必须先于 DDL 落库:MySQL 的 DDL 隐式提交、PostgreSQL 的并发索引
    // 也在主事务提交后执行;若等 DDL 成功后再写绑定,进程中断或后续步骤失败会
    // 让框架建的表在下次启动时被误判为 adopted。
    super::binding::ensure_binding_table(driver, connection).await?;
    let existing_bindings = super::binding::load_bindings(connection, datasource).await?;
    let planned_changes = plans
        .iter()
        .flat_map(|plan| plan.changes.iter().cloned())
        .collect::<Vec<_>>();
    let binding_updates =
        binding_updates(driver, definitions, &existing_bindings, &planned_changes)?;
    super::binding::upsert_bindings(connection, datasource, &binding_updates).await?;

    if driver.transactional_ddl() {
        // PostgreSQL:地基步骤 -> 同事务内预检(能看到新列)-> 其余事务步骤
        // -> 提交 -> 并发索引与 deferred VALIDATE -> 外键事务。
        connection.begin().await?;
        let transaction = async {
            execute_steps(connection, &plans, StepPhase::Foundation).await?;
            let violations = driver.preflight(connection, definitions, &plans).await?;
            if !violations.is_empty() {
                return Err(BaseError::DatabaseInitFailed(format_violations(
                    &violations,
                )));
            }
            execute_steps(connection, &plans, StepPhase::Main).await
        }
        .await;
        match transaction {
            Ok(()) => connection.commit().await?,
            Err(error) => {
                // 回滚失败不覆盖原始 DDL/预检错误,调用方应优先处理根因。
                let _ = connection.rollback().await;
                return Err(error);
            }
        }
        // CREATE/DROP INDEX CONCURRENTLY 不能在事务块内执行;非外键步骤的
        // deferred `VALIDATE CONSTRAINT`(CHECK 等)也在此阶段以 autocommit 执行。
        execute_steps(connection, &plans, StepPhase::Concurrent).await?;
        // 外键最后执行,确保它依赖的唯一索引(可能刚并发创建)已存在。
        if plans
            .iter()
            .flat_map(|plan| &plan.steps)
            .any(|step| step.change.kind == SchemaSyncChangeKind::AddedForeignKey)
        {
            connection.begin().await?;
            match execute_steps(connection, &plans, StepPhase::ForeignKeys).await {
                Ok(()) => connection.commit().await?,
                Err(error) => {
                    let _ = connection.rollback().await;
                    return Err(error);
                }
            }
        }
        // 外键事务提交后再 VALIDATE,避免 ADD 的 ShareRowExclusiveLock 持有到验证结束;
        // 仅需自愈验证的既有外键也会在这里执行。
        execute_steps(connection, &plans, StepPhase::PostForeignKeys).await?;
    } else {
        // MySQL:保持既有顺序,预检先于全部 DDL。
        let violations = driver.preflight(connection, definitions, &plans).await?;
        if !violations.is_empty() {
            return Err(BaseError::DatabaseInitFailed(format_violations(
                &violations,
            )));
        }
        execute_steps(connection, &plans, StepPhase::AllNonForeignKey).await?;
        execute_steps(connection, &plans, StepPhase::ForeignKeys).await?;
    }

    // 报告按计划顺序生成,保证每个 step 恰好一条且顺序稳定(与执行阶段无关)。
    let (statements, deferred_statements) = plan_statements(&plans);
    Ok(SchemaSyncReport {
        tables: report_tables(definitions),
        changes: plans
            .iter()
            .flat_map(|plan| plan.steps.iter().map(|step| step.change.clone()))
            .collect(),
        statements,
        deferred_statements,
        bindings: binding_updates
            .iter()
            .map(|update| super::SchemaBindingChange {
                datasource: datasource.clone(),
                table: update.table.clone(),
                mode: update.mode,
                newly_bound: update.newly_bound,
            })
            .collect(),
    })
}

/// 汇总计划中的事务内与 deferred DDL 文本,供同步/dry-run 报告审计。
fn plan_statements(plans: &[super::model::TableSyncPlan]) -> (Vec<String>, Vec<String>) {
    let mut statements = Vec::new();
    let mut deferred_statements = Vec::new();
    for plan in plans {
        for step in &plan.steps {
            statements.extend(step.statements.iter().cloned());
            deferred_statements.extend(step.deferred_statements.iter().cloned());
        }
    }
    (statements, deferred_statements)
}

/// 计算本轮需要写入的所有权绑定。
///
/// - 首次登记时:本轮由框架建表 → `managed`;表已存在 → `adopted`。
/// - 已登记为 `adopted` 的表一旦被框架实际演进,即进入 `managed`。
fn binding_updates(
    driver: SchemaDriver,
    definitions: &[&TableDefinition],
    existing: &std::collections::BTreeMap<String, super::binding::BindingRecord>,
    changes: &[super::SchemaSyncChange],
) -> Result<Vec<super::binding::BindingUpdate>, BaseError> {
    let changed = changes
        .iter()
        .map(|change| change.table.as_str())
        .collect::<std::collections::BTreeSet<_>>();
    let now = super::binding::now_unix_seconds();
    let mut updates = Vec::new();
    for definition in definitions {
        let table = definition.name().to_string();
        let fingerprint = super::binding::table_fingerprint(driver, definition)?;
        let record = existing.get(&table);
        let (mode, newly_bound) = match record {
            Some(record) => {
                let mode = if record.mode == super::SchemaBindingMode::Adopted
                    && changed.contains(table.as_str())
                {
                    super::SchemaBindingMode::Managed
                } else {
                    record.mode
                };
                (mode, false)
            }
            // 首次登记:框架本轮建表或演进过的表直接归 managed;完全未动的
            // 存量表先记为 adopted,等待下一次实际演进或在报告中人工确认。
            None if changed.contains(table.as_str()) => (super::SchemaBindingMode::Managed, true),
            None => (super::SchemaBindingMode::Adopted, true),
        };
        let needs_write = record.map_or(true, |record| {
            record.mode != mode || record.fingerprint != fingerprint
        });
        if needs_write {
            updates.push(super::binding::BindingUpdate {
                table,
                mode,
                fingerprint,
                adopted_at: now,
                newly_bound,
            });
        }
    }
    Ok(updates)
}

async fn execute_steps(
    connection: &mut SchemaConnection<'_>,
    plans: &[super::model::TableSyncPlan],
    phase: StepPhase,
) -> Result<(), BaseError> {
    for plan in plans {
        for step in &plan.steps {
            let run_statements = phase.runs_statements(step);
            let run_deferred = phase.runs_deferred(step);
            if !run_statements && !run_deferred {
                continue;
            }
            if run_statements {
                for statement in &step.statements {
                    connection.execute(statement).await?;
                }
            }
            if run_deferred {
                for statement in &step.deferred_statements {
                    connection.execute(statement).await?;
                }
            }
            tracing::info!(
                table = %step.change.table,
                object = %step.change.object,
                kind = ?step.change.kind,
                phase = ?phase,
                "数据库 schema 已同步"
            );
        }
    }
    Ok(())
}