BSON::DBRef(3pm)

💖 BSON::DBRef 💖

okay so bestie, welcome to the BSON::DBRef page — it's part of the User Contributed Perl Documentation, and it's literally the whole vibe for wrapping MongoDB DBRefs in BSON. sit down, grab a boba, let's go 🧋✨

---

✨ VERSION ✨

version v1.12.2 — yeah she's on v1.12.2, iconic, no notes 💅

---

🦋 SYNOPSIS 🦋

the way you summon her:

use BSON::Types ':all';

my $dbref = bson_dbref( $oid, $collection_name );

that's it. that's the whole ritual. 🎀

---

🌸 DESCRIPTION 🌸

so this module hands you a BSON type wrapper for MongoDB Database References — you can peep the official docs over at http://docs.mongodb.org/manual/reference/database-references/ if you want the lore.

a DBRef is a special document format that points at another document in the database. and like — important — DBRefs are NOT the same as foreign keys. they do not give you any referential integrity, no constraint checking, nothing. zero. so a DBRef can absolutely point at a document that no longer exists. or one that <em>never</em> existed. it's giving "ghosted" 😭

and here's the tea: use of DBRefs is discouraged, so this module only exists for backwards compatibility. what you actually want are "Manual references" (https://docs.mongodb.com/manual/reference/database-references/#document-references) whenever you need to reference other documents. periodt. 👑

---

💅 ATTRIBUTES 💅

🍓 id

Required. this is the "_id" value of the document you're referencing. and heads up: if that "_id" is an ObjectID, then bestie you must use a BSON::OID object. no shortcuts. 🙈

🧚 ref

Required. the name of the collection where the referenced document lives. you can hand her either a MongoDB::Collection object or a plain string with the collection name. if it's an object, she'll coerce it to string form. slay ✨

fun fact: you can also pass this in the constructor as '$ref'.

💜 db

Optional. the database where the referenced document lives. again, either a MongoDB::Database object or a string with the database name — object gets coerced to string form.

but ngl, not all other language drivers support the $db field, so using this field is not recommended. just putting that out there 🫶

you can also pass this in the constructor as '$db'.

🌈 extra

Optional. a hash reference of extra fields in the DBRef document. not all MongoDB drivers support this feature and you should not rely on it. this attribute literally exists for one reason only: so DBRefs generated by drivers that do allow extra fields will round-trip correctly. that's it.

🚨 USE OF THIS FIELD FOR NEW DBREFS IS NOT RECOMMENDED. 🚨 like, at all. don't.

---

🔥 METHODS 🔥

⭐ TO_JSON

so if the "BSON_EXTJSON" option is true, this returns a hashref compatible with MongoDB's extended JSON format (https://github.com/mongodb/specifications/blob/master/source/extended-json.rst), and it represents it as a document like this:

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

and if the "BSON_EXTJSON" option is false? an error is thrown, because this value literally cannot be represented in JSON any other way. it's giving "no thoughts, head empty" but for JSON 😭

---

👑 AUTHORS 👑

the legends behind this:

• 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

---

and that's the whole page, bestie!! 🦋 this was written for perl v5.30.3 back on 2020-08-14 — yeah she's a little vintage but she still serves 💖 mwah, go forth and reference responsibly (or don't, apparently, since DBRefs are discouraged 😭) 🫶✨