man MongoDB::GridFS (3): A file storage utility

VERSION

version v1.2.3

SYNOPSIS

my $grid = $database->get_gridfs;
my $fh = IO::File->new("myfile", "r");
$grid->insert($fh, {"filename" => "mydbfile"});

DESCRIPTION

This class models a GridFS file store in a MongoDB database and provides an API for interacting with it.

Generally, you never construct one of these directly with "new". Instead, you call "get_gridfs" on a MongoDB::Database object.

USAGE

API

There are two interfaces for GridFS: a file-system/collection-like interface (insert, remove, drop, find_one) and a more general interface (get, put, delete). Their functionality is the almost identical (get, put and delete are always safe ops, insert, remove, and find_one are optionally safe), using one over the other is a matter of preference.

Error handling

Unless otherwise explicitly documented, all methods throw exceptions if an error occurs. The error types are documented in MongoDB::Error.

To catch and handle errors, the Try::Tiny and Safe::Isa modules are recommended:

    use Try::Tiny;
    use Safe::Isa; # provides $_isa
    try {
        $grid->get( $id )
    }
    catch {
        if ( $_->$_isa("MongoDB::TimeoutError" ) {
            ...
        }
        else {
            ...
        }
    };

To retry failures automatically, consider using Try::Tiny::Retry.

ATTRIBUTES

chunk_size

The number of bytes per chunk. Defaults to 261120 (255kb).

read_preference

A MongoDB::ReadPreference object. It may be initialized with a string corresponding to one of the valid read preference modes or a hash reference that will be coerced into a new MongoDB::ReadPreference object. By default it will be inherited from a MongoDB::Database object.

write_concern

A MongoDB::WriteConcern object. It may be initialized with a hash reference that will be coerced into a new MongoDB::WriteConcern object. By default it will be inherited from a MongoDB::Database object.

max_time_ms

Specifies the default maximum amount of time in milliseconds that the server should use for working on a query.

Note: this will only be used for server versions 2.6 or greater, as that was when the $maxTimeMS meta-operator was introduced.

bson_codec

An object that provides the "encode_one" and "decode_one" methods, such as from MongoDB::BSON. It may be initialized with a hash reference that will be coerced into a new MongoDB::BSON object. By default it will be inherited from a MongoDB::Database object.

prefix

The prefix used for the collections. Defaults to ``fs''.

METHODS

get

    $file = $grid->get($id);

Get a file from GridFS based on its _id. Returns a MongoDB::GridFS::File.

To retrieve a file based on metadata like "filename", use the ``find_one'' method instead.

put

    $id = $grid->put($fh, $metadata);
    $id = $grid->put($fh, {filename => "pic.jpg"});

Inserts a file into GridFS, adding a MongoDB::OID as the _id field if the field is not already defined. This is a wrapper for "MongoDB::GridFS::insert", see that method below for more information.

Returns the _id field.

delete

    $grid->delete($id)

Removes the file with the given _id. Will die if the remove is unsuccessful. Does not return anything on success.

find_one

    $file = $grid->find_one({"filename" => "foo.txt"});
    $file = $grid->find_one($criteria, $fields);

Returns a matching MongoDB::GridFS::File or undef.

remove

    $grid->remove({"filename" => "foo.txt"});
    $grid->remove({"filename" => "foo.txt"}, $options);

Cleanly removes files from the database. $options is a hash of options for the remove.

A hashref of options may be provided with the following keys:

"just_one": If true, only one file matching the criteria will be removed.
"safe": (DEPRECATED) If true, each remove will be checked for success and die on failure. Set the ``write_concern'' attribute instead.

This method doesn't return anything.

insert

    $id = $gridfs->insert($fh);
    $id = $gridfs->insert($fh, $metadata);
    $id = $gridfs->insert($fh, $metadata, $options);
    $id = $gridfs->insert($fh, {"content-type" => "text/html"});

Reads from a file handle into the database. Saves the file with the given metadata. The file handle must be readable.