1 /**
2 MongoDB and MongoCollection classes and connections.
3
4 Implementation_Note:
5
6 The MongoDB driver implementation here is missing a number of API functions
7 known from the JavaScript driver, but these can usually be implemented in
8 terms of MongoDatabase.runCommand or MongoCollection.find. Since the
9 official documentation is lacking in some places, it may be necessary to use
10 a network sniffer to monitor what exactly needs to be sent. MongoDB has a
11 dedicated utility for this called $(LINK2 http://docs.mongodb.org/manual/reference/program/mongosniff/ mongosniff).
12
13 As of 2014 there is proper documentation on $(LINK https://github.com/mongodb/specifications).
14
15 Copyright: © 2012-2013 Sönke Ludwig
16 License: Subject to the terms of the MIT license, as written in the included LICENSE.txt file.
17 Authors: Sönke Ludwig
18 */
19 module vibe.db.mongo.mongo;
20
21 public import vibe.db.mongo.client;
22 public import vibe.db.mongo.settings;
23
24 import std.algorithm;
25
26 @safe:
27
28
29 /**
30 Connects to a MongoDB instance.
31
32 If the host/port form is used, default settings will be used, which enable
33 safe updates, but no fsync. By specifying a URL instead, it is possible to
34 fully customize the settings. See
35 $(LINK http://www.mongodb.org/display/DOCS/Connections) for the complete set
36 of options. Note that 'sslverifycertificate' is only present in some client
37 bindings, including here.
38
39 Note that the returned MongoClient uses a vibe.core.connectionpool.ConnectionPool
40 internally to create and reuse connections as necessary. Thus, the
41 MongoClient instance can - and should - be shared among all fibers in a
42 thread by storing in in a thread local variable.
43
44 Authentication:
45 Authenticated connections are supported by using a URL connection string
46 such as "mongodb://user:password@host". SCRAM-SHA-1 is used by default.
47
48 Examples:
49 ---
50 // connecting with default settings:
51 auto client = connectMongoDB("127.0.0.1");
52 auto users = client.getCollection("users");
53 users.insert(Bson("peter"));
54 ---
55
56 ---
57 // connecting using the URL form with custom settings
58 auto client = connectMongoDB("mongodb://localhost/?slaveOk=true");
59 ---
60
61 ---
62 // connecting with SSL encryption enabled and verification off
63 auto client = connectMongoDB("mongodb://localhost/?ssl=true&sslverifycertificate=false");
64 ---
65
66 Params:
67 host = Specifies the host name or IP address of the MongoDB server.
68 port = Can be used to specify the port of the MongoDB server if different from the default one.
69 host_or_url = Can either be a host name, in which case the default port will be used, or a URL with the mongodb:// scheme.
70 settings = An object containing the full set of possible configuration options.
71
72 Returns:
73 A new MongoClient instance that can be used to access the database.
74
75 Throws:
76 Throws an exception if a mongodb:// URL is given and the URL cannot be parsed.
77 An exception will not be thrown if called with a hostname and port.
78 */
79 MongoClient connectMongoDB(string host, ushort port)
80 {
81 assert(!host.startsWith("mongodb://"));
82 return new MongoClient(host, port);
83 }
84 /// ditto
85 MongoClient connectMongoDB(string host_or_url)
86 {
87 /* If this looks like a URL try to parse it that way. */
88 if(host_or_url.startsWith("mongodb://")){
89 return new MongoClient(host_or_url);
90 } else {
91 return new MongoClient(host_or_url, MongoClientSettings.defaultPort);
92 }
93 }
94 /// ditto
95 MongoClient connectMongoDB(MongoClientSettings settings)
96 {
97 return new MongoClient(settings);
98 }