Skip to main content

uqa_sql/copy/
output.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Incremental COPY output with admitted value formatting and bounded write/cancellation intervals.
8
9use super::{CopyFormat, CopyHeader, CopyOptions};
10use crate::{expr::EngineHook, ColumnType, SQLError, SQLResult};
11use std::io::{ErrorKind, Write};
12use uqa_core::{
13    memory::{Produced, ProductionControl},
14    Value,
15};
16
17const WRITE_BYTES: usize = 8192;
18
19/// Text/CSV output over an existing sink. The encoder retains no row or encoded-output buffer; only the current value's formatted text can own scratch memory.
20pub struct CopyEncoder<'a, 'c, W: Write + ?Sized> {
21    options: &'a CopyOptions,
22    output: &'a mut W,
23    engine: Option<&'a dyn EngineHook>,
24    control: ProductionControl<'c>,
25}
26
27impl<'a, 'c, W: Write + ?Sized> CopyEncoder<'a, 'c, W> {
28    pub fn new(
29        options: &'a CopyOptions,
30        output: &'a mut W,
31        engine: Option<&'a dyn EngineHook>,
32        control: ProductionControl<'c>,
33    ) -> Result<Self, SQLError> {
34        if options.format == CopyFormat::Binary {
35            return Err(SQLError::Unsupported(
36                "binary COPY format is not implemented".into(),
37            ));
38        }
39        Ok(Self {
40            options,
41            output,
42            engine,
43            control,
44        })
45    }
46
47    pub fn write_header(&mut self, columns: &[String]) -> Result<(), SQLError> {
48        self.check()?;
49        if self.options.header == CopyHeader::False {
50            return Ok(());
51        }
52        for (index, column) in columns.iter().enumerate() {
53            if index != 0 {
54                self.write(&[self.options.delimiter])?;
55            }
56            self.field(Some(column), columns.len() == 1)?;
57        }
58        self.write(b"\n")
59    }
60
61    /// Write one positional row, preserving separately valued duplicate column names and a missing value's SQL NULL semantics.
62    pub fn write_row<'v>(
63        &mut self,
64        fields: impl IntoIterator<Item = (Option<&'v Value>, Option<&'v ColumnType>)>,
65    ) -> Result<(), SQLError> {
66        self.check()?;
67        let mut fields = fields.into_iter().peekable();
68        let mut first = true;
69        while let Some((value, ty)) = fields.next() {
70            if !first {
71                self.write(&[self.options.delimiter])?;
72            }
73            let text = value
74                .map(|value| value_text(value, ty, self.engine, &self.control))
75                .transpose()?
76                .flatten();
77            self.field(
78                text.as_ref().map(FieldText::as_str),
79                first && fields.peek().is_none(),
80            )?;
81            first = false;
82        }
83        self.write(b"\n")
84    }
85
86    /// Finish the sink while the producing statement can still fail and roll back.
87    pub fn finish(self) -> Result<(), SQLError> {
88        loop {
89            self.check()?;
90            match self.output.flush() {
91                Ok(()) => return self.check(),
92                Err(error) if error.kind() == ErrorKind::Interrupted => {}
93                Err(error) => return Err(write_error(error)),
94            }
95        }
96    }
97
98    fn check(&self) -> Result<(), SQLError> {
99        self.control.check()?;
100        crate::expr::check_statement_cancellation()?;
101        Ok(())
102    }
103
104    fn write(&mut self, mut bytes: &[u8]) -> Result<(), SQLError> {
105        while !bytes.is_empty() {
106            self.check()?;
107            let chunk = &bytes[..bytes.len().min(WRITE_BYTES)];
108            match self.output.write(chunk) {
109                Ok(0) => return Err(write_error(std::io::Error::from(ErrorKind::WriteZero))),
110                Ok(count) => bytes = &bytes[count..],
111                Err(error) if error.kind() == ErrorKind::Interrupted => {}
112                Err(error) => return Err(write_error(error)),
113            }
114        }
115        Ok(())
116    }
117
118    fn field(&mut self, field: Option<&str>, single_column: bool) -> Result<(), SQLError> {
119        let Some(field) = field else {
120            return self.write(self.options.null.as_bytes());
121        };
122        match self.options.format {
123            CopyFormat::Text => self.text_field(field),
124            CopyFormat::Csv => self.csv_field(field, single_column),
125            CopyFormat::Binary => unreachable!("constructor rejects binary COPY"),
126        }
127    }
128
129    fn text_field(&mut self, field: &str) -> Result<(), SQLError> {
130        let bytes = field.as_bytes();
131        let mut start = 0;
132        for (index, byte) in bytes.iter().copied().enumerate() {
133            if index % WRITE_BYTES == 0 {
134                self.check()?;
135            }
136            let escaped = match byte {
137                0x08 => Some(b'b'),
138                0x0c => Some(b'f'),
139                b'\n' => Some(b'n'),
140                b'\r' => Some(b'r'),
141                b'\t' => Some(b't'),
142                0x0b => Some(b'v'),
143                b'\\' => Some(b'\\'),
144                other if other == self.options.delimiter => Some(other),
145                _ => None,
146            };
147            if let Some(escaped) = escaped {
148                self.write(&bytes[start..index])?;
149                self.write(&[b'\\', escaped])?;
150                start = index + 1;
151            }
152        }
153        self.write(&bytes[start..])
154    }
155
156    fn csv_field(&mut self, field: &str, single_column: bool) -> Result<(), SQLError> {
157        let mut needs_quotes =
158            (field.is_empty() && self.options.null.is_empty()) || (single_column && field == r"\.");
159        if field.len() == self.options.null.len() {
160            let mut same = true;
161            for (left, right) in field
162                .as_bytes()
163                .chunks(WRITE_BYTES)
164                .zip(self.options.null.as_bytes().chunks(WRITE_BYTES))
165            {
166                self.check()?;
167                if left != right {
168                    same = false;
169                    break;
170                }
171            }
172            needs_quotes |= same;
173        }
174        for chunk in field.as_bytes().chunks(WRITE_BYTES) {
175            self.check()?;
176            if needs_quotes {
177                break;
178            }
179            needs_quotes = chunk.iter().any(|byte| {
180                matches!(byte, b'\n' | b'\r')
181                    || *byte == self.options.delimiter
182                    || *byte == self.options.quote
183            });
184        }
185        if !needs_quotes {
186            return self.write(field.as_bytes());
187        }
188        self.write(&[self.options.quote])?;
189        let bytes = field.as_bytes();
190        let mut start = 0;
191        for (index, byte) in bytes.iter().copied().enumerate() {
192            if index % WRITE_BYTES == 0 {
193                self.check()?;
194            }
195            if byte == self.options.quote || byte == self.options.escape {
196                self.write(&bytes[start..index])?;
197                self.write(&[self.options.escape, byte])?;
198                start = index + 1;
199            }
200        }
201        self.write(&bytes[start..])?;
202        self.write(&[self.options.quote])
203    }
204}
205
206enum FieldText<'v> {
207    Borrowed(&'v str),
208    Owned(Produced<String>),
209}
210
211impl FieldText<'_> {
212    fn as_str(&self) -> &str {
213        match self {
214            Self::Borrowed(text) => text,
215            Self::Owned(text) => text,
216        }
217    }
218}
219
220fn value_text<'v>(
221    value: &'v Value,
222    ty: Option<&ColumnType>,
223    engine: Option<&dyn EngineHook>,
224    control: &ProductionControl<'_>,
225) -> Result<Option<FieldText<'v>>, SQLError> {
226    control.check()?;
227    if matches!(value, Value::Null) {
228        return Ok(None);
229    }
230    let _interval_style = if crate::expr::interval_style::output_can_contain_interval(value) {
231        crate::expr::interval_style::live_scope(engine, control)?
232    } else {
233        None
234    };
235    Ok(Some(match value {
236        Value::Str(text) | Value::Json(text) | Value::JsonB(text) | Value::FixedChar(text) => {
237            FieldText::Borrowed(text)
238        }
239        Value::Bool(value) => FieldText::Borrowed(if *value { "t" } else { "f" }),
240        Value::Float(value) if value.is_nan() => FieldText::Borrowed("NaN"),
241        Value::Float(value) if *value == f64::INFINITY => FieldText::Borrowed("Infinity"),
242        Value::Float(value) if *value == f64::NEG_INFINITY => FieldText::Borrowed("-Infinity"),
243        other => {
244            let text = if let Some(ty) = ty {
245                let catalog = engine.map(crate::expr::EngineValueCatalog);
246                crate::result::format_postgres_text_with_catalog_and_control(
247                    other,
248                    ty,
249                    catalog
250                        .as_ref()
251                        .map(|catalog| catalog as &dyn crate::expr::SQLValueCatalog),
252                    control,
253                )?
254            } else {
255                crate::expr::value_to_string_with_control(other, control)?
256            };
257            FieldText::Owned(text)
258        }
259    }))
260}
261
262fn write_error(error: std::io::Error) -> SQLError {
263    SQLError::Routine {
264        sqlstate: "58030".into(),
265        message: format!("write COPY TO stream: {error}"),
266    }
267}
268
269/// Write a materialized SQL result without allocating a second, encoded result. Streaming producers use [`CopyEncoder`] directly with one row at a time.
270pub fn write_copy_result<W: Write + ?Sized>(
271    result: &SQLResult,
272    options: &CopyOptions,
273    output: &mut W,
274    engine: Option<&dyn EngineHook>,
275    control: &ProductionControl<'_>,
276) -> Result<(), SQLError> {
277    let mut encoder = CopyEncoder::new(options, output, engine, *control)?;
278    encoder.write_header(&result.columns)?;
279    for row in 0..result.rows.len() {
280        encoder.write_row(result.columns.iter().enumerate().map(|(column, _)| {
281            (
282                result.value_at(row, column),
283                result.column_types.get(column).and_then(Option::as_ref),
284            )
285        }))?;
286    }
287    encoder.finish()
288}
289
290#[cfg(test)]
291mod tests;