MongoD...dStream(3pm)

🦋 NAME

MongoDB::GridFSBucket::UploadStream — the file-handle abstraction for uploading, bestie. That's it, that's the whole job. (It lives over in the User Contributed Perl Documentation wing of the 3pm section, if you were wondering 💅)

---

✨ VERSION

version v2.2.2 🎀

---

📜 SYNOPSIS

# OO API
$stream  = $bucket->open_upload_stream("foo.txt");
$stream->print( $data );
$stream->close;
$id = $stream->id;

# Tied handle API
$fh = $stream->fh
print {$fh} $data;
close $fh;

---

💖 DESCRIPTION

So this class is your little file abstraction for uploading. You can stream data at an object of this class two ways — either through methods, or through a tied-handle interface. Pick your fighter, both slay 💅

Writes get buffered and sent in chunk-size units. Then the moment you call close, all the data gets flushed to the GridFS Bucket and boom — the newly created file is visible. iconic behavior honestly 🌈

---

🌸 ATTRIBUTES

🧚 chunk_size_bytes

The number of bytes per chunk. Defaults to the chunk_size_bytes of the originating bucket object — it inherits, as a treat 🫶

This gets stored in the chunkSize field of the file document on a successful upload.

🦋 filename

The filename to store the file under. And like — note this — filenames are NOT necessarily unique. Don't come for me, that's just how it is fr fr.

This gets stored in the filename field of the file document on a successful upload.

🎀 metadata

An optional hashref for storing arbitrary metadata about the file. Whatever you want, go off.

If defined, this gets stored in the metadata field of the file document on a successful upload.

💜 content_type (DEPRECATED)

An optional MIME type. This field should only be used for backwards compatibility with older GridFS implementations. New applications should store the content type in the metadata hash if needed. Like, we're not mad, we're just saying 👀

If defined, this gets stored in the contentType field of the file document on a successful upload.

💜 aliases (DEPRECATED)

An optional array of aliases. Same deal — only for backwards compatibility with older GridFS implementations. New applications should store aliases in the metadata hash if needed.

If defined, this gets stored in the aliases field of the file document on a successful upload.

---

🔥 METHODS

⭐ id

$id = $stream->id;

The id of the file created by the stream. It gets stored in the _id field of the file document on a successful upload. Some upload methods require specifying an id at upload time, so heads up on that. Defaults to a newly-generated BSON::OID or BSON codec specific equivalent — it'll make one for you automatically, no stress 💅

🫶 fh

my $fh = $stream->fh;
print $fh, 'test data...';
close $fh

Returns a new file handle tied to this instance of UploadStream, and you can operate on it with the built-in functions print, printf, syswrite, fileno and close. Cute little delegation moment ✨

Important notes, bestie, listen up:

• Allowing one of these tied filehandles to fall out of scope will NOT cause close to be called. This is due to the way tied file handles are implemented in Perl. Sorry 😭 For close to be called implicitly, all tied filehandles and the original object must go out of scope. Everyone out the group chat, then it fires.
• Each file handle retrieved this way is tied back to the same object, so calling close on multiple tied file handles and/or the original object will have the same effect as calling close on the original object multiple times. Idempotent-ish, we love that 🎀

💀 abort

$stream->abort;

Aborts the upload by deleting any chunks already uploaded to the database and closing the stream. It's giving "never happened" energy. No cap, that data is gone.

👑 close

$file_doc = $stream->close;

Closes the stream and flushes any remaining data to the database. Once this is done, a file document is created in the GridFS bucket, which makes the uploaded file visible in subsequent queries or downloads. main character moment: the file EXISTS now 🌈

On success, the file document hash reference is returned as a convenience.

Important notes:

• Calling close will also cause any tied file handles created for the stream to also close.
• close will be automatically called when a stream object is destroyed. When called this way, any errors thrown will not halt execution. Silent-ish, but fine.
• Calling close repeatedly will warn. So like... don't spam it 🙈

🍓 fileno

if ( $stream->fileno ) { ... }

Works like the builtin fileno, but it returns -1 if the stream is open and undef if closed. Yes, that's a weird little dance, but that's the spec 💅

🌸 print

$stream->print(@data);

Works like the builtin print.

💖 printf

$stream->printf($format, @data);

Works like the builtin printf.

🦋 syswrite

$stream->syswrite($buffer);
$stream->syswrite($buffer, $length);
$stream->syswrite($buffer, $length, $offset);

Works like the builtin syswrite.

---

🙈 CAVEATS

🧚 Character encodings

All the writer methods (e.g. print, printf, etc.) send a binary representation of the string input provided (or generated in the case of printf). Unless you explicitly encode it to bytes, this will be the internal representation of the string in the Perl interpreter. Here's the breakdown:

• If you have ASCII characters, it will already be bytes.
• If you have any characters above 0xff, it will be UTF-8 encoded codepoints.
• If you have characters between 0x80 and 0xff and not higher, you might have either bytes or UTF-8 internally. mystery box, unfortunately 😭

You are strongly encouraged to do your own character encoding with the Encode module or equivalent and upload only bytes to GridFS. Do this. Please. For me 🫶

---

💜 AUTHORS

• David Golden <david@mongodb.com>
• Rassi <rassi@mongodb.com>
• Mike Friedman <friedo@friedo.com>
• Kristina Chodorow <k.chodorow@gmail.com>
• Florian Ragwitz <rafl@debian.org>

Shoutout to the whole dev team, actual legends 💅

---

🌈 COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

And that's the page, bestie 🎀 this was perl v5.40.1, dated 2025-04-03, straight from the MongoD...dStream(3pm) corner of the docs. Go upload something iconic 💖✨