Skip to content

Commit 299661e

Browse files
patrickfreedpatrickfreed
authored
RUST-249 Add readme (#98)
1 parent d66a2dc commit 299661e

File tree

1 file changed

+176
-0
lines changed

1 file changed

+176
-0
lines changed

‎README.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# MongoDB Rust Driver
2+
[![Crates.io](https://img.shields.io/crates/v/mongodb.svg)](https://crates.io/crates/mongodb) [![docs.rs](https://docs.rs/mongodb/badge.svg)](https://docs.rs/mongodb) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
3+
4+
This repository contains the officially supported MongoDB Rust driver, a client side library that can be used to interact with MongoDB deployments in Rust applications. It depends on the community-supported [`bson`](https://docs.rs/bson) library for BSON support.
5+
6+
## Index
7+
- [Installation](#Installation)
8+
- [Example Usage](#example-usage)
9+
- [Connecting to a MongoDB deployment](#connecting-to-a-mongodb-deployment)
10+
- [Getting a handle to a database](#getting-a-handle-to-a-database)
11+
- [Inserting documents into a collection](#inserting-documents-into-a-collection)
12+
- [Finding documents in a collection](#finding-documents-in-a-collection)
13+
- [Bug Reporting / Feature Requests](#bug-reporting--feature-requests)
14+
- [Contributing](#contributing)
15+
- [Running the tests](#running-the-tests)
16+
- [Continuous Integration](#continuous-integration)
17+
- [License](#license)
18+
19+
## Installation
20+
### Requirements
21+
- Rust 1.39+
22+
- MongoDB 3.6+
23+
24+
### Importing
25+
The driver is available on [crates.io](https://crates.io/crates/mongodb). To use the driver in your application, simply add it to your project's `Cargo.toml`. You will also want to add [`bson`](https://docs.rs/bson) as well.
26+
```toml
27+
[dependencies]
28+
mongodb = "0.9.0"
29+
bson = "0.14.0"
30+
```
31+
32+
## Example Usage
33+
Below are simple examples of using the driver. For more specific examples and the API reference, see the driver's [docs.rs page](https://docs.rs/mongodb).
34+
### Connecting to a MongoDB deployment
35+
```rust
36+
use mongodb::{Client, options::ClientOptions};
37+
```
38+
```rust
39+
// Parse a connection string into an options struct.
40+
let mut client_options = ClientOptions::parse("mongodb://localhost:27017")?;
41+
42+
// Manually set an option.
43+
client_options.app_name = Some("My App".to_string());
44+
45+
// Get a handle to the deployment.
46+
let client = Client::with_options(client_options)?;
47+
48+
// List the names of the databases in that deployment.
49+
for db_name in client.list_database_names(None)? {
50+
println!("{}", db_name);
51+
}
52+
```
53+
### Getting a handle to a database
54+
```rust
55+
// Get a handle to a database.
56+
let db = client.database("mydb");
57+
58+
// List the names of the collections in that database.
59+
for collection_name in db.list_collection_names(None)? {
60+
println!("{}", collection_name);
61+
}
62+
```
63+
### Inserting documents into a collection
64+
```rust
65+
use bson::{doc, bson};
66+
```
67+
```rust
68+
// Get a handle to a collection in the database.
69+
let collection = db.collection("books");
70+
71+
let docs = vec![
72+
doc! { "title": "1984", "author": "George Orwell" },
73+
doc! { "title": "Animal Farm", "author": "George Orwell" },
74+
doc! { "title": "The Great Gatsby", "author": "F. Scott Fitzgerald" },
75+
];
76+
77+
// Insert some documents into the "mydb.books" collection.
78+
collection.insert_many(docs, None)?;
79+
```
80+
### Finding documents in a collection
81+
```rust
82+
use bson::{doc, bson};
83+
use mongodb::options::FindOptions;
84+
```
85+
```rust
86+
// Query the documents in the collection with a filter and an option.
87+
let filter = doc! { "author": "George Orwell" };
88+
let find_options = FindOptions::builder().sort(doc! { "title": 1 }).build();
89+
let cursor = collection.find(filter, find_options)?;
90+
91+
// Iterate over the results of the cursor.
92+
for result in cursor {
93+
match result {
94+
Ok(document) => {
95+
if let Some(title) = document.get("title").and_then(Bson::as_str) {
96+
println!("title: {}", title);
97+
} else {
98+
println!("no title found");
99+
}
100+
}
101+
Err(e) => return Err(e.into()),
102+
}
103+
}
104+
```
105+
106+
## Bug Reporting / Feature Requests
107+
To file a bug report or submit a feature request, please open a ticket on our [Jira project](https://jira.mongodb.org/browse/RUST):
108+
- Create an account and login at [jira.mongodb.org](https://jira.mongodb.org)
109+
- Navigate to the RUST project at [jira.mongorb.org/browse/RUST](https://jira.mongodb.org/browse/RUST)
110+
- Click **Create Issue** - If the ticket you are filing is a bug report, please include as much detail as possible about the issue and how to reproduce it.
111+
112+
Before filing a ticket, please use the search functionality of Jira to see if a similar issue has already been filed.
113+
114+
## Contributing
115+
116+
We encourage and would happily accept contributions in the form of GitHub pull requests. Before opening one, be sure to run the tests locally; check out the [testing section](#running-the-tests) for information on how to do that. Once you open a pull request, your branch will be run against the same testing matrix that we use for our [continuous integration](#continuous-integration) system, so it is usually sufficient to only run the integration tests locally against a standalone. Remember to always run the linter tests before opening a pull request.
117+
118+
## Running the tests
119+
### Integration and unit tests
120+
In order to run the tests (which are mostly integration tests), you must have access to a MongoDB deployment. You may specify a [MongoDB connection string](https://docs.mongodb.com/manual/reference/connection-string/) in the `MONGODB_URI` environment variable, and the the tests will use it to connect to the deployment. If `MONGODB_URI` is unset, the tests will attempt to connect to a local deployment on port 27017.
121+
122+
**Note:** The integration tests will clear out the databases/collections they need to use, but they do not clean up after themselves.
123+
124+
To actually run the tests, you can use `cargo` like you would in any other crate:
125+
```bash
126+
cargo test --verbose # runs against localhost:27017
127+
export MONGODB_URI="mongodb://localhost:123"
128+
cargo test --verbose # runs against localhost:123
129+
```
130+
131+
#### Auth tests
132+
The authentication tests will only be included in the test run if certain requirements are met:
133+
- The deployment must have `--auth` enabled
134+
- Credentials must be specified in `MONGODB_URI`
135+
- The credentials specified in `MONGODB_URI` must be valid and have root privledges on the deployment
136+
```bash
137+
export MONGODB_URI="mongodb://user:pass@localhost:27017"
138+
cargo test --verbose # auth tests included
139+
```
140+
#### Topology-specific tests
141+
Certain tests will only be run against certain topologies. To ensure that the entire test suite is run, make sure to run the tests separately against standalone, replicated, and sharded deployments.
142+
```bash
143+
export MONGODB_URI="mongodb://my-standalone-host:20717" # mongod running on 27017
144+
cargo test --verbose
145+
export MONGODB_URI="mongodb://localhost:27018,localhost:27019,localhost:27020/?replSet=repl"
146+
cargo test --verbose
147+
export MONGODB_URI="mongodb://localhost:27021" # mongos running on 27021
148+
cargo test --verbose
149+
```
150+
151+
#### Run the tests with TLS/SSL
152+
To run the tests with TLS/SSL enabled, you must enable it on the deployment and in `MONGODB_URI`.
153+
```bash
154+
export MONGODB_URI="mongodb://localhost:27017/?tls=true&tlsCertificateKeyFile=cert.pem&tlsCAFile=ca.pem"
155+
cargo test --verbose
156+
```
157+
**Note:** When you open a pull request, your code will be run against a comprehensive testing matrix, so it is usually not necessary run the integration tests against all combinations of topology/auth/TLS locally.
158+
159+
### Linter Tests
160+
Our linter tests use the nightly version of `rustfmt` to verify that the source is formatted properly and the stable version of `clippy` to statically detect any common mistakes.
161+
You can use `rustup` to install them both:
162+
```bash
163+
rustup component add clippy --toolchain stable
164+
rustup component add rustfmt --toolchain nightly
165+
```
166+
To run the linter tests, run the `check-clippy.sh` and `check-rustfmt.sh` scripts in the `.evergreen` directory:
167+
```bash
168+
bash .evergreen/check-clippy.sh && bash .evergreen/check-rustfmt.sh
169+
```
170+
171+
## Continuous Integration
172+
Commits to master are run automatically on [evergreen](https://evergreen.mongodb.com/waterfall/mongo-rust-driver-stable).
173+
174+
## License
175+
176+
This project is licensed under the [Apache License 2.0](https://github.com/10gen/mongo-rust-driver/blob/master/LICENSE).

0 commit comments

Comments
 (0)