view release on metacpan or  search on metacpan

lib/Couchbase/Bucket.pm  view on Meta::CPAN

        printf("Got value: %s\n", $doc->value);
    }


The C<get_and_touch> variant will also update (or clear) the expiration time of
the item. See L<"Document Expiration"> for more details:

    my $doc = Couchbase::Document->new("id", { expiry => 300 });
    $cb->get_and_touch($doc); # Expires in 5 minutes


=head3 fetch($id)

This is a convenience method which will create a new document with the given C<id>
and perform a C<get> on it. It will then return the resulting document.

    my $doc = $cb->fetch("id_to_retrieve");


=head3 insert($doc)

=head3 replace($doc, $options)

=head3 upsert($doc, $options)


    my $doc = Couchbase::Document->new(
        "mutation_method_names",
        [ "insert", "replace", "upsert"],
        { expiry => 3600 }
    );

    # Store a new item into the cluster, failing if it exists:
    $cb->insert($doc);

    # Unconditionally overwrite the value:
    $cb->upsert($doc);

    # Only replace an existing value
    $cb->replace($doc);

    # Ignore any kind of race conditions:
    $cb->replace($doc, { ignore_cas => 1 });

    # Store the document, wait until it has been persisted
    # on at least 2 nodes
    $cb->replace($doc, { persist_to => 2 });


These three methods will set the value of the document on the server. C<insert>
will only succeed if the item does B<not> exist, C<replace> will only succeed if the
item B<already> exists, and C<upsert> will unconditionally write the new value
regardless of it existing or not.


=head4 Storage Format

By default, the document is serialized and stored as JSON. This allows proper
integration with other optional functionality of the cluster (such as views and
N1QL queries). You may also store items in other formats which may then be
transparently serialized and deserialized as needed.

To specify the storage format for a document, specify the `format` setting
in the L<Couchbase::Document> object, like so:

    use Couchbase::Document;
    my $doc = Couchbase::Document->new('foo', \1234, { format => COUCHBASE_FMT_STORABLE);


This version of the client uses so-called "Common Flags", allowing seamless integration
with Couchbase clients written in other languages.


=head4 Encoding Formats

Bear in mind that Perl's default encoding is I<Latin-1> and not I<UTF-8>. To
that effect, any input, unless indicated otherwise, is assumed to thus be
Latin-1. There are various ways to change the "type" of a string, the details
of which can be found within the L<utf8> and L<Encode> modules.

From the perspective of this module, any I<input> string which is marked
as being JSON or UTF8 will be marked as being UTF-8. This may mean some
smaller performance implications. If this is a concern, you can intercept
the JSON decoding function and handle the raw string there.


=head4 CAS Operations

To avoid race conditions when two applications attempt to write to the same document
Couchbase utilizes something called a I<CAS> value which represents the last known
state of the document. This I<CAS> value is modified each time a change is made to the
document, and is returned back to the client for each operation. If the C<$doc> item is
a document previously used for a successful C<get> or other operation, it will contain
the I<CAS>, and the client will send it back to the server. If the current I<CAS> of the
document on the server does not match the value embedded into the document the operation
will fail with the code C<COUCHBASE_KEY_EEXISTS>.

To always modify the value (ignoring whether the value may have been previously
modified by another application), set the C<ignore_cas> option to a true value in
the C<$options> hashref.


=head4 Durability Requirements

Mutation operations in couchbase are considered successful once they are stored
in the master node's cache for a given key. Sometimes extra redundancy and
reliability is required, where an application should only proceed once the data
has been replicated to a certain number of nodes and possibly persisted to their
disks. Use the C<persist_to> and C<replicate_to> options to specify the specific
durability requirements:

=over

=item C<persist_to>

Wait until the item has been persisted (written to non-volatile storage) of this
many nodes. A value of I<1> means the master node, where a value of 2 or higher
means the master node I<and> C<n-1> replica nodes.


=item C<replicate_to>