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