Skip to main content

yang_db/postgres/
copy.rs

1//! PostgreSQL COPY 协议封装(`COPY ... FROM STDIN` / `COPY ... TO STDOUT`)。
2//!
3//! 设计要点:
4//! - COPY 在独立连接上执行:入口从连接池借出一条连接,正常结束后归还;
5//!   任何协议状态不确定的失败都会 `detach` 该连接(关闭而非放回池),
6//!   避免污染池内连接的协议状态。
7//! - 导入入口 [`Database::copy_from_csv`] 接受行迭代器,按块发送 CSV 数据;
8//!   导出入口 [`Database::copy_to_csv`] 把输出一次性收集为字节。
9//! - 本模块不做 CSV 转义:行内容按调用方提供的字节原样发送。
10//! - `COPY` 是单条语句:中途失败时服务端会整体丢弃本批数据。
11
12use crate::error::DbError;
13use crate::postgres::Database;
14use sqlx::postgres::PgConnection;
15use std::future::poll_fn;
16
17/// 发送缓冲上限:达到后立即向服务端发送一块 COPY 数据,避免逐行一条协议消息。
18const COPY_SEND_BUFFER_BYTES: usize = 64 * 1024;
19
20/// 校验 COPY 语句非空并去掉首尾空白。
21///
22/// 语句形状(`FROM STDIN` / `TO STDOUT`)由 sqlx 与服务端校验,这里只拦住空语句,
23/// 避免把明显的调用方错误变成协议层错误。
24fn validate_copy_sql(sql: &str) -> Result<&str, DbError> {
25    let trimmed = sql.trim();
26    if trimmed.is_empty() {
27        return Err(DbError::InvalidArgument(
28            "PostgreSQL COPY 语句不能为空".to_string(),
29        ));
30    }
31    Ok(trimmed)
32}
33
34/// 把一行 CSV 追加到发送缓冲;行内容缺少换行时补一个 `\n`。
35///
36/// 项内容按字节原样保留(引号字段内的换行不受影响),本函数只负责行尾换行。
37fn append_csv_row(buffer: &mut Vec<u8>, row: &[u8]) {
38    buffer.extend_from_slice(row);
39    if !row.ends_with(b"\n") {
40        buffer.push(b'\n');
41    }
42}
43
44impl Database {
45    /// 通过 `COPY ... FROM STDIN` 批量导入 CSV 行。
46    ///
47    /// `sql` 必须是形如
48    /// `COPY <表> [(列...)] FROM STDIN WITH (FORMAT csv, ...)` 的语句,其余
49    /// 格式选项由 SQL 文本决定。`rows` 的每一项是一条完整 CSV 记录:末尾缺少
50    /// `\n` 时自动补一个;字段内的 CSV 转义(引号、逗号、换行)由调用方负责,
51    /// 本方法按字节原样发送,不做转义。
52    ///
53    /// 返回服务端确认的写入行数。失败时若连接协议状态已无法确认,该连接会被
54    /// 关闭而不是放回连接池。
55    pub async fn copy_from_csv<I, R>(&self, sql: &str, rows: I) -> Result<u64, DbError>
56    where
57        I: IntoIterator<Item = R>,
58        R: AsRef<[u8]>,
59    {
60        let sql = validate_copy_sql(sql)?;
61        let mut conn = self.acquire().await?;
62        match copy_in_rows(&mut conn, sql, rows).await {
63            Ok(affected) => Ok(affected),
64            Err(error) => {
65                // 协议状态未知:关闭连接,不把脏连接放回池。
66                drop(conn.detach());
67                Err(error)
68            }
69        }
70    }
71
72    /// 通过 `COPY ... TO STDOUT` 导出 CSV 数据。
73    ///
74    /// `sql` 必须是形如
75    /// `COPY (SELECT ...) TO STDOUT WITH (FORMAT csv, ...)` 的语句。返回服务端
76    /// 输出的完整原始字节(CSV 文本)。
77    ///
78    /// 输出会一次性收集到内存;导出超大结果集时请改用
79    /// [`stream_query`](Self::stream_query) 分页读取。
80    ///
81    /// 失败时若连接协议状态已无法确认,该连接会被关闭而不是放回连接池。
82    pub async fn copy_to_csv(&self, sql: &str) -> Result<Vec<u8>, DbError> {
83        let sql = validate_copy_sql(sql)?;
84        let mut conn = self.acquire().await?;
85        match copy_out_bytes(&mut conn, sql).await {
86            Ok(bytes) => Ok(bytes),
87            Err(error) => {
88                // 未读完的 COPY OUT 会残留服务端待发送数据:关闭连接。
89                drop(conn.detach());
90                Err(error)
91            }
92        }
93    }
94}
95
96/// 在指定连接上执行 `COPY ... FROM STDIN` 并逐块发送行数据。
97async fn copy_in_rows<I, R>(conn: &mut PgConnection, sql: &str, rows: I) -> Result<u64, DbError>
98where
99    I: IntoIterator<Item = R>,
100    R: AsRef<[u8]>,
101{
102    let mut copy = conn.copy_in_raw(sql).await?;
103    let mut buffer = Vec::with_capacity(COPY_SEND_BUFFER_BYTES);
104    for row in rows {
105        let row = row.as_ref();
106        if buffer.len() + row.len() + 1 > COPY_SEND_BUFFER_BYTES && !buffer.is_empty() {
107            copy.send(buffer.as_slice()).await?;
108            buffer.clear();
109        }
110        append_csv_row(&mut buffer, row);
111    }
112    if !buffer.is_empty() {
113        copy.send(buffer.as_slice()).await?;
114    }
115    Ok(copy.finish().await?)
116}
117
118/// 在指定连接上执行 `COPY ... TO STDOUT` 并把全部数据块收集为字节。
119async fn copy_out_bytes(conn: &mut PgConnection, sql: &str) -> Result<Vec<u8>, DbError> {
120    let mut stream = conn.copy_out_raw(sql).await?;
121    let mut bytes = Vec::new();
122    while let Some(chunk) = poll_fn(|cx| stream.as_mut().poll_next(cx)).await {
123        bytes.extend_from_slice(&chunk?);
124    }
125    Ok(bytes)
126}
127
128#[cfg(test)]
129#[allow(clippy::unwrap_used)]
130mod tests {
131    use super::*;
132
133    #[test]
134    fn validate_copy_sql_rejects_blank_statements() {
135        for blank in ["", "   ", "\n\t"] {
136            assert!(
137                matches!(validate_copy_sql(blank), Err(DbError::InvalidArgument(_))),
138                "空语句应被拒绝: {blank:?}"
139            );
140        }
141        assert_eq!(
142            validate_copy_sql("  COPY t FROM STDIN  ").unwrap(),
143            "COPY t FROM STDIN"
144        );
145    }
146
147    #[test]
148    fn append_csv_row_adds_missing_newline_and_preserves_existing() {
149        let mut buffer = Vec::new();
150        append_csv_row(&mut buffer, b"1,alice");
151        assert_eq!(buffer, b"1,alice\n");
152
153        // 已带行尾换行时不重复追加。
154        append_csv_row(&mut buffer, b"2,bob\n");
155        assert_eq!(buffer, b"1,alice\n2,bob\n");
156
157        // 空记录写入一个空行。
158        append_csv_row(&mut buffer, b"");
159        assert_eq!(buffer, b"1,alice\n2,bob\n\n");
160
161        // 引号字段内的换行按原样保留。
162        let mut quoted = Vec::new();
163        append_csv_row(&mut quoted, b"\"a\nb\",c");
164        assert_eq!(quoted, b"\"a\nb\",c\n");
165    }
166}