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 exectly 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 	Copyright: © 2012-2013 RejectedSoftware e.K.
14 	License: Subject to the terms of the MIT license, as written in the included LICENSE.txt file.
15 	Authors: Sönke Ludwig
16 */
17 module vibe.db.mongo.mongo;
18 
19 public import vibe.db.mongo.client;
20 public import vibe.db.mongo.settings;
21 
22 import std.algorithm;
23 
24 @safe:
25 
26 
27 /**
28 	Connects to a MongoDB instance.
29 
30 	If the host/port form is used, default settings will be used, which enable
31 	safe updates, but no fsync. By specifying a URL instead, it is possible to
32 	fully customize the settings. See
33 	$(LINK http://www.mongodb.org/display/DOCS/Connections) for the complete set
34 	of options. Note that 'sslverifycertificate' is only present in some client
35 	bindings, including here.
36 
37 	Note that the returned MongoClient uses a vibe.core.connectionpool.ConnectionPool
38 	internally to create and reuse connections as necessary. Thus, the
39 	MongoClient instance can - and should - be shared among all fibers in a
40 	thread by storing in in a thread local variable.
41 
42 	Authentication:
43 		Authenticated connections are supported by using a URL connection string
44 		such as "mongodb://user:password@host". SCRAM-SHA-1 is used by default.
45 
46 	Examples:
47 		---
48 		// connecting with default settings:
49 		auto client = connectMongoDB("127.0.0.1");
50 		auto users = client.getCollection("users");
51 		users.insert(Bson("peter"));
52 		---
53 
54 		---
55 		// connecting using the URL form with custom settings
56 		auto client = connectMongoDB("mongodb://localhost/?slaveOk=true");
57 		---
58 
59 		---
60 		// connecting with SSL encryption enabled and verification off
61 		auto client = connectMongoDB("mongodb://localhost/?ssl=true&sslverifycertificate=false");
62 		---
63 
64 	Params:
65 		host = Specifies the host name or IP address of the MongoDB server.
66 		port = Can be used to specify the port of the MongoDB server if different from the default one.
67 		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.
68 		settings = An object containing the full set of possible configuration options.
69 
70 	Returns:
71 		A new MongoClient instance that can be used to access the database.
72 
73  	Throws:
74  		Throws an exception if a mongodb:// URL is given and the URL cannot be parsed.
75  		An exception will not be thrown if called with a hostname and port.
76 */
77 MongoClient connectMongoDB(string host, ushort port)
78 {
79 	assert(!host.startsWith("mongodb://"));
80 	return new MongoClient(host, port);
81 }
82 /// ditto
83 MongoClient connectMongoDB(string host_or_url)
84 {
85 	/* If this looks like a URL try to parse it that way. */
86 	if(host_or_url.startsWith("mongodb://")){
87 		return new MongoClient(host_or_url);
88 	} else {
89 		return new MongoClient(host_or_url, MongoClientSettings.defaultPort);
90 	}
91 }
92 /// ditto
93 MongoClient connectMongoDB(MongoClientSettings settings)
94 {
95 	return new MongoClient(settings);
96 }