1MongoDB::Database(3)  User Contributed Perl Documentation MongoDB::Database(3)
2
3
4

NAME

6       MongoDB::Database - A MongoDB Database
7

VERSION

9       version v2.2.2
10

SYNOPSIS

12           # get a Database object via MongoDB::MongoClient
13           my $db   = $client->get_database("foo");
14
15           # get a Collection via the Database object
16           my $coll = $db->get_collection("people");
17
18           # run a command on a database
19           my $res = $db->run_command([ismaster => 1]);
20

DESCRIPTION

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
26       Generally, you never construct one of these directly with "new".
27       Instead, you call "get_database" on a MongoDB::MongoClient object.
28

USAGE

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
34       To catch and handle errors, the Try::Tiny and Safe::Isa modules are
35       recommended:
36
37           use Try::Tiny;
38           use Safe::Isa; # provides $_isa
39
40           try {
41               $db->run_command( @command )
42           }
43           catch {
44               if ( $_->$_isa("MongoDB::DuplicateKeyError" ) {
45                   ...
46               }
47               else {
48                   ...
49               }
50           };
51
52       To retry failures automatically, consider using Try::Tiny::Retry.
53

ATTRIBUTES

55   name
56       The name of the database.
57
58   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
65   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
70   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
75       By default it will be inherited from a MongoDB::MongoClient object.
76
77   max_time_ms
78       Specifies the maximum amount of time in milliseconds that the server
79       should use for working on a query.
80
81       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
84   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

METHODS

91   client
92           $client = $db->client;
93
94       Returns the MongoDB::MongoClient object associated with this object.
95
96   list_collections
97           $result = $coll->list_collections( $filter );
98           $result = $coll->list_collections( $filter, $options );
99
100       Returns a MongoDB::QueryResult object to iterate over collection
101       description documents.  These will contain "name" and "options" keys
102       like so:
103
104           use boolean;
105
106           {
107               name => "my_capped_collection",
108               options => {
109                   capped => true,
110                   size => 10485760,
111               }
112           },
113
114       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
120       A hash reference of options may be provided. Valid keys include:
121
122       •   "batchSize" – the number of documents to return per batch.
123
124       •   "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
128       •   "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
132       •   "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
136       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
139   collection_names
140           my @collections = $database->collection_names;
141           my @collections = $database->collection_names( $filter );
142           my @collections = $database->collection_names( $filter, $options );
143
144       Returns the list of collections in this database.
145
146       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
152       A hashref of options may also be provided.
153
154       Valid options include:
155
156       •   "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
160       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
164   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
169       Returns a MongoDB::Collection for the given collection name within this
170       database.
171
172       It takes an optional hash reference of options that are passed to the
173       MongoDB::Collection constructor.
174
175       The "coll" method is an alias for "get_collection".
176
177   get_gridfsbucket, gfs
178           my $grid = $database->get_gridfsbucket;
179           my $grid = $database->get_gridfsbucket($options);
180           my $grid = $database->gfs($options);
181
182       This method returns a MongoDB::GridFSBucket object for storing and
183       retrieving files from the database.
184
185       It takes an optional hash reference of options that are passed to the
186       MongoDB::GridFSBucket constructor.
187
188       See MongoDB::GridFSBucket for more information.
189
190       The "gfs" method is an alias for "get_gridfsbucket".
191
192   drop
193           $database->drop;
194
195       Deletes the database.
196
197       A hashref of options may also be provided.
198
199       Valid options include:
200
201       •   "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
205   run_command
206           my $output = $database->run_command([ some_command => 1 ]);
207
208           my $output = $database->run_command(
209               [ some_command => 1 ],
210               { mode => 'secondaryPreferred' }
211           );
212
213           my $output = $database->run_command(
214               [ some_command => 1 ],
215               $read_preference,
216               $options
217           );
218
219       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
225       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
230       A hashref of options may also be provided.
231
232       Valid options include:
233
234       •   "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
238       It returns the output of the command (a hash reference) on success or
239       throws a MongoDB::DatabaseError exception if the command fails.
240
241       For a list of possible database commands, run:
242
243           my $commands = $db->run_command([listCommands => 1]);
244
245       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
249   aggregate
250       Runs a query using the MongoDB 3.6+ aggregation framework and returns a
251       MongoDB::QueryResult object.
252
253       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
257       The server supports several collection-less aggregation source stages
258       like $currentOp and $listLocalSessions.
259
260           $result = $database->aggregate( [
261               {
262                   "\$currentOp" => {
263                       allUsers => true,
264                   },
265               },
266           ] );
267
268       See Aggregation <http://docs.mongodb.org/manual/aggregation/> in the
269       MongoDB manual for more information on how to construct aggregation
270       queries.
271
272   watch
273       Watches for changes on this database.
274
275       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
280           my $stream = $db->watch();
281           my $stream = $db->watch( \@pipeline );
282           my $stream = $db->watch( \@pipeline, \%options );
283
284           while (1) {
285
286               # 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
293       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
297       See "watch" in MongoDB::Collection for details on usage and available
298       options.
299

AUTHORS

301       •   David Golden <david@mongodb.com>
302
303       •   Rassi <rassi@mongodb.com>
304
305       •   Mike Friedman <friedo@friedo.com>
306
307       •   Kristina Chodorow <k.chodorow@gmail.com>
308
309       •   Florian Ragwitz <rafl@debian.org>
310
312       This software is Copyright (c) 2020 by MongoDB, Inc.
313
314       This is free software, licensed under:
315
316         The Apache License, Version 2.0, January 2004
317
318
319
320perl v5.36.0                      2023-01-20              MongoDB::Database(3)
Impressum