1MongoDB::Database(3) User Contributed Perl Documentation MongoDB::Database(3)
2
6 MongoDB::Database - A MongoDB Database
7
9 version v2.2.1
10
12 # get a Database object via MongoDB::MongoClient
13 my $db = $client->get_database("foo");
14 # get a Collection via the Database object
16 my $coll = $db->get_collection("people");
17 # run a command on a database
19 my $res = $db->run_command([ismaster => 1]);
20
22 This class models a MongoDB database. Use it to construct
23 MongoDB::Collection objects. It also provides the "run_command" method
24 and some convenience methods that use it.
25 Generally, you never construct one of these directly with "new".
27 Instead, you call "get_database" on a MongoDB::MongoClient object.
28
30 Error handling
31 Unless otherwise explicitly documented, all methods throw exceptions if
32 an error occurs. The error types are documented in MongoDB::Error.
33 To catch and handle errors, the Try::Tiny and Safe::Isa modules are
35 recommended:
36 use Try::Tiny;
38 use Safe::Isa; # provides $_isa
39 try {
41 $db->run_command( @command )
42 }
43 catch {
44 if ( $_->$_isa("MongoDB::DuplicateKeyError" ) {
45 ...
46 }
47 else {
48 ...
49 }
50 };
51 To retry failures automatically, consider using Try::Tiny::Retry.
53
55 name
56 The name of the database.
57 read_preference
59 A MongoDB::ReadPreference object. It may be initialized with a string
60 corresponding to one of the valid read preference modes or a hash
61 reference that will be coerced into a new MongoDB::ReadPreference
62 object. By default it will be inherited from a MongoDB::MongoClient
63 object.
64 write_concern
66 A MongoDB::WriteConcern object. It may be initialized with a hash
67 reference that will be coerced into a new MongoDB::WriteConcern object.
68 By default it will be inherited from a MongoDB::MongoClient object.
69 read_concern
71 A MongoDB::ReadConcern object. May be initialized with a hash
72 reference or a string that will be coerced into the level of read
73 concern.
74 By default it will be inherited from a MongoDB::MongoClient object.
76 max_time_ms
78 Specifies the maximum amount of time in milliseconds that the server
79 should use for working on a query.
80 Note: this will only be used for server versions 2.6 or greater, as
82 that was when the $maxTimeMS meta-operator was introduced.
83 bson_codec
85 An object that provides the "encode_one" and "decode_one" methods, such
86 as from BSON. It may be initialized with a hash reference that will be
87 coerced into a new BSON object. By default it will be inherited from a
88 MongoDB::MongoClient object.
89
91 client
92 $client = $db->client;
93 Returns the MongoDB::MongoClient object associated with this object.
95 list_collections
97 $result = $coll->list_collections( $filter );
98 $result = $coll->list_collections( $filter, $options );
99 Returns a MongoDB::QueryResult object to iterate over collection
101 description documents. These will contain "name" and "options" keys
102 like so:
103 use boolean;
105 {
107 name => "my_capped_collection",
108 options => {
109 capped => true,
110 size => 10485760,
111 }
112 },
113 An optional filter document may be provided, which cause only
115 collection description documents matching a filter expression to be
116 returned. See the listCollections command documentation
117 <http://docs.mongodb.org/manual/reference/command/listCollections/> for
118 more details on filtering for specific collections.
119 A hash reference of options may be provided. Valid keys include:
121 · "batchSize" – the number of documents to return per batch.
123 · "maxTimeMS" – the maximum amount of time in milliseconds to allow
125 the command to run. (Note, this will be ignored for servers before
126 version 2.6.)
127 · "nameOnly" - query and return names of the collections only.
129 Defaults to false. (Note, this will be ignored for servers before
130 version 4.0)
131 · "session" - the session to use for these operations. If not
133 supplied, will use an implicit session. For more information see
134 MongoDB::ClientSession
135 NOTE: When using "nameOnly", the filter query must be empty or must
137 only query the "name" field or else no documents will be found.
138 collection_names
140 my @collections = $database->collection_names;
141 my @collections = $database->collection_names( $filter );
142 my @collections = $database->collection_names( $filter, $options );
143 Returns the list of collections in this database.
145 An optional filter document may be provided, which cause only
147 collection description documents matching a filter expression to be
148 returned. See the listCollections command documentation
149 <http://docs.mongodb.org/manual/reference/command/listCollections/> for
150 more details on filtering for specific collections.
151 A hashref of options may also be provided.
153 Valid options include:
155 · "session" - the session to use for these operations. If not
157 supplied, will use an implicit session. For more information see
158 MongoDB::ClientSession
159 Warning: if the number of collections is very large, this may return a
161 very large result. Either pass an appropriate filter, or use
162 "list_collections" to iterate over collections instead.
163 get_collection, coll
165 my $collection = $database->get_collection('foo');
166 my $collection = $database->get_collection('foo', $options);
167 my $collection = $database->coll('foo', $options);
168 Returns a MongoDB::Collection for the given collection name within this
170 database.
171 It takes an optional hash reference of options that are passed to the
173 MongoDB::Collection constructor.
174 The "coll" method is an alias for "get_collection".
176 get_gridfsbucket, gfs
178 my $grid = $database->get_gridfsbucket;
179 my $grid = $database->get_gridfsbucket($options);
180 my $grid = $database->gfs($options);
181 This method returns a MongoDB::GridFSBucket object for storing and
183 retrieving files from the database.
184 It takes an optional hash reference of options that are passed to the
186 MongoDB::GridFSBucket constructor.
187 See MongoDB::GridFSBucket for more information.
189 The "gfs" method is an alias for "get_gridfsbucket".
191 drop
193 $database->drop;
194 Deletes the database.
196 A hashref of options may also be provided.
198 Valid options include:
200 · "session" - the session to use for these operations. If not
202 supplied, will use an implicit session. For more information see
203 MongoDB::ClientSession
204 run_command
206 my $output = $database->run_command([ some_command => 1 ]);
207 my $output = $database->run_command(
209 [ some_command => 1 ],
210 { mode => 'secondaryPreferred' }
211 );
212 my $output = $database->run_command(
214 [ some_command => 1 ],
215 $read_preference,
216 $options
217 );
218 This method runs a database command. The first argument must be a
220 document with the command and its arguments. It should be given as an
221 array reference of key-value pairs or a Tie::IxHash object with the
222 command name as the first key. An error will be thrown if the command
223 is not an ordered document.
224 By default, commands are run with a read preference of 'primary'. An
226 optional second argument may specify an alternative read preference.
227 If given, it must be a MongoDB::ReadPreference object or a hash
228 reference that can be used to construct one.
229 A hashref of options may also be provided.
231 Valid options include:
233 · "session" - the session to use for these operations. If not
235 supplied, will use an implicit session. For more information see
236 MongoDB::ClientSession
237 It returns the output of the command (a hash reference) on success or
239 throws a MongoDB::DatabaseError exception if the command fails.
240 For a list of possible database commands, run:
242 my $commands = $db->run_command([listCommands => 1]);
244 There are a few examples of database commands in the "DATABASE
246 COMMANDS" in MongoDB::Examples section. See also core documentation on
247 database commands: <http://dochub.mongodb.org/core/commands>.
248 aggregate
250 Runs a query using the MongoDB 3.6+ aggregation framework and returns a
251 MongoDB::QueryResult object.
252 The first argument must be an array-ref of aggregation pipeline
254 <http://docs.mongodb.org/manual/core/aggregation-pipeline/> documents.
255 Each pipeline document must be a hash reference.
256 The server supports several collection-less aggregation source stages
258 like $currentOp and $listLocalSessions.
259 $result = $database->aggregate( [
261 {
262 "\$currentOp" => {
263 allUsers => true,
264 },
265 },
266 ] );
267 See Aggregation <http://docs.mongodb.org/manual/aggregation/> in the
269 MongoDB manual for more information on how to construct aggregation
270 queries.
271 watch
273 Watches for changes on this database.
274 Perform an aggregation with an implicit initial $changeStream stage and
276 returns a MongoDB::ChangeStream result which can be used to iterate
277 over the changes in the database. This functionality is available since
278 MongoDB 4.0.
279 my $stream = $db->watch();
281 my $stream = $db->watch( \@pipeline );
282 my $stream = $db->watch( \@pipeline, \%options );
283 while (1) {
285 # This inner loop will only run until no more changes are
287 # available.
288 while (my $change = $stream->next) {
289 # process $change
290 }
291 }
292 The returned stream will not block forever waiting for changes. If you
294 want to respond to changes over a longer time use "maxAwaitTimeMS" and
295 regularly call "next" in a loop.
296 See "watch" in MongoDB::Collection for details on usage and available
298 options.
299
301 · David Golden <david@mongodb.com>
302 · Rassi <rassi@mongodb.com>
304 · Mike Friedman <friedo@friedo.com>
306 · Kristina Chodorow <k.chodorow@gmail.com>
308 · Florian Ragwitz <rafl@debian.org>
310
312 This software is Copyright (c) 2019 by MongoDB, Inc.
313 This is free software, licensed under:
315 The Apache License, Version 2.0, January 2004
317perl v5.30.1 2020-01-30 MongoDB::Database(3)