1Name 2==== 3 4ngx_rds_csv - Nginx output filter module to convert Resty-DBD-Streams 5(RDS) to Comma-Separated Values (CSV) 6 7Table of Contents 8================= 9 10* [Name](#name) 11* [Status](#status) 12* [Synopsis](#synopsis) 13* [Description](#description) 14* [Directives](#directives) 15 * [rds_csv](#rds_csv) 16 * [rds_csv_row_terminator](#rds_csv_row_terminator) 17 * [rds_csv_field_separator](#rds_csv_field_separator) 18 * [rds_csv_field_name_header](#rds_csv_field_name_header) 19 * [rds_csv_content_type](#rds_csv_content_type) 20 * [rds_csv_buffer_size](#rds_csv_buffer_size) 21* [Installation](#installation) 22* [Compatibility](#compatibility) 23* [Author](#author) 24* [Copyright & License](#copyright--license) 25* [See Also](#see-also) 26 27Status 28====== 29 30This module is considered production ready. 31 32Synopsis 33======== 34 35```nginx 36location /foo { 37 # drizzle_pass/postgres_pass/... 38 39 rds_csv on; 40 rds_csv_row_terminator "\n"; # default to "\r\n" 41} 42``` 43 44Description 45=========== 46 47This module implements an efficient output filter that converts 48Resty-DBD-Streams (RDS) generated by [ngx_drizzle](https://github.com/openresty/drizzle-nginx-module) 49and [ngx_postgres](https://github.com/FRiCKLE/ngx_postgres/) 50to Comma-Separated Values (CSV) format in a streaming fashion. 51By default, the CSV format is in compliance with [RFC 4180](http://tools.ietf.org/html/rfc4180): 52 53http://tools.ietf.org/html/rfc4180 54 55SQL NULL values will be converted to empty field value, just like 56empty string values. 57 58[Back to TOC](#table-of-contents) 59 60Directives 61========== 62 63[Back to TOC](#table-of-contents) 64 65rds_csv 66------- 67**syntax:** *rds_csv on|off* 68 69**default:** *rds_csv off* 70 71**context:** *http, server, location, location if* 72 73Enables this output filter when on and disables otherwise. 74 75[Back to TOC](#table-of-contents) 76 77rds_csv_row_terminator 78---------------------- 79 80**syntax:** *rds_csv_row_terminator <str>* 81 82**default:** *rds_csv_row_terminator "\r\n"* 83 84**context:** *http, server, location, location if* 85 86Specifies the row terminator used by the CSV format. 87Only `"\r\n"` and `"\n"` are allowed. 88 89Defaults to `"\r\n"`, i.e., CR LF, according to [RFC 4180](http://tools.ietf.org/html/rfc4180). 90 91[Back to TOC](#table-of-contents) 92 93rds_csv_field_separator 94----------------------- 95 96**syntax:** *rds_csv_field_separator <char>* 97 98**default:** *rds_csv_field_separator ","* 99 100**context:** *http, server, location, location if* 101 102Specifies the field seperator used by the CSV format. 103Only `","`, `";"`, and `"\t"` are allowed. 104 105Defaults to `","` according to [RFC 4180](http://tools.ietf.org/html/rfc4180). 106 107[Back to TOC](#table-of-contents) 108 109rds_csv_field_name_header 110------------------------- 111 112**syntax:** *rds_csv_field_name_header on|off* 113 114**default:** *rds_csv_field_name_header off* 115 116**context:** *http, server, location, location if* 117 118Emits the first line of field names when this directive is set on, 119and none otherwise. 120 121[Back to TOC](#table-of-contents) 122 123rds_csv_content_type 124-------------------- 125**syntax:** *rds_csv_content_type <str>* 126 127**default:** *rds_csv_content_type "text/csv; header=<present|absence>"* 128 129**context:** *http, server, location, location if* 130 131Specifies the `Content-Type` response header generated by this module. 132 133Defaults to `"text/csv; header=present"` or `"text/csv; header=absence"`, 134depending on whether [rds_csv_field_name_header](#rds_csv_field_name_header) is on or off. 135 136[Back to TOC](#table-of-contents) 137 138rds_csv_buffer_size 139------------------- 140**syntax:** *rds_csv_buffer_size <size>* 141 142**default:** *rds_csv_buffer_size 4k/8k* 143 144**context:** *http, server, location, location if* 145 146The lager this buffer size setting, the less streammy the output 147will be. 148 149[Back to TOC](#table-of-contents) 150 151Installation 152============ 153 154You're recommended to install this module (as well as the Nginx core and many other goodies) via the [ngx_openresty bundle](http://openresty.org). See [the detailed instructions](http://openresty.org/#Installation) for downloading and installing ngx_openresty into your system. This is the easiest and most safe way to set things up. 155 156Alternatively, you can install this module manually with the Nginx source: 157 158Grab the nginx source code from [nginx.org](http://nginx.org/), for example, 159the version 1.13.6 (see [nginx compatibility](#compatibility)), and then build the source with this module: 160 161```bash 162 163 $ wget 'http://nginx.org/download/nginx-1.13.6.tar.gz' 164 $ tar -xzvf nginx-1.13.6.tar.gz 165 $ cd nginx-1.13.6/ 166 167 # Here we assume you would install you nginx under /opt/nginx/. 168 $ ./configure --prefix=/opt/nginx \ 169 --add-module=/path/to/rds-csv-nginx-module 170 171 $ make -j2 172 $ make install 173``` 174 175Download the latest version of the release tarball of this module from [rds-csv-nginx-module file list](https://github.com/openresty/rds-csv-nginx-module/tags). 176 177Also, this module is included and enabled by default in the [ngx_openresty bundle](http://openresty.org). 178 179[Back to TOC](#table-of-contents) 180 181Compatibility 182============= 183 184This module is compatible with the following versions of Nginx: 185 186* **1.13.x** (last tested: 1.13.6) 187* **1.12.x** 188* **1.11.x** (last tested: 1.11.2) 189* **1.10.x** 190* **1.9.x** (last tested: 1.9.7) 191* **1.8.x** 192* **1.7.x** (last tested: 1.7.10) 193* **1.6.x** 194* **1.5.x** 195* **1.4.x** (last tested: 1.4.3) 196* **1.2.x** (last tested: 1.2.9) 197* **1.1.x** (last tested: 1.1.5) 198* **1.0.x** (last tested: 1.0.8) 199 200[Back to TOC](#table-of-contents) 201 202Author 203====== 204Yichun "agentzh" Zhang <agentzh@gmail.com>, OpenResty Inc. 205 206[Back to TOC](#table-of-contents) 207 208Copyright & License 209=================== 210This module is licenced under the BSD license. 211 212Copyright (C) 2011-2018, Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, OpenResty Inc. 213 214All rights reserved. 215 216Redistribution and use in source and binary forms, with or without 217modification, are permitted provided that the following conditions 218are met: 219 220* Redistributions of source code must retain the above copyright 221notice, this list of conditions and the following disclaimer. 222* Redistributions in binary form must reproduce the above copyright 223notice, this list of conditions and the following disclaimer in the 224documentation and/or other materials provided with the distribution. 225 226THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 227"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 228LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 229A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 230HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 231SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 232TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 233PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 234LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 235NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 236SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 237 238[Back to TOC](#table-of-contents) 239 240See Also 241======== 242 243* [ngx_drizzle](https://github.com/openresty/drizzle-nginx-module) 244* [ngx_postgres](https://github.com/FRiCKLE/ngx_postgres/) 245* [ngx_rds_json](https://github.com/openresty/rds-json-nginx-module) 246 247[Back to TOC](#table-of-contents) 248 249