| Don Newton | 379ae25 | 2019-04-01 12:17:06 -0400 | [diff] [blame^] | 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("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 | // raw, err := cur.DecodeBytes() |
| 39 | // if err != nil { log.Fatal(err) } |
| 40 | // // do something with elem.... |
| 41 | // } |
| 42 | // if err := cur.Err(); err != nil { |
| 43 | // return err |
| 44 | // } |
| 45 | // |
| 46 | // Methods that only return a single document will return a *SingleResult, which works |
| 47 | // like a *sql.Row: |
| 48 | // |
| 49 | // result := struct{ |
| 50 | // Foo string |
| 51 | // Bar int32 |
| 52 | // }{} |
| 53 | // filter := bson.D{{"hello", "world"}} |
| 54 | // err := collection.FindOne(context.Background(), filter).Decode(&result) |
| 55 | // if err != nil { return err } |
| 56 | // // do something with result... |
| 57 | // |
| 58 | // Additional examples can be found under the examples directory in the driver's repository and |
| 59 | // on the MongoDB website. |
| 60 | package mongo |