Skip to main content

yang_db/postgres/
init.rs

1//! PostgreSQL DDL/脚本执行逃生舱(P1-27)。
2//!
3//! 提供按 PostgreSQL 词法切分多语句脚本的
4//! [`split_sql_script`](识别单/双引号、`E'...'` 转义字符串、行注释、可嵌套块
5//! 注释与 `$$`/`$tag$` dollar-quote),以及整脚本单事务执行的
6//! [`Database::execute_script`]。函数体、`DO` 块和注释里的分号不会被误切。
7
8use crate::error::DbError;
9use crate::postgres::{Database, Transaction};
10
11/// 数据库迁移配置(PostgreSQL)
12#[derive(Debug, Clone)]
13pub struct MigrationConfig {
14    /// 迁移脚本目录
15    pub migrations_dir: String,
16    /// 是否自动运行迁移
17    pub auto_migrate: bool,
18}
19
20impl Default for MigrationConfig {
21    fn default() -> Self {
22        Self {
23            migrations_dir: "migrations".to_string(),
24            auto_migrate: false,
25        }
26    }
27}
28
29/// PostgreSQL 未加引号标识符的首字符规则(`[A-Za-z_]`)。
30fn is_ident_start(c: char) -> bool {
31    c.is_ascii_alphabetic() || c == '_'
32}
33
34/// PostgreSQL 未加引号标识符的后续字符规则(`[A-Za-z0-9_$]`)。
35fn is_ident_char(c: char) -> bool {
36    c.is_ascii_alphanumeric() || c == '_' || c == '$'
37}
38
39/// 在 `chars[start] == '$'` 处尝试解析 dollar-quote 标签。
40///
41/// 返回包含首尾 `$` 的标签(如 `$$`、`$body$`)。标签内容必须为空或符合
42/// 未加引号标识符规则(首字符非数字),因此 `$1` 这类位置参数不会被当成标签。
43fn parse_dollar_tag(chars: &[char], start: usize) -> Option<Vec<char>> {
44    let mut end = start + 1;
45    // 标签内容只能是 ASCII 字母/数字/下划线(不含 `$`,`$$` 的标签为空)。
46    while end < chars.len() && (chars[end].is_ascii_alphanumeric() || chars[end] == '_') {
47        end += 1;
48    }
49    // 标签内首字符不允许是数字(`$1$` 不是合法 dollar-quote 标签)。
50    if end > start + 1 && !is_ident_start(chars[start + 1]) {
51        return None;
52    }
53    if end < chars.len() && chars[end] == '$' {
54        Some(chars[start..=end].to_vec())
55    } else {
56        None
57    }
58}
59
60/// 按 PostgreSQL 词法把一个多语句脚本切分为独立语句。
61///
62/// 切分规则(P1-27):
63/// - 单引号字符串:`''` 为转义;`E'...'` 前缀下反斜杠转义下一个字符;
64/// - 双引号标识符:`""` 为转义;
65/// - 行注释 `-- ...` 到行尾;块注释 `/* ... */`,支持嵌套;
66/// - dollar-quote `$$...$$` / `$tag$...$tag$`:内部(含函数体分号)原样保留;
67/// - 其余位置的分号是语句分隔符。
68///
69/// 返回去掉首尾空白的语句(不含结尾分号、忽略空语句)。引号/注释/dollar-quote
70/// 未闭合时返回 [`DbError::InvalidArgument`]。
71pub fn split_sql_script(script: &str) -> Result<Vec<String>, DbError> {
72    let chars: Vec<char> = script.chars().collect();
73    let mut statements = Vec::new();
74    let mut current = String::new();
75    let mut i = 0usize;
76
77    while i < chars.len() {
78        match chars[i] {
79            // 单引号字符串(含 E'...' 反斜杠转义)。
80            '\'' => {
81                let escape_backslash = i > 0
82                    && matches!(chars[i - 1], 'E' | 'e')
83                    && (i < 2 || !is_ident_char(chars[i - 2]));
84                current.push('\'');
85                i += 1;
86                let mut closed = false;
87                while i < chars.len() {
88                    let c = chars[i];
89                    current.push(c);
90                    if escape_backslash && c == '\\' {
91                        i += 1;
92                        if i < chars.len() {
93                            current.push(chars[i]);
94                            i += 1;
95                        }
96                        continue;
97                    }
98                    if c == '\'' {
99                        if i + 1 < chars.len() && chars[i + 1] == '\'' {
100                            current.push('\'');
101                            i += 2;
102                            continue;
103                        }
104                        i += 1;
105                        closed = true;
106                        break;
107                    }
108                    i += 1;
109                }
110                if !closed {
111                    return Err(unterminated("单引号字符串", script, i));
112                }
113            }
114            // 双引号标识符。
115            '"' => {
116                current.push('"');
117                i += 1;
118                let mut closed = false;
119                while i < chars.len() {
120                    let c = chars[i];
121                    current.push(c);
122                    if c == '"' {
123                        if i + 1 < chars.len() && chars[i + 1] == '"' {
124                            current.push('"');
125                            i += 2;
126                            continue;
127                        }
128                        i += 1;
129                        closed = true;
130                        break;
131                    }
132                    i += 1;
133                }
134                if !closed {
135                    return Err(unterminated("双引号标识符", script, i));
136                }
137            }
138            // 行注释:复制到行尾(不含分隔作用)。
139            '-' if chars.get(i + 1) == Some(&'-') => {
140                current.push_str("--");
141                i += 2;
142                while i < chars.len() && chars[i] != '\n' {
143                    current.push(chars[i]);
144                    i += 1;
145                }
146            }
147            // 块注释:支持嵌套。
148            '/' if chars.get(i + 1) == Some(&'*') => {
149                current.push_str("/*");
150                i += 2;
151                let mut depth = 1usize;
152                while i < chars.len() && depth > 0 {
153                    if chars[i] == '/' && chars.get(i + 1) == Some(&'*') {
154                        depth += 1;
155                        current.push_str("/*");
156                        i += 2;
157                    } else if chars[i] == '*' && chars.get(i + 1) == Some(&'/') {
158                        depth -= 1;
159                        current.push_str("*/");
160                        i += 2;
161                    } else {
162                        current.push(chars[i]);
163                        i += 1;
164                    }
165                }
166                if depth > 0 {
167                    return Err(unterminated("块注释", script, i));
168                }
169            }
170            // dollar-quote:整体复制到匹配的结束标签。
171            '$' => match parse_dollar_tag(&chars, i) {
172                Some(tag) => {
173                    current.extend(tag.iter());
174                    i += tag.len();
175                    let mut closed = false;
176                    while i < chars.len() {
177                        if chars.len() - i >= tag.len() && chars[i..i + tag.len()] == tag[..] {
178                            current.extend(tag.iter());
179                            i += tag.len();
180                            closed = true;
181                            break;
182                        }
183                        current.push(chars[i]);
184                        i += 1;
185                    }
186                    if !closed {
187                        return Err(unterminated("dollar-quote", script, i));
188                    }
189                }
190                None => {
191                    current.push('$');
192                    i += 1;
193                }
194            },
195            // 语句分隔符。
196            ';' => {
197                let statement = current.trim();
198                if !statement.is_empty() {
199                    statements.push(statement.to_string());
200                }
201                current.clear();
202                i += 1;
203            }
204            c => {
205                current.push(c);
206                i += 1;
207            }
208        }
209    }
210
211    let statement = current.trim();
212    if !statement.is_empty() {
213        statements.push(statement.to_string());
214    }
215    Ok(statements)
216}
217
218/// 构造未闭合词法单元的错误(附带字符位置便于定位)。
219fn unterminated(kind: &str, script: &str, position: usize) -> DbError {
220    let line = script.chars().take(position).filter(|c| *c == '\n').count() + 1;
221    DbError::InvalidArgument(format!(
222        "SQL 脚本中存在未闭合的{kind}(第 {line} 行,字符位置 {position})"
223    ))
224}
225
226/// 在给定事务内顺序执行已切分的语句(不开启新事务)。
227pub(crate) async fn execute_statements(
228    transaction: &mut Transaction,
229    statements: &[String],
230) -> Result<(), DbError> {
231    for statement in statements {
232        let conn = transaction
233            .executor()
234            .ok_or_else(|| DbError::TransactionError("事务已提交或回滚".to_string()))?;
235        sqlx::query(statement).execute(conn).await?;
236    }
237    Ok(())
238}
239
240impl Database {
241    /// 在当前连接池上执行一个多语句脚本(整脚本单事务)。
242    ///
243    /// 脚本按 [`split_sql_script`] 切分后在同一事务内依次执行;任一条失败则整个
244    /// 脚本回滚(DDL 在 PostgreSQL 中可事务化,因此建表失败不会留下半成品)。
245    ///
246    /// 注意:`CREATE INDEX CONCURRENTLY`、`VACUUM` 等不能在事务块内执行的语句会
247    /// 被服务端拒绝;这类语句请单独执行。
248    ///
249    /// 返回执行的语句条数(空脚本返回 0,且不开事务)。
250    pub async fn execute_script(&self, script: &str) -> Result<usize, DbError> {
251        let statements = split_sql_script(script)?;
252        if statements.is_empty() {
253            return Ok(0);
254        }
255        let mut transaction = self.transaction().await?;
256        execute_statements(&mut transaction, &statements).await?;
257        transaction.commit().await?;
258        Ok(statements.len())
259    }
260}
261
262#[cfg(test)]
263#[allow(clippy::unwrap_used)]
264mod tests {
265    use super::*;
266
267    fn split(script: &str) -> Vec<String> {
268        split_sql_script(script).unwrap()
269    }
270
271    #[test]
272    fn splits_multiple_statements_and_trims() {
273        let statements = split("  SELECT 1; SELECT 2 ;;  SELECT 3  ");
274        assert_eq!(statements, vec!["SELECT 1", "SELECT 2", "SELECT 3"]);
275        assert!(split("   ; ;  ").is_empty());
276        assert!(split("").is_empty());
277    }
278
279    #[test]
280    fn keeps_semicolons_inside_dollar_quotes() {
281        let script = "
282            CREATE FUNCTION add_one(x int) RETURNS int AS $$
283            BEGIN
284                RETURN x + 1;
285            END;
286            $$ LANGUAGE plpgsql;
287            SELECT add_one(1);
288        ";
289        let statements = split(script);
290        assert_eq!(statements.len(), 2);
291        assert!(statements[0].contains("RETURN x + 1;"));
292        assert!(statements[0].ends_with("LANGUAGE plpgsql"));
293        assert_eq!(statements[1], "SELECT add_one(1)");
294    }
295
296    #[test]
297    fn keeps_semicolons_inside_tagged_dollar_quotes() {
298        let script = "DO $body$ BEGIN PERFORM 1; PERFORM 2; END $body$; SELECT 1";
299        let statements = split(script);
300        assert_eq!(statements.len(), 2);
301        assert!(statements[0].starts_with("DO $body$"));
302        assert!(statements[0].ends_with("END $body$"));
303    }
304
305    #[test]
306    fn keeps_semicolons_inside_quotes_and_comments() {
307        assert_eq!(
308            split("SELECT ';' AS a, 'it''s; ok' AS b; SELECT 2"),
309            vec!["SELECT ';' AS a, 'it''s; ok' AS b", "SELECT 2"]
310        );
311        assert_eq!(
312            split("SELECT \"we;ird\" FROM t; SELECT 2"),
313            vec!["SELECT \"we;ird\" FROM t", "SELECT 2"]
314        );
315        assert_eq!(
316            split("SELECT 1 -- a; b\n; SELECT 2"),
317            vec!["SELECT 1 -- a; b", "SELECT 2"]
318        );
319        assert_eq!(
320            split("SELECT /* a; b */ 1; SELECT 2"),
321            vec!["SELECT /* a; b */ 1", "SELECT 2"]
322        );
323        // 嵌套块注释。
324        assert_eq!(
325            split("SELECT /* outer /* inner; */ still; */ 1; SELECT 2").len(),
326            2
327        );
328    }
329
330    #[test]
331    fn handles_escape_strings() {
332        // E'...' 中的 \' 不结束字符串。
333        assert_eq!(
334            split("SELECT E'it\\'s; ok' AS x; SELECT 2"),
335            vec!["SELECT E'it\\'s; ok' AS x", "SELECT 2"]
336        );
337    }
338
339    #[test]
340    fn does_not_treat_positional_params_as_dollar_quotes() {
341        assert_eq!(
342            split("SELECT $1, $2 FROM t WHERE x = $3; SELECT 2"),
343            vec!["SELECT $1, $2 FROM t WHERE x = $3", "SELECT 2"]
344        );
345        // `$` 出现在标识符中间(`a$b`)不是 dollar-quote。
346        assert_eq!(
347            split("SELECT a$b FROM t; SELECT 2"),
348            vec!["SELECT a$b FROM t", "SELECT 2"]
349        );
350    }
351
352    #[test]
353    fn rejects_unterminated_lexical_units() {
354        for script in [
355            "SELECT 'unterminated",
356            "SELECT \"unterminated",
357            "SELECT 1 /* unterminated",
358            "SELECT $$unterminated",
359            "SELECT $tag$ unterminated",
360        ] {
361            assert!(
362                matches!(split_sql_script(script), Err(DbError::InvalidArgument(_))),
363                "应拒绝未闭合脚本: {script:?}"
364            );
365        }
366    }
367}