Skip to main content

yang_base/database/schema_sync/
binding.rs

1//! `_yang_schema_binding` 所有权登记。
2//!
3//! 同步器用该表区分框架创建的托管表(`managed`)与接管存量表(`adopted`),
4//! 并记录最近一次同步后的结构指纹。登记只做附加写入,绝不删除表或列。
5
6use super::driver::{SchemaConnection, SchemaDriver};
7use crate::datasource::DatasourceId;
8use crate::error::BaseError;
9use crate::table::TableDefinition;
10use sqlx::FromRow;
11use std::collections::BTreeMap;
12use std::time::{SystemTime, UNIX_EPOCH};
13
14/// 框架所有权登记表名。
15pub(crate) const BINDING_TABLE: &str = "_yang_schema_binding";
16
17#[cfg(feature = "mysql")]
18const BINDING_TABLE_DDL_MYSQL: &str = "CREATE TABLE IF NOT EXISTS `_yang_schema_binding` (\
19 `datasource` VARCHAR(32) NOT NULL, \
20 `table_name` VARCHAR(128) NOT NULL, \
21 `mode` VARCHAR(16) NOT NULL, \
22 `fingerprint` VARCHAR(64) NOT NULL, \
23 `adopted_at` BIGINT NOT NULL, \
24 PRIMARY KEY (`datasource`, `table_name`)\
25) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4";
26
27#[cfg(feature = "postgres")]
28const BINDING_TABLE_DDL_POSTGRES: &str = "CREATE TABLE IF NOT EXISTS \"_yang_schema_binding\" (\
29 \"datasource\" VARCHAR(32) NOT NULL, \
30 \"table_name\" VARCHAR(128) NOT NULL, \
31 \"mode\" VARCHAR(16) NOT NULL, \
32 \"fingerprint\" VARCHAR(64) NOT NULL, \
33 \"adopted_at\" BIGINT NOT NULL, \
34 PRIMARY KEY (\"datasource\", \"table_name\")\
35)";
36
37/// 表的所有权模式。
38#[derive(Debug, Clone, Copy, PartialEq, Eq)]
39#[non_exhaustive]
40pub enum SchemaBindingMode {
41    /// 接管存量表:只允许附加变更,首次同步后保留该模式,直到框架实际演进该表。
42    Adopted,
43    /// 框架托管:声明式定义是唯一事实源。
44    Managed,
45}
46
47impl SchemaBindingMode {
48    pub(crate) fn as_str(self) -> &'static str {
49        match self {
50            Self::Adopted => "adopted",
51            Self::Managed => "managed",
52        }
53    }
54
55    fn parse(value: &str) -> Result<Self, BaseError> {
56        match value {
57            "adopted" => Ok(Self::Adopted),
58            "managed" => Ok(Self::Managed),
59            other => Err(BaseError::DatabaseInitFailed(format!(
60                "未知 schema binding 模式: {other}"
61            ))),
62        }
63    }
64}
65
66/// 已登记的表绑定。
67#[derive(Debug, Clone)]
68pub(crate) struct BindingRecord {
69    pub(crate) mode: SchemaBindingMode,
70    pub(crate) fingerprint: String,
71}
72
73/// 一次同步后需要写入的绑定。
74#[derive(Debug, Clone)]
75pub(crate) struct BindingUpdate {
76    pub(crate) table: String,
77    pub(crate) mode: SchemaBindingMode,
78    pub(crate) fingerprint: String,
79    pub(crate) adopted_at: i64,
80    pub(crate) newly_bound: bool,
81}
82
83#[derive(FromRow)]
84struct BindingRow {
85    table_name: String,
86    mode: String,
87    fingerprint: String,
88}
89
90/// 幂等创建所有权登记表。
91pub(crate) async fn ensure_binding_table(
92    driver: SchemaDriver,
93    connection: &mut SchemaConnection<'_>,
94) -> Result<(), BaseError> {
95    connection
96        .execute(match driver {
97            #[cfg(feature = "mysql")]
98            SchemaDriver::MySql => BINDING_TABLE_DDL_MYSQL,
99            #[cfg(feature = "postgres")]
100            SchemaDriver::PostgreSql => BINDING_TABLE_DDL_POSTGRES,
101        })
102        .await
103}
104
105/// 读取某个逻辑数据源已登记的表绑定。
106pub(crate) async fn load_bindings(
107    connection: &mut SchemaConnection<'_>,
108    datasource: &DatasourceId,
109) -> Result<BTreeMap<String, BindingRecord>, BaseError> {
110    let rows = match connection {
111        #[cfg(feature = "mysql")]
112        SchemaConnection::MySql(connection) => {
113            sqlx::query_as::<_, BindingRow>(
114                "SELECT CAST(table_name AS CHAR) AS table_name, \
115                        CAST(mode AS CHAR) AS mode, \
116                        CAST(fingerprint AS CHAR) AS fingerprint \
117                 FROM `_yang_schema_binding` WHERE datasource = ?",
118            )
119            .bind(datasource.as_str())
120            .fetch_all(&mut **connection)
121            .await
122        }
123        #[cfg(feature = "postgres")]
124        SchemaConnection::PostgreSql(connection) => {
125            sqlx::query_as::<_, BindingRow>(
126                "SELECT table_name, mode, fingerprint \
127                 FROM \"_yang_schema_binding\" WHERE datasource = $1",
128            )
129            .bind(datasource.as_str())
130            .fetch_all(&mut **connection)
131            .await
132        }
133    }
134    .map_err(|error| BaseError::DatabaseQueryFailed(error.into()))?;
135    let mut bindings = BTreeMap::new();
136    for row in rows {
137        bindings.insert(
138            row.table_name,
139            BindingRecord {
140                mode: SchemaBindingMode::parse(&row.mode)?,
141                fingerprint: row.fingerprint,
142            },
143        );
144    }
145    Ok(bindings)
146}
147
148/// 写入/更新表绑定。
149pub(crate) async fn upsert_bindings(
150    connection: &mut SchemaConnection<'_>,
151    datasource: &DatasourceId,
152    updates: &[BindingUpdate],
153) -> Result<(), BaseError> {
154    for update in updates {
155        let result = match connection {
156            #[cfg(feature = "mysql")]
157            SchemaConnection::MySql(connection) => sqlx::query(
158                "INSERT INTO `_yang_schema_binding` \
159                     (datasource, table_name, mode, fingerprint, adopted_at) \
160                     VALUES (?, ?, ?, ?, ?) \
161                     ON DUPLICATE KEY UPDATE mode = VALUES(mode), \
162                     fingerprint = VALUES(fingerprint)",
163            )
164            .bind(datasource.as_str())
165            .bind(&update.table)
166            .bind(update.mode.as_str())
167            .bind(&update.fingerprint)
168            .bind(update.adopted_at)
169            .execute(&mut **connection)
170            .await
171            .map(|_| ()),
172            #[cfg(feature = "postgres")]
173            SchemaConnection::PostgreSql(connection) => sqlx::query(
174                "INSERT INTO \"_yang_schema_binding\" \
175                     (datasource, table_name, mode, fingerprint, adopted_at) \
176                     VALUES ($1, $2, $3, $4, $5) \
177                     ON CONFLICT (datasource, table_name) DO UPDATE SET \
178                     mode = EXCLUDED.mode, fingerprint = EXCLUDED.fingerprint",
179            )
180            .bind(datasource.as_str())
181            .bind(&update.table)
182            .bind(update.mode.as_str())
183            .bind(&update.fingerprint)
184            .bind(update.adopted_at)
185            .execute(&mut **connection)
186            .await
187            .map(|_| ()),
188        };
189        result.map_err(|error| BaseError::DatabaseExecuteFailed(error.into()))?;
190    }
191    Ok(())
192}
193
194/// 计算表定义的结构指纹(FNV-1a 64 位十六进制)。
195pub(crate) fn table_fingerprint(
196    driver: SchemaDriver,
197    definition: &TableDefinition,
198) -> Result<String, BaseError> {
199    let config = definition.shared_config();
200    let signature = driver.dialect().table_signature(config.as_ref())?;
201    Ok(format!("{:016x}", fnv1a_64(signature.as_bytes())))
202}
203
204pub(crate) fn now_unix_seconds() -> i64 {
205    SystemTime::now()
206        .duration_since(UNIX_EPOCH)
207        .map_or(0, |duration| duration.as_secs() as i64)
208}
209
210fn fnv1a_64(bytes: &[u8]) -> u64 {
211    let mut hash: u64 = 0xcbf29ce484222325;
212    for byte in bytes {
213        hash ^= u64::from(*byte);
214        hash = hash.wrapping_mul(0x100000001b3);
215    }
216    hash
217}