NAME

CHI::Driver::MongoDB - MongoDB driver for CHI

VERSION

version 0.0101

SYNOPSIS

    use CHI;
 
    my $cache = CHI->new (
        driver          => 'MongoDB',
        namespace       => 'foo',
        # optional, default: _CHI_
        db_name         => '...',
        # optional, default: mongodb://127.0.0.1:27017
        connection_uri  => '...',
        # optional
        mongodb_options => { ... },
    );

DESCRIPTION

Driver to use MongoDB as storage back end for CHI.

CHI namespaces are translated to MongoDB collections, so you can use the same database name for all CHI instances (or simply use the default and omit the parameter).

The driver supports the expires_on_backend option, but be aware that the expiration actually happens within a short but unspecified time frame after the exact expiration timeout (cf. "FAILING TESTS").

By default the MongoDB server is expected to be available on localhost, port 27017. Pass the connection_uri param to override this. For testing purposes, set the MONGODB_CONNECTION_URI environment variable.

WARNING

Because of the not fully understood test failures this module is still considered to be a beta release.

On the other hand I have never received any reports - which either means that nobody uses it or that it does work as intended ;-)

Please open a bug report on https://rt.perl.org/ or send me a mail if you encounter any problems.

CONSTRUCTOR OPTIONS

connection_uri: String

Where the MongoDB server is listening. By default, mongodb://127.0.0.1:27017 is used.

See "CONNECTION-STRING-URI" in MongoDB::MongoClient for details.

db_name: String

The database name inside MongoDB. Defaults to _CHI_. The name is arbitrary but should of course not clash with your other databases.

mongodb_options: HASHREF

Arbitrary options which are passed to the constructor of the underlying MongoDB::MongoClient object.

FAILING TESTS

Currently, you should expect four failing tests from the CHI test suite: 94, 205-206, 904.

94: Failed test 'threw Regexp ((?^:discard timeout .* reached))'

I do not know yet, why the test functions succeeds while it is supposed to die.

205: Failed test 'cannot get_object(key0) after expire'

206: Failed test 'cannot get_object(key1) after expire'

MongoDB uses a dedicated thread to remove documents whose lifetime has expired. It checks the stored documents periodically but that means there is a short period of time between the moment a document expires and the moment it is actually removed. This should be no problem for our caching purposes but is the reason why these tests fail.

904 Failed test 'test_serializers died (Insecure dependency in eval while running with -T switch...

No idea yet what is wrong here.

Fixing the second and third failing test may not be possible at all, but I haven't yet found a way to disable indiviual tests.

Other than these four, 944 subtests succeed while 67 are skipped.

I have seen test runs where for some unknown reason a large number of tests fail. I do not know why that happens. The MongoDB database is dropped and recreated on every run of the test suite. On simply re-running the whole test usually only the four tests shown above fail.

TODO

In no particular order:

Allow passing in a preconfigured MongoDB object.

Allow using Mango instead of MongoDB.

Implement store_multi ( $key_data, $options ) method.

Implement LRU discard policy.

Implement support for size awareness in the back end.

Caveat: As of version 3.2 MongoDB supports collections that either have a finite size (in bytes or in number of stored documents) or support the automatic expiration handling but not both!

SEE ALSO

CHI, CHI::Driver::Development, MongoDB

AUTHOR

Heiko Jansen <hjansen@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Heiko Jansen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm CHI::Driver::MongoDB

perl -MCPAN -e shell
install CHI::Driver::MongoDB