feat: add nullstr option

The string representing the null can now be specified.

```sql
SELECT csv_agg(x, csv_options(nullstr:='<NULL>')) AS body
FROM   projects x;

              body
--------------------------------
 id,name,client_id             +
 1,Death Star OS,1             +
 2,Windows 95 Rebooted,1       +
 3,"Project ""Comma,Please""",2+
 4,"Escape """"Plan""""",2     +
 <NULL>,NULL & Void,<NULL>
(1 row)
```

Author: steve-chavez

.github/workflows/ci.yaml

@@ -37,7 +37,7 @@ jobs:
   loadtest:
     strategy:
       matrix:
-        kind: ['csv_agg', 'csv_agg_delim', 'csv_agg_delim_bom', 'postgrest']
+        kind: ['csv_agg', 'csv_agg_delim', 'csv_agg_delim_bom_nullstr', 'postgrest']
     name: Loadtest
     runs-on: ubuntu-24.04
     steps:

README.md

@@ -127,6 +127,25 @@ select csv_agg(x, csv_options(header := false)) from projects x;
 (1 row)
 ```
 
+### Null string
+
+NULL values are represented by an empty string by default. This can be changed with the `nullstr` option.
+
+```sql
+SELECT csv_agg(x, csv_options(nullstr:='<NULL>')) AS body
+FROM   projects x;
+
+              body
+--------------------------------
+ id,name,client_id             +
+ 1,Death Star OS,1             +
+ 2,Windows 95 Rebooted,1       +
+ 3,"Project ""Comma,Please""",2+
+ 4,"Escape """"Plan""""",2     +
+ <NULL>,NULL & Void,<NULL>
+(1 row)
+```
+
 ## Limitations
 
 - For large bulk exports and imports, `COPY ... CSV` should still be preferred as its faster due to streaming support.

bench/csv_agg_delim_bom_nullstr.sql

@@ -0,0 +1,5 @@
+\set lim random(1000, 2000)
+
+select csv_agg(t, csv_options(delimiter:=',', bom:=true, nullstr='<NULL>')) from (
+  select * from student_emotion_assessments limit :lim
+) as t;

sql/pg_csv.sql

@@ -1,15 +1,17 @@
-create type csv_options as (
-  delimiter "char"
+create type csv_options as
+( delimiter "char"
 , bom       bool
 , header    bool
+, nullstr   text
 );
 
-create or replace function csv_options(
-  delimiter "char" default NULL,
-  bom       bool default NULL,
-  header    bool default NULL
+create or replace function csv_options
+( delimiter "char" default NULL
+, bom       bool default NULL
+, header    bool default NULL
+, nullstr   text default NULL
 ) returns csv_options as $$
-  select row(delimiter, bom, header)::csv_options;
+  select row(delimiter, bom, header, nullstr)::csv_options;
 $$ language sql;
 
 create function csv_agg_transfn(internal, anyelement)

src/aggs.c

@@ -27,6 +27,7 @@ void parse_csv_options(HeapTupleHeader opts_hdr, CsvOptions *csv_opts) {
   csv_opts->delimiter = ',';
   csv_opts->bom       = false;
   csv_opts->header    = true;
+  csv_opts->nullstr   = NULL;
 
   if (opts_hdr == NULL) return;
 
@@ -56,6 +57,10 @@ void parse_csv_options(HeapTupleHeader opts_hdr, CsvOptions *csv_opts) {
     csv_opts->header = DatumGetBool(values[2]);
   }
 
+  if (!nulls[3]) {
+    csv_opts->nullstr = DatumGetTextPP(values[3]);
+  }
+
   ReleaseTupleDesc(desc);
 }
 

src/aggs.h

@@ -3,18 +3,21 @@
 
 // mirrors the SQL csv_options type
 typedef struct {
-  char delimiter;
-  bool bom;
-  bool header;
+  char  delimiter;
+  bool  bom;
+  bool  header;
+  text *nullstr;
 } CsvOptions;
-#define csv_options_count 3
+#define csv_options_count 4
 
 typedef struct {
   StringInfoData accum_buf;
   bool           header_done;
   bool           first_row;
   TupleDesc      tupdesc;
+  int            nullstr_len;
   CsvOptions    *options;
+  char          *cached_nullstr;
 } CsvAggState;
 
 extern const char NEWLINE;

src/pg_csv.c

@@ -39,16 +39,23 @@ Datum csv_agg_transfn(PG_FUNCTION_ARGS) {
 
     state = palloc(sizeof(CsvAggState));
     initStringInfo(&state->accum_buf);
-    state->header_done = false;
-    state->first_row   = true;
-    state->tupdesc     = NULL;
-    state->options     = palloc(sizeof(CsvOptions));
+    state->header_done    = false;
+    state->first_row      = true;
+    state->tupdesc        = NULL;
+    state->nullstr_len    = 0;
+    state->cached_nullstr = NULL;
+    state->options        = palloc(sizeof(CsvOptions));
 
     // we'll parse the csv options only once
     HeapTupleHeader opts_hdr =
         PG_NARGS() >= 3 && !PG_ARGISNULL(2) ? PG_GETARG_HEAPTUPLEHEADER(2) : NULL;
     parse_csv_options(opts_hdr, state->options);
 
+    if (state->options->nullstr) {
+      state->cached_nullstr = text_to_cstring(state->options->nullstr);
+      state->nullstr_len    = VARSIZE_ANY_EXHDR(state->options->nullstr);
+    }
+
     MemoryContextSwitchTo(oldctx);
   }
 
@@ -109,10 +116,14 @@ Datum csv_agg_transfn(PG_FUNCTION_ARGS) {
 
     if (i > 0) appendStringInfoChar(&state->accum_buf, state->options->delimiter);
 
-    if (nulls[i]) continue; // empty field for NULL
-
-    char *cstr = datum_to_cstring(datums[i], att->atttypid);
-    csv_append_field(&state->accum_buf, cstr, strlen(cstr), state->options->delimiter);
+    if (nulls[i]) {
+      if (state->cached_nullstr)
+        csv_append_field(&state->accum_buf, state->cached_nullstr, state->nullstr_len,
+                         state->options->delimiter);
+    } else {
+      char *cstr = datum_to_cstring(datums[i], att->atttypid);
+      csv_append_field(&state->accum_buf, cstr, strlen(cstr), state->options->delimiter);
+    }
   }
 
   PG_RETURN_POINTER(state);

test/expected/nullstr.out

@@ -0,0 +1,55 @@
+-- custom null string
+SELECT csv_agg(x, csv_options(nullstr:='<null>')) AS body
+FROM   projects x;
+             body              
+-------------------------------
+ id,name,client_id            +
+ 1,Windows 7,1                +
+ 2,"has,comma",1              +
+ <null>,<null>,<null>         +
+ 4,OSX,2                      +
+ <null>,"has""quote",<null>   +
+ 5,"has,comma and ""quote""",7+
+ 6,"has                       +
+  LF",7                       +
+ 7,"has \r CR",8              +
+ 8,"has \r                    +
+  CRLF""",8
+(1 row)
+
+-- custom null string with no header
+SELECT csv_agg(x, csv_options(nullstr:='NULL', header:=false)) AS body
+FROM   projects x;
+             body              
+-------------------------------
+ 1,Windows 7,1                +
+ 2,"has,comma",1              +
+ NULL,NULL,NULL               +
+ 4,OSX,2                      +
+ NULL,"has""quote",NULL       +
+ 5,"has,comma and ""quote""",7+
+ 6,"has                       +
+  LF",7                       +
+ 7,"has \r CR",8              +
+ 8,"has \r                    +
+  CRLF""",8
+(1 row)
+
+-- custom null string with no header and delimiter
+SELECT csv_agg(x, csv_options(nullstr:='~', delimiter:='|', header:=false)) AS body
+FROM   projects x;
+             body              
+-------------------------------
+ 1|Windows 7|1                +
+ 2|has,comma|1                +
+ ~|~|~                        +
+ 4|OSX|2                      +
+ ~|"has""quote"|~             +
+ 5|"has,comma and ""quote"""|7+
+ 6|"has                       +
+  LF"|7                       +
+ 7|"has \r CR"|8              +
+ 8|"has \r                    +
+  CRLF"""|8
+(1 row)
+

test/sql/nullstr.sql

@@ -0,0 +1,11 @@
+-- custom null string
+SELECT csv_agg(x, csv_options(nullstr:='<null>')) AS body
+FROM   projects x;
+
+-- custom null string with no header
+SELECT csv_agg(x, csv_options(nullstr:='NULL', header:=false)) AS body
+FROM   projects x;
+
+-- custom null string with no header and delimiter
+SELECT csv_agg(x, csv_options(nullstr:='~', delimiter:='|', header:=false)) AS body
+FROM   projects x;