1// Copyright (C) MongoDB, Inc. 2017-present.
2//
3// Licensed under the Apache License, Version 2.0 (the "License"); you may
4// not use this file except in compliance with the License. You may obtain
5// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
6
7// NOTE: This documentation should be kept in line with the Example* test functions.
8
9// Package mongo provides a MongoDB Driver API for Go.
10//
11// Basic usage of the driver starts with creating a Client from a connection
12// string. To do so, call the NewClient and Connect functions:
13//
14// 		client, err := NewClient(options.Client().ApplyURI("mongodb://foo:bar@localhost:27017"))
15// 		if err != nil { return err }
16// 		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
17// 		defer cancel()
18// 		err = client.Connect(ctx)
19// 		if err != nil { return err }
20//
21// This will create a new client and start monitoring the MongoDB server on localhost.
22// The Database and Collection types can be used to access the database:
23//
24//    collection := client.Database("baz").Collection("qux")
25//
26// A Collection can be used to query the database or insert documents:
27//
28//    res, err := collection.InsertOne(context.Background(), bson.M{"hello": "world"})
29//    if err != nil { return err }
30//    id := res.InsertedID
31//
32// Several methods return a cursor, which can be used like this:
33//
34//    cur, err := collection.Find(context.Background(), bson.D{})
35//    if err != nil { log.Fatal(err) }
36//    defer cur.Close(context.Background())
37//    for cur.Next(context.Background()) {
38//      // To decode into a struct, use cursor.Decode()
39//      result := struct{
40//        Foo string
41//        Bar int32
42//      }{}
43//      err := cur.Decode(&result)
44//      if err != nil { log.Fatal(err) }
45//      // do something with result...
46//
47//      // To get the raw bson bytes use cursor.Current
48//      raw := cur.Current
49//      // do something with raw...
50//    }
51//    if err := cur.Err(); err != nil {
52//      return err
53//    }
54//
55// Methods that only return a single document will return a *SingleResult, which works
56// like a *sql.Row:
57//
58//    result := struct{
59//      Foo string
60//      Bar int32
61//    }{}
62//    filter := bson.D{{"hello", "world"}}
63//    err := collection.FindOne(context.Background(), filter).Decode(&result)
64//    if err != nil { return err }
65//    // do something with result...
66//
67// All Client, Collection, and Database methods that take parameters of type interface{}
68// will return ErrNilDocument if nil is passed in for an interface{}.
69//
70// Additional examples can be found under the examples directory in the driver's repository and
71// on the MongoDB website.
72//
73// Potential DNS Issues
74//
75// Building with Go 1.11+ and using connection strings with the "mongodb+srv"[1] scheme is
76// incompatible with some DNS servers in the wild due to the change introduced in
77// https://github.com/golang/go/issues/10622. If you receive an error with the message "cannot
78// unmarshal DNS message" while running an operation, we suggest you use a different DNS server.
79//
80// Client Side Encryption
81//
82// Client-side encryption is a new feature in MongoDB 4.2 that allows specific data fields to be encrypted. Using this
83// feature requires specifying the "cse" build tag during compilation.
84//
85// Note: Auto encryption is an enterprise-only feature.
86//
87// The libmongocrypt C library is required when using client-side encryption. To install libmongocrypt, follow the
88// instructions for your operating system:
89//
90// 1. Linux: follow the instructions listed at
91// https://github.com/mongodb/libmongocrypt#installing-libmongocrypt-from-distribution-packages to install the correct
92// deb/rpm package.
93//
94// 2. Mac: Follow the instructions listed at https://github.com/mongodb/libmongocrypt#installing-libmongocrypt-on-macos
95// to install packages via brew and compile the libmongocrypt source code.
96//
97// 3. Windows:
98//    mkdir -p c:/libmongocrypt/bin
99//    mkdir -p c:/libmongocrypt/include
100//
101//    // Run the curl command in an empty directory as it will create new directories when unpacked.
102//    curl https://s3.amazonaws.com/mciuploads/libmongocrypt/windows/latest_release/libmongocrypt.tar.gz --output libmongocrypt.tar.gz
103//    tar -xvzf libmongocrypt.tar.gz
104//
105//    cp ./bin/mongocrypt.dll c:/libmongocrypt/bin
106//    cp ./include/mongocrypt/*.h c:/libmongocrypt/include
107//    export PATH=$PATH:/cygdrive/c/libmongocrypt/bin
108//
109// libmongocrypt communicates with the mongocryptd process for automatic encryption. This process can be started manually
110// or auto-spawned by the driver itself. To enable auto-spawning, ensure the process binary is on the PATH. To start it
111// manually, use AutoEncryptionOptions:
112//
113//    aeo := options.AutoEncryption()
114//    mongocryptdOpts := map[string]interface{}{
115//        "mongocryptdBypassSpawn": true,
116//    }
117//    aeo.SetExtraOptions(mongocryptdOpts)
118// To specify a process URI for mongocryptd, the "mongocryptdURI" option can be passed in the ExtraOptions map as well.
119// See the ClientSideEncryption and ClientSideEncryptionCreateKey examples below for code samples about using this
120// feature.
121//
122// [1] See https://docs.mongodb.com/manual/reference/connection-string/#dns-seedlist-connection-format
123package mongo
124