ABOUT:
------
ngx_postgres is an upstream module that allows nginx
to communicate directly with PostgreSQL database.

Response is generated in RDS format, so it's compatible with:
rds_json, ngx_drizzle and ngx_oracle modules.


CONFIGURATION DIRECTIVES:
-------------------------

  postgres_server ip[:port] dbname=dbname user=user password=pass (context: upstream)
  -----------------------------------------------------------------------------------
  Set details about the database server.

  default: none


  postgres_keepalive off | max=count [mode=single|multi] [overflow=ignore|reject] (context: upstream)
  --------------------------------------------------------------------------------------------------- 
  Configure keepalive parameters:
  - max      - maximum number of keepalive connections (per worker process),
  - mode     - backend matching mode,
  - overflow - either "ignore" the fact that keepalive connection pool
               is full and allow request, but close connection afterwards
               or "reject" request with 503 Service Unavailable response.

  default: max=10 mode=single overflow=ignore


  postgres_pass upstream (context: http, server, location)
  --------------------------------------------------------
  Set name of an upstream block that will be used for the database
  connections (it can include variables).

  default: none


  postgres_query query (context: http, server, location)
  ------------------------------------------------------
  Set query string (it can include variables).

  default: none


  postgres_get_value row column (context: http, server, location)
  ---------------------------------------------------------------
  Return single value from the result-set in 'text/plain' format.
  Row and column numbers start at 0.

  default: none


  postgres_connect_timeout timeout (context: http, server, location)
  ------------------------------------------------------------------
  Set timeout for connecting to the database (in milliseconds).

  default: 10000ms (10s)


  postgres_result_timeout timeout (context: http, server, location)
  -----------------------------------------------------------------
  Set timeout for receiving result from the database (in milliseconds).

  default: 30000ms (30s)


EXAMPLE CONFIGURATION #1:
-------------------------
http {
    upstream database {
        postgres_server     127.0.0.1 dbname=test
                            user=monty password=some_pass;
    }

    server {
        location / {
            postgres_pass   database;
            postgres_query  "SELECT * FROM cats";
        }
    }
}

Return content of table "cats" (in RDS format).


EXAMPLE CONFIGURATION #2:
-------------------------
http {
    upstream database {
        postgres_server     127.0.0.1 dbname=test
                            user=monty password=some_pass;
    }

    server {
        location / {
            postgres_pass   database;
            postgres_query  SELECT * FROM sites WHERE host='$http_host'";
        }
    }
}

Return only those rows from table "sites" that match "host" filter
which is evaluated for each request based on its $http_host variable.


EXAMPLE CONFIGURATION #3:
-------------------------
http {
    upstream database {
        postgres_server     127.0.0.1 dbname=test
                            user=monty password=some_pass;
    }

    server {
        location / {
            eval_subrequest_in_memory  off;

            eval $backend {
                postgres_pass       database;
                postgres_query      "SELECT * FROM backends LIMIT 1";
                postgres_get_value  0 0;
            }

            proxy_pass  $backend;
        }
    }
}

Pass request to the backend that was selected from the database
(traffic router).