---
name: "BSON::DBRef"
section: "3pm"
platform: "linux"
package: "libbson-perl"
version: "1.12.2-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/BSON::DBRef"
---

# BSON::DBRef(3pm)

BSON type wrapper for MongoDB DBRefs

## NAME

BSON::DBRef - BSON type wrapper for MongoDB DBRefs

## VERSION

version v1.12.2

## SYNOPSIS

```
    use BSON::Types ':all';
    my $dbref = bson_dbref( $oid, $collection_name );
```

## DESCRIPTION

This module provides a BSON type wrapper for MongoDB Database References \<http://docs.mongodb.org/manual/reference/database-references/\>.

A DBRef is a special document format which references 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.)

Use of DBRefs is discouraged, so this module is provided for backwards compatibility.  "Manual references" \<https://docs.mongodb.com/manual/reference/database-references/#document-references\> are preferred when there is a need to reference other documents.

## ATTRIBUTES

### id

Required. The `"_id"` value of the referenced document. If the `"_id"` is an ObjectID, then you must use a BSON::OID object.

### ref

Required. The name of 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.

This may also be specified in the constructor as `'$ref'`.

### 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.

Not all other language drivers support the `$db` field, so using this field is not recommended.

This may also be specified in the constructor as `'$db'`.

### extra

Optional.  A hash reference of additional fields in the DBRef document. Not all MongoDB drivers support this feature and you **should not** rely on it.  This attribute exists solely to ensure DBRefs generated by drivers that do allow extra fields will round-trip correctly.

**USE OF THIS FIELD FOR NEW DBREFS IS NOT RECOMMENDED.**

## METHODS

### TO\_JSON

If the `"BSON_EXTJSON"` option is true, returns a hashref compatible with MongoDB's extended JSON \<https://github.com/mongodb/specifications/blob/master/source/extended-json.rst\> format, which represents it as a document as follows:

```
    { "$ref": "<collection name>", "$id": "<id>" }
```

If the `"BSON_EXTJSON"` option is false, an error is thrown, as this value can't otherwise be represented in JSON.

## AUTHORS

- •

  David Golden \<david@mongodb.com\>

- •

  Stefan G. \<minimalist@lavabit.com\>

## COPYRIGHT AND LICENSE

This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.

This is free software, licensed under:

```
  The Apache License, Version 2.0, January 2004
```