README.md
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