Perl driver for the MongoDB
Perl C C++ XS
Latest commit 04bb782 Nov 30, 2016 @xdg xdg PERL-671 Make CRUD tests more robust
This commit makes two changes:

* Is more careful about constructing and testing server version numbers
* Avoids trying to modify post-operation collection test data if not
Failed to load latest commit information.
bson PERL-611 Add support for Decimal128 Jul 7, 2016
devel PERL-680 PERL-684 Update Max Staleness implementation Nov 28, 2016
inc PERL-611 Add support for Decimal128 Jul 7, 2016
lib Restore development release POD prelude Nov 29, 2016
t PERL-671 Make CRUD tests more robust Nov 30, 2016
xs Throw error when decoding an invalid BSON document Apr 26, 2016
xt/author minor: Skip xt/author/circular-refs.t if no server running Sep 12, 2016
.gitignore PERL-611 Add support for Decimal128 Jul 7, 2016
.gitmodules remove unused meta-driver submodule Sep 8, 2014
.mailmap Add Rassi as author in dist.ini, update .mailmap Sep 12, 2016
.travis.yml Devel: make .travis.yml give a list of prereqs and versions Aug 18, 2016 Improve Mar 11, 2016
Changes Update Changes Nov 29, 2016 Fix typo in Oct 27, 2016
LICENSE adding LICENSE to repo Jun 28, 2013
Makefile.PL PERL-611 Add support for Decimal128 Jul 7, 2016 symlink readme Mar 19, 2014
dist.ini PERL-667 Add and pass minimal Perl::Critic release tests Sep 28, 2016
perl_mongo.c Fix incompatible pointer type warning Jul 13, 2016
perl_mongo.h load bson.h first, so it stops fighting perl.h over 'bool' May 14, 2015
perlcritic.rc PERL-667 Add and pass minimal Perl::Critic release tests Sep 28, 2016
ppport.h update ppport.h May 7, 2015
pstdint.h Configure platform-specific libbson headers Mar 24, 2014
weaver.ini document alpha status and roadmap Nov 10, 2014

Contributing Guidelines

This file describes requirements and procedures for developing and testing the MongoDB Perl driver from its code repository. For instructions installing from CPAN or tarball, see the file instead.

While this distribution is shipped using Dist::Zilla, you do not need to install it or use it for development and testing.


mongo-perl-driver is the official client-side driver for talking to MongoDB with Perl. It is free software released under the Apache 2.0 license and available on CPAN under the distribution name MongoDB.

How to Ask for Help

If you are having difficulty building the driver after reading the instructions here, please email the mongodb-user mailing list to ask for help. Please include in your email all of the following information:

  • The version of the driver you are trying to build (branch or tag).
    • Examples: maint-v0 branch, v0.704.2.0 tag
  • The output of perl -V
  • How your version of perl was built or installed.
    • Examples: plenv, perlbrew, built from source
  • The error you encountered. This may be compiler, Config::AutoConf, or other output.

Failure to include the relevant information will result in additional round-trip communications to ascertain the necessary details, delaying a useful response.

How to Contribute

The code for mongo-perl-driver is hosted on GitHub at:

If you would like to contribute code, documentation, tests, or bugfixes, follow these steps:

  1. Fork the project on GitHub.
  2. Clone the fork to your local machine.
  3. Make your changes and push them back up to your GitHub account.
  4. Send a "pull request" with a brief description of your changes, and a link to a JIRA ticket if there is one.

If you are unfamiliar with GitHub, start with their excellent documentation here:

Compiler tool requirements

This module requires make and a compiler.

For example, Debian and Ubuntu users should issue the following command:

$ sudo apt-get install build-essential

Users of Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux, Fedora, etc.) should issue the following command:

$ sudo yum install make gcc

On Windows, StrawberryPerl ships with a GCC compiler.

On Mac, install XCode or just the XCode command line tools.

Installing Perl dependencies as a non-privileged user

If you do not have write permissions to your Perl's site library directory (perl -V:sitelib), then you will need to use your CPAN client or run make install as root or with sudo.

Alternatively, you can configure a local library. See local::lib on CPAN for more details. If you configure a local library, don't forget to modify your .bashrc or equivalent files.

Configuration and dependencies

You will need to install Config::AutoConf and Path::Tiny to be able to run the Makefile.PL.

$ cpan Config::AutoConf Path::Tiny

To configure:

$ perl Makefile.PL

The output will highlight any missing dependencies. Install those with the cpan client.

$ cpan [list of dependencies]

You may also use cpan to install the current stable MongoDB driver with cpan MongoDB, which should pick up most of the dependencies you will need automatically.

Building and testing

Most tests will skip unless a MongoDB database is available either on the default localhost and port or on an alternate host:port specified by the MONGOD environment variable:

$ export MONGOD=localhosts:31017

You can download a free, community edition of MongoDB from MongoDB Downloads.

To build and test (after configuration):

$ make
$ make test