.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "MongoDB::DBRef 3pm"
.TH MongoDB::DBRef 3pm "2016-09-09" "perl v5.24.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 \- A MongoDB database reference
.SH "VERSION"
.IX Header "VERSION"
version v1.4.5
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    my $dbref = MongoDB::DBRef\->new(
\&        ref => \*(Aqmy_collection\*(Aq,
\&        id => 123
\&    );
\&
\&    $coll\->insert( { foo => \*(Aqbar\*(Aq, other_doc => $dbref } );
.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.)
.PP
Generally, these are not recommended and \*(L"manual references\*(R" are preferred.
.PP
See Database references <http://docs.mongodb.org/manual/reference/database-references/>
en the MongoDB manual for more information.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.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.
.PP
This may also be specified in the constructor as \f(CW\*(Aq$id\*(Aq\fR.
.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.
.PP
This may also be specified in the constructor as \f(CW\*(Aq$ref\*(Aq\fR.
.SS "db"
.IX Subsection "db"
Optional. 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.
.PP
Not all other language drivers support the \f(CW$db\fR field, so using this
field is not recommended.
.PP
This may also be specified in the constructor as \f(CW\*(Aq$db\*(Aq\fR.
.SS "extra"
.IX Subsection "extra"
Optional.  A hash reference of additional fields in the DBRef document.
Not all MongoDB drivers support this feature and you \fBshould not\fR rely on
it.  This attribute exists solely to ensure DBRefs generated by drivers that
do allow extra fields will round-trip correctly.
.PP
\&\fB\s-1USE OF THIS FIELD FOR NEW DBREFS IS NOT RECOMMENDED.\s0\fR
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2016 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve