The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
NAME
    Meerkat - Manage MongoDB documents as Moose objects

VERSION
    version 0.008

SYNOPSIS
        use Meerkat;

        my $meerkat = Meerkat->new(
            model_namespace => "My::Model",
            database_name   => "test",
            client_options  => {
                host => "mongodb://example.net:27017",
                username => "willywonka",
                password => "ilovechocolate",
            },
        );

        my $person = $meerkat->collection("Person"); # My::Model::Person

        # create an object and insert it into the MongoDB collection
        my $obj = $person->create( name => 'John' );

        # modify an object atomically
        $obj->update_inc ( likes => 1               ); # increment a counter
        $obj->update_push( tags => [qw/hot trendy/] ); # push to an array

        # find a single object
        my $copy = $person->find_one( { name => 'John' } );

        # get a Meerkat::Cursor for multiple objects
        my $cursor = $person->find( { tags => 'hot' } );

DESCRIPTION
    Meerkat lets you manage MongoDB documents as Moose objects. Your objects
    represent projections of the document state maintained in the database.

    When you create an object, a corresponding document is inserted into the
    database. This lets you use familiar Moose attribute builders and
    validation to construct your documents.

    Because state rests in the database, you don't modify your object with
    accessors. Instead, you issue MongoDB update directives that change the
    state of the document atomically in the database and synchronize the
    object state with the result.

    Meerkat is not an object-relational mapper. It does not offer or manage
    relations or support embedded objects.

    Meerkat is fork-safe. It maintains a cache of MongoDB::Collection
    objects that gets cleared when a fork occurs. Meerkat will transparently
    reconnect from child processes.

USAGE
    Meerkat divides functional responsibilities across six classes:

    *   Meerkat — associates a Perl namespace to a MongoDB connection and
        database

    *   Meerkat::Collection — associates a Perl class within a namespace to
        a MongoDB collection

    *   Meerkat::Role::Document — enhances a Moose object with Meerkat
        methods and metadata

    *   Meerkat::Cursor — proxies a result cursor and inflates documents
        into objects

    *   Meerkat::DateTime — proxies an epoch value with lazy DateTime
        inflation

    *   Meerkat::Types — provides type definition and coercion for
        Meerkat::DateTime

    You define your documents as Moose classes that consume
    Meerkat::Role::Document. This gives them several support methods to
    update, synchronize or remove documents from the database.

    In order to create objects from your model or retrieve them from the
    database, you must first create a Meerkat object that manages your
    connection to the MongoDB database. This is where you specify your
    database host, authentication options and so on.

    You then get a Meerkat::Collection object from the Meerkat object, which
    holds an association between the model class and a collection in the
    database. This class does all the real work of creating, searching,
    updating, or deleting from the underlying MongoDB collection.

    If you use the Meerkat::Collection object to run a query that could have
    multiple results, it returns a Meerkat::Cursor object that wraps the
    MongoDB::Cursor and inflates results into objects from your model.

    Meerkat::DateTime lazily inflates floating point epoch seconds into
    DateTime objects. It's conceptually similar to DateTime::Tiny, but based
    on the epoch seconds returned by the MongoDB client for its internal
    date value representation.

    See Meerkat::Tutorial and Meerkat::Cookbook for more.

ATTRIBUTES
  model_namespace (required)
    A perl module namespace that will be prepended to class names requested
    via the "collection" method. If "model_namespace" is "My::Model", then
    "$meerkat->collection("Baz")" will load and associate the
    "My::Model::Baz" class in the returned collection object.

  database_name (required)
    A MongoDB database name used to store all collections generated via the
    Meerkat object and its collection factories. Unless a "db_name" is
    provided in the "client_options" attribute, this database will be the
    default for authentication.

  client_options
    A hash reference of MongoDB::MongoClient options that will be passed to
    its "connect" method.

    Note: The "dt_type" will be forced to "undef" so that the MongoDB client
    will provide time values as epoch seconds. See the Meerkat::Cookbook for
    more on dealing with dates and times.

  collection_namespace
    A perl module namespace that will be be used to search for custom
    collection classes. The "collection_namespace" will be prepended to
    class names requested via the "collection" method. If
    "collection_namespace" is "My::Collection", then
    "$meerkat->collection("Baz")" will load and use "My::Collection::Baz"
    for constructing a collection object. If "collection_namespace" is not
    provided or if no class is found under the namespace (or if it fails to
    load), then collection objects will be constructed using
    Meerkat::Collection.

METHODS
  new
        my $meerkat = Meerkat->new(
            model_namespace => "My::Model",
            database_name   => "test",
            client_options  => {
                host => "mongodb://example.net:27017",
                username => "willywonka",
                password => "ilovechocolate",
            },
        );

    Generates and returns a new Meerkat object. The "model_namespace" and
    "database_name" attributes are required.

  collection
        my $person = $meerkat->collection("Person"); # My::Model::Person

    Returns a Meerkat::Collection factory object or possibly a subclass if a
    "collection_namespace" attribute has been provided. A single parameter
    is required and is used as the suffix of a class name provided to the
    Meerkat::Collection "class" attribute.

  mongo_collection
        my $coll = $meerkat->mongo_collection("My_Model_Person");

    Returns a raw MongoDB::Collection object from the associated database.
    This is used internally by Meerkat::Collection and is not intended for
    general use.

EXCEPTION HANDLING
    Unless otherwise specified, all methods throw exceptions on error either
    directly or by not catching errors thrown by MongoDB classes.

WARNINGS AND CAVEATS
    Your objects are subject to the same limitations as any MongoDB
    document.

    Most significantly, because MongoDB uses the dot character as a field
    separator in queries (e.g. "foo.bar"), you may not have the dot
    character as the key of any hash in your document.

        # this will fail
        $person->create( emails => { "dagolden@example.com" => "primary" } );

    Be particularly careful with email addresses and URLs.

RATIONALE
    Working with raw MongoDB documents as pure data structures is a bit
    painful and annoying. There are some existing libraries that attempt to
    make life easier, but I found them deficient in one way or another.

    I tried Mongoose first. I had problems when trying to work with multiple
    databases and doing any sort of authentication and it doesn't seem very
    actively maintained. MongoDBX::Class (discussed next) has some
    additional Mongoose critiques. Mongoose is about 1000 lines of code
    split across fourteen modules.

    Next I looked at MongoDBx::Class. In many ways, it works much more like
    the basic MongoDB classes. What stopped me cold was that it requires
    inserts to be done with a raw data structure. That means no defaults,
    validation, lazy building and other stuff that I like about Moose. It
    does offer some support making updates easier, and I've adapted that
    approach for Meerkat. MongoDBx::Class is about 800 lines of code split
    across fifteen modules.

    Both offer a relational model. While a noble goal, I'm suspicious of
    applying relational data models to a document-oriented database like
    MongoDB that doesn't have transactions. MongoDB offers atomic *document*
    updates, so I decided to focus Meerkat on that alone.

    Mongoose and MongoDBx also support defining embedded documents. I
    haven't decided if that's necessary — and it adds quite a bit of
    complexity — so I haven't implemented it in Meerkat.

    There are other MongoDB-based modules that I found and dismissed:

    *   KiokuDB::Backend::MongoDB, but see the Mongoose critique of it

    *   MongoDB::Simple, which is too simple to do what I want

    *   MongoDBx::Tiny, which hurts my eyes

    *   MongoDBI, "scheduled for a rewrite in the coming months" for the
        last year

    Conceptually, Meerkat is a bit similar to Mongoose, but less ambitious.
    (A meerkat is a smaller member of the mongoose family, after all.) It
    adopts some of the features I liked from MongoDBx::Class.

    Meerkat focuses on:

    *   Multiple database support

    *   Easy configuration of database connections

    *   Fork safety

    *   Simplicity and (to the extent possible) Moosey-ness

    *   A document-centric data model

    Because it is less ambitious, Meerkat is smaller and less complex,
    currently about 480 lines of code split across six modules.

SEE ALSO
  Meerkat documentation
    *   Meerkat::Tutorial

    *   Meerkat::Cookbook

  Other MongoDB resources
    *   MongoDB::MongoClient

    *   MongoDBx::Class

    *   Mongoose

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/dagolden/Meerkat/issues>. You will be notified
    automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/dagolden/Meerkat>

      git clone https://github.com/dagolden/Meerkat.git

AUTHOR
    David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2013 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004