1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
|
// Copyright (C) MongoDB, Inc. 2017-present.
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may
// not use this file except in compliance with the License. You may obtain
// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
// NOTE: This documentation should be kept in line with the Example* test functions.
// Package mongo provides a MongoDB Driver API for Go.
//
// Basic usage of the driver starts with creating a Client from a connection
// string. To do so, call Connect:
//
// ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
// defer cancel()
// client, err := mongo.Connect(ctx, options.Client().ApplyURI("mongodb://foo:bar@localhost:27017"))
// if err != nil { return err }
//
// This will create a new client and start monitoring the MongoDB server on localhost.
// The Database and Collection types can be used to access the database:
//
// collection := client.Database("baz").Collection("qux")
//
// A Collection can be used to query the database or insert documents:
//
// res, err := collection.InsertOne(context.Background(), bson.M{"hello": "world"})
// if err != nil { return err }
// id := res.InsertedID
//
// Several methods return a cursor, which can be used like this:
//
// cur, err := collection.Find(context.Background(), bson.D{})
// if err != nil { log.Fatal(err) }
// defer cur.Close(context.Background())
// for cur.Next(context.Background()) {
// // To decode into a struct, use cursor.Decode()
// result := struct{
// Foo string
// Bar int32
// }{}
// err := cur.Decode(&result)
// if err != nil { log.Fatal(err) }
// // do something with result...
//
// // To get the raw bson bytes use cursor.Current
// raw := cur.Current
// // do something with raw...
// }
// if err := cur.Err(); err != nil {
// return err
// }
//
// Cursor.All will decode all of the returned elements at once:
//
// var results []struct{
// Foo string
// Bar int32
// }
// if err = cur.All(context.Background(), &results); err != nil {
// log.Fatal(err)
// }
// // do something with results...
//
// Methods that only return a single document will return a *SingleResult, which works
// like a *sql.Row:
//
// result := struct{
// Foo string
// Bar int32
// }{}
// filter := bson.D{{"hello", "world"}}
// err := collection.FindOne(context.Background(), filter).Decode(&result)
// if err != nil { return err }
// // do something with result...
//
// All Client, Collection, and Database methods that take parameters of type interface{}
// will return ErrNilDocument if nil is passed in for an interface{}.
//
// Additional examples can be found under the examples directory in the driver's repository and
// on the MongoDB website.
//
// # Error Handling
//
// Errors from the MongoDB server will implement the ServerError interface, which has functions to check for specific
// error codes, labels, and message substrings. These can be used to check for and handle specific errors. Some methods,
// like InsertMany and BulkWrite, can return an error representing multiple errors, and in those cases the ServerError
// functions will return true if any of the contained errors satisfy the check.
//
// There are also helper functions to check for certain specific types of errors:
//
// IsDuplicateKeyError(error)
// IsNetworkError(error)
// IsTimeout(error)
//
// # Potential DNS Issues
//
// Building with Go 1.11+ and using connection strings with the "mongodb+srv"[1] scheme is unfortunately
// incompatible with some DNS servers in the wild due to the change introduced in
// https://github.com/golang/go/issues/10622. You may receive an error with the message "cannot unmarshal DNS message"
// while running an operation when using DNS servers that non-compliantly compress SRV records. Old versions of kube-dns
// and the native DNS resolver (systemd-resolver) on Ubuntu 18.04 are known to be non-compliant in this manner. We suggest
// using a different DNS server (8.8.8.8 is the common default), and, if that's not possible, avoiding the "mongodb+srv"
// scheme.
//
// # Client Side Encryption
//
// Client-side encryption is a new feature in MongoDB 4.2 that allows specific data fields to be encrypted. Using this
// feature requires specifying the "cse" build tag during compilation:
//
// go build -tags cse
//
// Note: Auto encryption is an enterprise- and Atlas-only feature.
//
// The libmongocrypt C library is required when using client-side encryption. Specific versions of libmongocrypt
// are required for different versions of the Go Driver:
//
// - Go Driver v1.2.0 requires libmongocrypt v1.0.0 or higher
//
// - Go Driver v1.5.0 requires libmongocrypt v1.1.0 or higher
//
// - Go Driver v1.8.0 requires libmongocrypt v1.3.0 or higher
//
// - Go Driver v1.10.0 requires libmongocrypt v1.5.0 or higher.
// There is a severe bug when calling RewrapManyDataKey with libmongocrypt versions less than 1.5.2.
// This bug may result in data corruption.
// Please use libmongocrypt 1.5.2 or higher when calling RewrapManyDataKey.
//
// - Go Driver v1.12.0 requires libmongocrypt v1.8.0 or higher.
//
// To install libmongocrypt, follow the instructions for your
// operating system:
//
// 1. Linux: follow the instructions listed at
// https://github.com/mongodb/libmongocrypt#installing-libmongocrypt-from-distribution-packages to install the correct
// deb/rpm package.
//
// 2. Mac: Follow the instructions listed at https://github.com/mongodb/libmongocrypt#installing-libmongocrypt-on-macos
// to install packages via brew and compile the libmongocrypt source code.
//
// 3. Windows:
//
// mkdir -p c:/libmongocrypt/bin
// mkdir -p c:/libmongocrypt/include
//
// // Run the curl command in an empty directory as it will create new directories when unpacked.
// curl https://s3.amazonaws.com/mciuploads/libmongocrypt/windows/latest_release/libmongocrypt.tar.gz --output libmongocrypt.tar.gz
// tar -xvzf libmongocrypt.tar.gz
//
// cp ./bin/mongocrypt.dll c:/libmongocrypt/bin
// cp ./include/mongocrypt/*.h c:/libmongocrypt/include
// export PATH=$PATH:/cygdrive/c/libmongocrypt/bin
//
// libmongocrypt communicates with the mongocryptd process or mongo_crypt shared library for automatic encryption.
// See AutoEncryptionOpts.SetExtraOptions for options to configure use of mongocryptd or mongo_crypt.
//
// [1] See https://www.mongodb.com/docs/manual/reference/connection-string/#dns-seedlist-connection-format
package mongo
|