{"id":28479027,"url":"https://github.com/openresty/ngx_postgres","last_synced_at":"2025-07-03T09:30:43.077Z","repository":{"id":136300577,"uuid":"99741159","full_name":"openresty/ngx_postgres","owner":"openresty","description":"OpenResty's fork of FRiCKLE/ngx_postgres","archived":false,"fork":false,"pushed_at":"2024-08-07T08:38:17.000Z","size":284,"stargazers_count":26,"open_issues_count":4,"forks_count":14,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-06-07T18:07:53.017Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openresty.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-08T22:24:53.000Z","updated_at":"2025-03-26T14:47:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"b9081487-d6e2-4fb1-aa95-7fda6c146288","html_url":"https://github.com/openresty/ngx_postgres","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/openresty/ngx_postgres","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fngx_postgres","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fngx_postgres/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fngx_postgres/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fngx_postgres/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/ngx_postgres/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fngx_postgres/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263300060,"owners_count":23445169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-07T18:07:55.211Z","updated_at":"2025-07-03T09:30:43.064Z","avatar_url":"https://github.com/openresty.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"About\n=====\n`ngx_postgres` is an upstream module that allows `nginx` to communicate directly\nwith `PostgreSQL` database.\n\nResponse is generated in `rds` format, so it's compatible with `ngx_rds_json`\nand `ngx_drizzle` modules.\n\n\nStatus\n======\nThis module is production-ready and it's compatible with following nginx\nreleases:\n\n- 0.7.x (tested with 0.7.60 to 0.7.69),\n- 0.8.x (tested with 0.8.0 to 0.8.55),\n- 0.9.x (tested with 0.9.0 to 0.9.7),\n- 1.0.x (tested with 1.0.0 to 1.0.11),\n- 1.1.x (tested with 1.1.0 to 1.1.12).\n- 1.2.x (tested with 1.2.3 to 1.2.3).\n- 1.3.x (tested with 1.3.4 to 1.3.4).\n\n\nConfiguration directives\n========================\npostgres_server\n---------------\n* **syntax**: `postgres_server ip[:port] dbname=dbname user=user password=pass`\n* **default**: `none`\n* **context**: `upstream`\n\nSet details about the database server.\n\n\npostgres_keepalive\n------------------\n* **syntax**: `postgres_keepalive off | max=count [mode=single|multi] [overflow=ignore|reject]`\n* **default**: `max=10 mode=single overflow=ignore`\n* **context**: `upstream`\n\nConfigure keepalive parameters:\n\n- `max`      - maximum number of keepalive connections (per worker process),\n- `mode`     - backend matching mode,\n- `overflow` - either `ignore` the fact that keepalive connection pool is full\n  and allow request, but close connection afterwards or `reject` request with\n  `503 Service Unavailable` response.\n\n\npostgres_pass\n-------------\n* **syntax**: `postgres_pass upstream`\n* **default**: `none`\n* **context**: `location`, `if location`\n\nSet name of an upstream block that will be used for the database connections\n(it can include variables).\n\n\npostgres_query\n--------------\n* **syntax**: `postgres_query [methods] query`\n* **default**: `none`\n* **context**: `http`, `server`, `location`, `if location`\n\nSet query string (it can include variables). When methods are specified then\nquery is used only for them, otherwise it's used for all methods.\n\nThis directive can be used more than once within same context.\n\n\npostgres_rewrite\n----------------\n* **syntax**: `postgres_rewrite [methods] condition [=]status_code`\n* **default**: `none`\n* **context**: `http`, `server`, `location`, `if location`\n\nRewrite response `status_code` when given condition is met (first one wins!):\n\n- `no_changes` - no rows were affected by the query,\n- `changes`    - at least one row was affected by the query,\n- `no_rows`    - no rows were returned in the result-set,\n- `rows`       - at least one row was returned in the result-set.\n\nWhen `status_code` is prefixed with `=` sign then original response body is\nsend to the client instead of the default error page for given `status_code`.\n\nBy design both `no_changes` and `changes` apply only to `INSERT`,\n`UPDATE`, `DELETE`, `MOVE`, `FETCH` and `COPY` SQL queries.\n\nThis directive can be used more than once within same context.\n\n\npostgres_output\n---------------\n* **syntax**: `postgres_output rds|text|value|binary_value|none`\n* **default**: `rds`\n* **context**: `http`, `server`, `location`, `if location`\n\nSet output format:\n\n- `rds`          - return all values from the result-set in `rds` format\n  (with appropriate `Content-Type`),\n- `text`         - return all values from the result-set in text format\n  (with default `Content-Type`), values are separated by new line,\n- `value`        - return single value from the result-set in text format\n  (with default `Content-Type`),\n- `binary_value` - return single value from the result-set in binary format\n  (with default `Content-Type`),\n- `none`         - don't return anything, this should be used only when\n  extracting values with `postgres_set` for use with other modules (without\n  `Content-Type`).\n\n\npostgres_set\n------------\n* **syntax**: `postgres_set $variable row column [optional|required]`\n* **default**: `none`\n* **context**: `http`, `server`, `location`\n\nGet single value from the result-set and keep it in $variable.\n\nWhen requirement level is set to `required` and value is either out-of-range,\n`NULL` or zero-length, then nginx returns `500 Internal Server Error` response.\nSuch condition is silently ignored when requirement level is set to `optional`\n(default).\n\nRow and column numbers start at 0. Column name can be used instead of column\nnumber.\n\nThis directive can be used more than once within same context.\n\n\npostgres_escape\n---------------\n* **syntax**: `postgres_escape $escaped [[=]$unescaped]`\n* **default**: `none`\n* **context**: `http`, `server`, `location`\n\nEscape and quote `$unescaped` string. Result is stored in `$escaped` variable\nwhich can be safely used in SQL queries.\n\nBecause nginx cannot tell the difference between empty and non-existing strings,\nall empty strings are by default escaped to `NULL` value. This behavior can be\ndisabled by prefixing `$unescaped` string with `=` sign.\n\n\npostgres_connect_timeout\n------------------------\n* **syntax**: `postgres_connect_timeout timeout`\n* **default**: `10s`\n* **context**: `http`, `server`, `location`\n\nSet timeout for connecting to the database.\n\n\npostgres_result_timeout\n-----------------------\n* **syntax**: `postgres_result_timeout timeout`\n* **default**: `30s`\n* **context**: `http`, `server`, `location`\n\nSet timeout for receiving result from the database.\n\n\nConfiguration variables\n=======================\n$postgres_columns\n-----------------\nNumber of columns in received result-set.\n\n\n$postgres_rows\n--------------\nNumber of rows in received result-set.\n\n\n$postgres_affected\n------------------\nNumber of rows affected by `INSERT`, `UPDATE`, `DELETE`, `MOVE`, `FETCH`\nor `COPY` SQL query.\n\n\n$postgres_query\n---------------\nSQL query, as seen by `PostgreSQL` database.\n\n\nSample configurations\n=====================\nSample configuration #1\n-----------------------\nReturn content of table `cats` (in `rds` format).\n\n    http {\n        upstream database {\n            postgres_server  127.0.0.1 dbname=test\n                             user=test password=test;\n        }\n\n        server {\n            location / {\n                postgres_pass   database;\n                postgres_query  \"SELECT * FROM cats\";\n            }\n        }\n    }\n\n\nSample configuration #2\n-----------------------\nReturn only those rows from table `sites` that match `host` filter which\nis evaluated for each request based on its `$http_host` variable.\n\n    http {\n        upstream database {\n            postgres_server  127.0.0.1 dbname=test\n                             user=test password=test;\n        }\n\n        server {\n            location / {\n                postgres_pass   database;\n                postgres_query  SELECT * FROM sites WHERE host='$http_host'\";\n            }\n        }\n    }\n\n\nSample configuration #3\n-----------------------\nPass request to the backend selected from the database (traffic router).\n\n    http {\n        upstream database {\n            postgres_server  127.0.0.1 dbname=test\n                             user=test password=test;\n        }\n\n        server {\n            location / {\n                eval_subrequest_in_memory  off;\n\n                eval $backend {\n                    postgres_pass    database;\n                    postgres_query   \"SELECT * FROM backends LIMIT 1\";\n                    postgres_output  value 0 0;\n                }\n\n                proxy_pass  $backend;\n            }\n        }\n    }\n\nRequired modules (other than `ngx_postgres`):\n\n- [nginx-eval-module (agentzh's fork)](http://github.com/agentzh/nginx-eval-module),\n\n\nSample configuration #4\n-----------------------\nRestrict access to local files by authenticating against `PostgreSQL` database.\n\n    http {\n        upstream database {\n            postgres_server  127.0.0.1 dbname=test\n                             user=test password=test;\n        }\n\n        server {\n            location = /auth {\n                internal;\n\n                postgres_escape   $user $remote_user;\n                postgres_escape   $pass $remote_passwd;\n\n                postgres_pass     database;\n                postgres_query    \"SELECT login FROM users WHERE login=$user AND pass=$pass\";\n                postgres_rewrite  no_rows 403;\n                postgres_output   none;\n            }\n\n            location / {\n                auth_request      /auth;\n                root              /files;\n            }\n        }\n    }\n\nRequired modules (other than `ngx_postgres`):\n\n- [ngx_http_auth_request_module](http://mdounin.ru/hg/ngx_http_auth_request_module/),\n- [ngx_coolkit](http://github.com/FRiCKLE/ngx_coolkit).\n\n\nSample configuration #5\n-----------------------\nSimple RESTful webservice returning JSON responses with appropriate HTTP status\ncodes.\n\n    http {\n        upstream database {\n            postgres_server  127.0.0.1 dbname=test\n                             user=test password=test;\n        }\n\n        server {\n            set $random  123;\n\n            location = /numbers/ {\n                postgres_pass     database;\n                rds_json          on;\n\n                postgres_query    HEAD GET  \"SELECT * FROM numbers\";\n\n                postgres_query    POST      \"INSERT INTO numbers VALUES('$random') RETURNING *\";\n                postgres_rewrite  POST      changes 201;\n\n                postgres_query    DELETE    \"DELETE FROM numbers\";\n                postgres_rewrite  DELETE    no_changes 204;\n                postgres_rewrite  DELETE    changes 204;\n            }\n\n            location ~ /numbers/(?\u003cnum\u003e\\d+) {\n                postgres_pass     database;\n                rds_json          on;\n\n                postgres_query    HEAD GET  \"SELECT * FROM numbers WHERE number='$num'\";\n                postgres_rewrite  HEAD GET  no_rows 410;\n\n                postgres_query    PUT       \"UPDATE numbers SET number='$num' WHERE number='$num' RETURNING *\";\n                postgres_rewrite  PUT       no_changes 410;\n\n                postgres_query    DELETE    \"DELETE FROM numbers WHERE number='$num'\";\n                postgres_rewrite  DELETE    no_changes 410;\n                postgres_rewrite  DELETE    changes 204;\n            }\n        }\n    }\n\nRequired modules (other than `ngx_postgres`):\n\n- [ngx_rds_json](http://github.com/agentzh/rds-json-nginx-module).\n\nSample configuration #6\n-----------------------\nUse GET parameter in SQL query.\n\n    location /quotes {\n        set_unescape_uri  $txt $arg_txt;\n        postgres_escape   $txt;\n        postgres_pass     database;\n        postgres_query    \"SELECT * FROM quotes WHERE quote=$txt\";\n    }\n\nRequired modules (other than `ngx_postgres`):\n\n- [ngx_set_misc](http://github.com/agentzh/set-misc-nginx-module).\n\nTesting\n=======\n`ngx_postgres` comes with complete test suite based on [Test::Nginx](http://github.com/agentzh/test-nginx).\n\nYou can test core functionality by running:\n\n`$ TEST_NGINX_IGNORE_MISSING_DIRECTIVES=1 prove`\n\nYou can also test interoperability with following modules:\n\n- [ngx_coolkit](http://github.com/FRiCKLE/ngx_coolkit),\n- [ngx_echo](github.com/agentzh/echo-nginx-module),\n- [ngx_form_input](http://github.com/calio/form-input-nginx-module),\n- [ngx_set_misc](http://github.com/agentzh/set-misc-nginx-module),\n- [ngx_http_auth_request_module](http://mdounin.ru/hg/ngx_http_auth_request_module/),\n- [nginx-eval-module (agentzh's fork)](http://github.com/agentzh/nginx-eval-module),\n- [ngx_rds_json](http://github.com/agentzh/rds-json-nginx-module).\n\nby running:\n\n`$ prove`\n\n\nLicense\n=======\n    Copyright (c) 2010-2017, FRiCKLE Piotr Sikora \u003cinfo@frickle.com\u003e\n    Copyright (c) 2009-2017, Xiaozhe Wang \u003cchaoslawful@gmail.com\u003e\n    Copyright (c) 2009-2017, Yichun Zhang \u003cagentzh@gmail.com\u003e\n    All rights reserved.\n\n    Redistribution and use in source and binary forms, with or without\n    modification, are permitted provided that the following conditions\n    are met:\n    1. Redistributions of source code must retain the above copyright\n       notice, this list of conditions and the following disclaimer.\n    2. Redistributions in binary form must reproduce the above copyright\n       notice, this list of conditions and the following disclaimer in the\n       documentation and/or other materials provided with the distribution.\n\n    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS\n    \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT\n    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\n    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\n    HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\n    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\n    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\n    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\n    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\nThis software includes also parts of the code from:\n\n- `nginx` (copyrighted by **Igor Sysoev** under BSD license),\n- `ngx_http_upstream_keepalive` module (copyrighted by **Maxim Dounin**\n  under BSD license).\n\n\nSee also\n========\n- [ngx_rds_json](http://github.com/agentzh/rds-json-nginx-module),\n- [ngx_drizzle](http://github.com/chaoslawful/drizzle-nginx-module),\n- [ngx_lua](http://github.com/chaoslawful/lua-nginx-module),\n- [nginx-eval-module (agentzh's fork)](http://github.com/agentzh/nginx-eval-module).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fngx_postgres","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Fngx_postgres","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fngx_postgres/lists"}