NAME

MongoDB::XS - MongoDB in Perl via C/XS.

SYNOPSIS

use MongoDB::XS;

# This sample code uses AnyEvent for demonstration only;
# any event interface will work.
use AnyEvent;

my $mdb = MongoDB::XS->new("mongodb://127.0.0.1");

my $cv = AE::cv();

# When the fd is readable there is at least one result pending.
my $w = AE::io( $mdb->fd(), 0, sub {
    $mdb->process();
    $cv->send();
} );

my $request_bson = MongoDB::XS::ejson2bson('{"hello": 1}');

$mdb->run_command(
    'admin',
    $request_bson,
    sub ($resp) {
        if ($resp isa Mongo::DB::Error) {
            warn $resp;
        }
        else {
            # Success! $resp is a BSON string.
            # Parse it, and be on your way.
        }
    },
);

$cv->recv();

DESCRIPTION

This library provides MongoDB support in Perl via an XS binding to MongoDB’s official C driver, MongoC.

This is a research project, NOT an official MongoDB driver.

DESIGN

This module attempts to avoid blocking Perl. Toward that end, each instance runs “behind” Perl in a separate thread; a pollable file descriptor facilitates event loop integration.

There is no attempt here to replicate the extensive interfaces found in official MongoDB drivers. Instead, this module provides a minimal interface that should nevertheless expose most useful MongoDB client functionality.

For example, to use a change stream, run the aggregate command with a $changeStream. This will return a cursor, which you can give to getMore to receive successive pieces of the change stream.

Also see /examples in the distribution.

BSON

Several interfaces here expect and return raw BSON (MongoDB’s binary JSON variant).

How you create & parse the BSON is up to you. CPAN offers multiple BSON modules; alternatively, you can use JSON::PP or some other JSON module with this module’s BSON/JSON conversion functions (see below).

STATUS

This module is experimental; its interface is subject to change. It’s been stable for the author as an alternative to mongosh, but YMMV.

NOTES

This library never calls mongoc_cleanup().

GENERAL-USE METHODS

Most of the below run asynchronously.

$obj = CLASS->new( $URI )

Instantiates CLASS with the given $URI.

NB: This may block briefly for DNS lookups.

$obj = OBJ->run_command( $REQUEST_BSON, \&CALLBACK )

Sends a request (encoded as BSON) to MongoDB. (See mongoc_client_command_simple for details.)

The $CALLBACK receives either:

A raw BSON string (to indicate success).
A MongoDB::XS::Error object.

Exceptions that escape the callback are trapped and reported as warnings.

OBJ->get_read_concern( \&CALLBACK )

Calls &CALLBACK with a string that represents OBJ’s active read concern, or undef if there is none.

The string should match the value of one of the read-concern constants mentioned below.

OBJ->set_read_concern( $LEVEL [, \&CALLBACK ] )

Sets the client’s read concern. $LEVEL should be one of the read-concern constants mentioned below.

&CALLBACK, if given, is called with no parameters whenever the request completes.

OBJ->get_write_concern( \&CALLBACK )

Calls &CALLBACK with a reference to a hash that represents OBJ’s active write concern. The hash contents are w, j, and wtimeout; see MongoDB’s documentation for details of what these mean.

(Undef values indicate that no value has been set, so the default is active.)

$obj = OBJ->set_write_concern( \%WC [, \&CALLBACK ] )

get_write_concern()’s complement. It expects the same hash reference. Individual values can be omitted (or left undef) to indicate a default value.

For example, the following:

{
    w        => 1,
    j        => undef,
    wtimeout => 7,
}

… indicates the default value for j but explicit values for w and wtimeout.

&CALLBACK, if given, is called with no parameters whenever the request completes.

CONSTANTS

READ_CONCERN_LOCAL, READ_CONCERN_MAJORITY, READ_CONCERN_LINEARIZABLE, READ_CONCERN_AVAILABLE, and READ_CONCERN_SNAPSHOT

EVENT LOOP INTEGRATION METHODS

OBJ->process()

Reads any queued request results and calls their associated callbacks.

$fd = OBJ->fd()

Returns the OS file descriptor that, when readable, indicates that at least one result is ready for process()ing.

NOTE: Some Perl event libraries only interact with Perl filehandles. For these libraries you can do:

use POSIX ();

my $fd_dup = POSIX::dup($mdb->fd()) or die "dup: $!";

open my $mdb_fh, '+>&', $fd_dup or die "open(dup): $!";

(The dup() ensures that, when Perl closes $mdb_fh, it won’t affect mongoc.)

STATIC FUNCTIONS

$str = mongoc_version_string()

Returns MongoC’s version as a string.

$json = bson2cejson( $BSON )

Converts BSON to Canonical Extended JSON.

$json = bson2rejson( $BSON )

Converts BSON to Relaxed Extended JSON.

$bson = ejson2bson( $EXT_JSON )

Converts Extended JSON (either variant??) to a raw BSON string.

LICENSE & COPYRIGHT

This library is licensed under the same license as Perl itself. See perlartistic.

FGasper / p5-MongoDB-XS