Module copy 

v7.22 (mailrs round-13 / T2) — shared COPY text-format helpers.

PG’s COPY is not an engine statement in SPG: both consumers lower it to per-row INSERTs. The wire path (spg-server pgwire) has done this since v7.15 for COPY … FROM stdin CopyData frames; the embed path (Database::execute_script / spg import) gained it in v7.22 because default-format pg_dump emits COPY blocks, and the zero-change import promise covers the default format, not just --column-inserts.

This module is the single home for the pure pieces: text-row decoding (tab-separated, \N nulls, backslash escapes) and INSERT synthesis. The wire path delegates here; wire-specific concerns (CopyData framing, SKIP/ON_ERROR/JSON options) stay in pgwire.

Structs

CopyFromFileSpec

v7.39 (round 249) — a parsed COPY <table> [(cols)] FROM '<path>'. The engine is no_std: the HOST reads path and hands the bytes to copy_buffer_inserts / Engine::copy_from_buffer.

CopyFromSpec

The head of an embed-path COPY … FROM stdin; statement.

CopyToFileSpec

v7.39 (round 252) — a parsed COPY … TO '<file>' (table or query form). The HOST renders via Engine::copy_to_buffer and writes path itself.

Functions

build_copy_insert

Build INSERT INTO <table> [(cols)] VALUES (…) from a decoded row. Numeric-looking and boolean cells go in bare so the engine sees typed literals; everything else is single-quoted with SQL escaping.

copy_buffer_inserts

v7.39 (round 249) — decode a whole COPY … FROM '<file>' buffer (the HOST read the file; the engine is no_std and performs no I/O) into the per-row INSERT statements both hosts drive. Text and CSV formats honour DELIMITER / NULL / HEADER / QUOTE; the text-format \. terminator ends the data early, as in PG.

csv_record_end

Byte length of the first complete CSV record in buf — including its terminating \n — or None if the buffer does not yet hold a full record (an unterminated quoted field, or no record-ending newline yet). Quote-aware: a newline inside a quoted field is part of the record. The quote character only opens a quoted field at the start of a field (buffer start or right after a delimiter), so delimiter is needed to track field boundaries. Scanning raw bytes is UTF-8-safe because the ASCII delimiter / quote / newline never collide with a multi-byte continuation byte (which is always ≥ 0x80).

decode_copy_csv_record

Decode one CSV data record (COPY … FROM stdin WITH (FORMAT csv)) into its fields. A field that starts with the quote character is a quoted field: its content runs to the matching close quote, a doubled quote ("") is one literal quote, and it is never NULL — a quoted empty string stays Some(""). An unquoted field runs to the next delimiter; if its text equals null_str it decodes to NULL, so with the default empty null string an empty unquoted field is NULL while "" is the empty string (PG’s exact CSV distinction). Embedded delimiters and newlines are only meaningful inside quotes.

decode_copy_text_row

Decode one COPY text-format data row: tab-separated cells, \N = NULL, C-style backslash escapes.

encode_copy_csv_cells

Encode one row’s cells as a CSV line (PG COPY … WITH (FORMAT csv)). A non-NULL field is quoted when it contains the delimiter, the quote character, a CR or LF, or when its text equals null_str — so an empty string under the default empty NULL, or any value that collides with the NULL marker, reads back as itself rather than as NULL. The quote character is doubled inside a quoted field. NULL is emitted as null_str, unquoted.

encode_copy_csv_cells_opts

v7.39 (round 247) — the full CSV cell encoder: escape is the character that precedes a quote (or itself) inside a quoted cell (PG’s default is the quote itself — doubling), and force_quote marks per-column forced quoting (NULLs stay bare, as PG’s FORCE_QUOTE does).

encode_copy_text_cells

Encode one row’s selected cells as a COPY text-format line — the inverse of decode_copy_text_row: tab-separated, \N for NULL, C-style backslash escapes for the control characters the decoder understands.

encode_copy_text_cells_opts

Encode one row’s cells as a COPY text-format line with a custom delimiter and NULL marker (PG COPY … WITH (FORMAT text, DELIMITER 'c', NULL 'str')). The named C-escapes (\t \n \r \b \f \v \\) are always applied; a delimiter character that is not itself one of those gets a literal \<char> escape so it round-trips.

parse_copy_from_file

Parse sql and return its parts when it is a COPY … FROM '<file>' statement — the host-side sniff for the file endpoint (any other statement, or a parse error, returns None and the caller executes normally).

parse_copy_from_stdin_head

Parse the head of a COPY <table> [(cols)] FROM stdin statement (text format). Returns None when the statement is not that shape — including COPY … TO stdout and file endpoints. A trailing WITH (…) options tail is accepted and ignored except that a non-text FORMAT makes this return None (the embed path only lowers the text format; callers surface a clear error).

parse_copy_to_file

Parse sql and return its parts when it is a COPY … TO '<file>' statement (any other statement, or a parse error, returns None).

validate_copy_option_direction

v7.39 (round 265) — the COPY option rules that depend on DIRECTION, probed against live PG18.4: