vibe.db.mongo.mongo source code

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 }