.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MongoDB::DBRef 3pm"
.TH MongoDB::DBRef 3pm "2014-10-09" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::DBRef \- Native DBRef support
.SH "VERSION"
.IX Header "VERSION"
version v0.705.0.0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    my $dbref = MongoDB::DBRef\->new( db => \*(Aqmy_db\*(Aq, ref => \*(Aqmy_collection\*(Aq, id => 123 );
\&    $coll\->insert( { foo => \*(Aqbar\*(Aq, other_doc => $dbref } );
\&
\&    my $other_doc = $coll\->find_one( { foo => \*(Aqbar\*(Aq } )\->{other_doc}\->fetch;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides support for database references (DBRefs) in the Perl 
MongoDB driver. A DBRef is a special embedded document which points to 
another document in the database. DBRefs are not the same as foreign keys
and do not provide any referential integrity or constraint checking. For example,
a DBRef may point to a document that no longer exists (or never existed.)
.SH "NAME"
MongoDB::DBRef \- A MongoDB database reference
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "db"
.IX Subsection "db"
Required. The database in which the referenced document lives. Either a MongoDB::Database
object or a string containing the database name. The object will be coerced to string form.
.SS "ref"
.IX Subsection "ref"
Required. The collection in which the referenced document lives. Either a MongoDB::Collection
object or a string containing the collection name. The object will be coerced to string form.
.SS "id"
.IX Subsection "id"
Required. The \f(CW\*(C`_id\*(C'\fR value of the referenced document. If the 
\&\f(CW\*(C`_id\*(C'\fR is an ObjectID, then you must use a MongoDB::OID object.
.SS "client"
.IX Subsection "client"
Optional. A MongoDB::MongoClient object to be used to fetch the referenced document
from the database. You must supply this attribute if you want to use the \f(CW\*(C`fetch\*(C'\fR method.
.PP
When you retrieve a document from MongoDB, any DBRefs will automatically be inflated
into \f(CW\*(C`MongoDB::DBRef\*(C'\fR objects with the \f(CW\*(C`client\*(C'\fR attribute automatically populated.
.PP
It is not necessary to specify a \f(CW\*(C`client\*(C'\fR if you are just making DBRefs to insert
in the database as part of a larger document.
.SS "verify_db"
.IX Subsection "verify_db"
Optional. Check that the referenced database exists before trying to fetch a document
from it. The default is \f(CW1\fR. Set to \f(CW0\fR to disable checking.
.SS "verify_coll"
.IX Subsection "verify_coll"
Optional. Check that the referenced collection exists before trying to fetch a document
from it. The default is \f(CW1\fR. Set to \f(CW0\fR to disable checking.
.SH "METHODS"
.IX Header "METHODS"
.SS "fetch"
.IX Subsection "fetch"
Retrieve the referenced document from the database. If the document does not exist, you'll
get back \f(CW\*(C`undef\*(C'\fR. You must populate the \f(CW\*(C`client\*(C'\fR attribute of the DBRef object in order
to use this method. If there's no \f(CW\*(C`client\*(C'\fR, \f(CW\*(C`fetch\*(C'\fR will throw a fatal error.
.PP
If \f(CW\*(C`verify_db\*(C'\fR or <verify_coll> are on, \f(CW\*(C`fetch\*(C'\fR will throw a fatal error if the 
database or collection concerned does not exist.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david.golden@mongodb.org>
.IP "\(bu" 4
Mike Friedman <friedo@mongodb.com>
.IP "\(bu" 4
Kristina Chodorow <kristina@mongodb.org>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2014 by MongoDB, Inc..
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve