Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Non-blocking upstream module for Nginx to connect to MongoDB

branch: master

Update nginx compatibility list.

Change-Id: Ib21ca79e4d9b2c33d844bc9074037865483372e6
Signed-off-by: Piotr Sikora <piotr.sikora@frickle.com>
latest commit 214bd0b965
Piotr Sikora PiotrSikora authored July 06, 2012
Octocat-spinner-32 src Add "mongo_buffers" and "mongo_busy_buffers_size" directives. April 01, 2012
Octocat-spinner-32 t Add BSON-to-JSON filter. April 01, 2012
Octocat-spinner-32 LICENSE nginx can be web scale now ;) February 18, 2012
Octocat-spinner-32 README.md Update nginx compatibility list. July 06, 2012
Octocat-spinner-32 config Add BSON-to-JSON filter. April 01, 2012
README.md

About

ngx_mongo is an upstream module that allows nginx to communicate directly with MongoDB database.

Status

This module is considered stable and it's compatible with the following nginx releases:

  • 1.1.4+ (tested with 1.1.4 to 1.1.19),
  • 1.2.x (tested with 1.2.0 to 1.2.2),
  • 1.3.x (tested with 1.3.0 to 1.3.2).

Configuration directives

mongo_auth

  • syntax: mongo_auth username password
  • default: none
  • context: server, location, if location

Set optional authentication details.

mongo_pass

  • syntax: mongo_pass upstream
  • default: none
  • context: location, if location

Set database address, this can be either: IP:port or name of existing upstream block.

mongo_query

  • syntax: mongo_query operation database[.collection] query|$request_body
  • default: none
  • context: location, if location

Set query details.

Valid operations are:

  • command,
  • select,
  • insert,
  • update,
  • upsert,
  • delete.

Query passed via $request_body can be either in BSON (with Content-Type set to application/x-bson) or JSON format.

mongo_json

  • syntax: mongo_json on|off
  • default: off
  • context: http, server, location, if location

Convert output from BSON (default) to JSON format.

mongo_bind

  • syntax: mongo_bind address
  • default: none
  • context: http, server, location

Set local address that should be used when connecting to the database.

mongo_connect_timeout

  • syntax: mongo_connect_timeout timeout
  • default: 60s
  • context: http, server, location

Configure connection timeout.

mongo_send_timeout

  • syntax: mongo_send_timeout timeout
  • default: 60s
  • context: http, server, location

Configure send timeout.

mongo_read_timeout

  • syntax: mongo_read_timeout timeout
  • default: 60s
  • context: http, server, location

Configure read timeout.

mongo_buffering

  • syntax: mongo_buffering on|off
  • default: on
  • context: http, server, location

Enable or disable buffering of the database response.

mongo_buffer_size

  • syntax: mongo_buffer_size size
  • default: 4k|8k
  • context: http, server, location

Configure buffers used to read database response.

mongo_buffers

  • syntax: mongo_buffers number size
  • default: 8 4k|8k
  • context: http, server, location

Configure buffers used to read database response.

mongo_busy_buffers_size

  • syntax: mongo_busy_buffers_size size
  • default: 8k|16k
  • context: http, server, location

Configure buffers used to read database response.

mongo_next_upstream

  • syntax: mongo_next_upstream error|timeout|off ...
  • default: error timeout
  • context: http, server, location

Configure in which case query should be passed to another server.

Configuration variables

$mongo_request_namespace

Full namespace (database[.collection]) used to query database.

$mongo_request_query

JSON object used to query database. This variable is empty when query is passed in request body.

$mongo_request_bson

BSON object used to query database.

Sample configurations

Sample configuration #1

Return content of the cats collection from the test database.

http {
    upstream database {
        server     127.0.0.1:27017;
        keepalive  1;
    }

    server {
        location = /cats {
            mongo_pass   database;
            mongo_query  select test.cats "{}";
        }

        location = /cats.json {
            mongo_pass   database;
            mongo_query  select test.cats "{}";
            mongo_json   on;
        }
    }
}

Sample configuration #2

Insert object(s) passed in the request body to the cats collection in the test database.

http {
    upstream database {
        server     127.0.0.1:27017;
        keepalive  1;
    }

    server {
        location / {
            mongo_pass   database;
            mongo_auth   user pass;
            mongo_query  insert test.cats $request_body;
        }
    }
}

Testing

ngx_mongo comes with complete test suite based on Test::Nginx.

You can test it by running:

$ prove

License

Copyright (c) 2011-2012, Simpl <foss@simpl.it>
Copyright (c) 2011-2012, FRiCKLE <info@frickle.com>
Copyright (c) 2011-2012, Piotr Sikora <piotr.sikora@frickle.com>
Copyright (c) 2002-2011, Igor Sysoev <igor@sysoev.ru>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

See also

Something went wrong with that request. Please try again.