Skip to content

Commit 192f9b4

Browse files
abr-egnabr-egn
authored
RUST-1244 Merge crate doc and readme (#1081)
1 parent c3e2bd5 commit 192f9b4

File tree

2 files changed

+20
-494
lines changed

2 files changed

+20
-494
lines changed

‎README.md

Lines changed: 19 additions & 225 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,9 @@
11
# 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 uses the [`bson`](https://docs.rs/bson/latest) crate for BSON support. The driver contains a fully async API that requires [`tokio`](https://docs.rs/tokio). The driver also has a sync API that may be enabled via feature flags.
5-
6-
For more detailed documentation, see https://www.mongodb.com/docs/drivers/rust/current/. This documentation includes detailed content about features, runnable examples, troubleshooting resources, and more.
7-
8-
## Index
9-
- [Installation](#installation)
10-
- [Requirements](#requirements)
11-
- [Supported platforms](#supported-platforms)
12-
- [Importing](#importing)
13-
- [Configuring the async runtime](#configuring-the-async-runtime)
14-
- [Enabling the sync API](#enabling-the-sync-api)
15-
- [All feature flags](#all-feature-flags)
16-
- [Example Usage](#example-usage)
17-
- [Using the async API](#using-the-async-api)
18-
- [Connecting to a MongoDB deployment](#connecting-to-a-mongodb-deployment)
19-
- [Getting a handle to a database](#getting-a-handle-to-a-database)
20-
- [Inserting documents into a collection](#inserting-documents-into-a-collection)
21-
- [Finding documents in a collection](#finding-documents-in-a-collection)
22-
- [Using the sync API](#using-the-sync-api)
23-
- [Web Framework Examples](#web-framework-examples)
24-
- [Note on connecting to Atlas deployments](#note-on-connecting-to-atlas-deployments)
25-
- [Windows DNS note](#windows-dns-note)
26-
- [Warning about timeouts / cancellation](#warning-about-timeouts--cancellation)
27-
- [Bug Reporting / Feature Requests](#bug-reporting--feature-requests)
28-
- [Contributing](#contributing)
29-
- [Running the tests](#running-the-tests)
30-
- [Continuous Integration](#continuous-integration)
31-
- [Minimum supported Rust version (MSRV) policy](#minimum-supported-rust-version-msrv-policy)
32-
- [License](#license)
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)](https://github.com/mongodb/mongo-rust-driver/blob/main/LICENSE)
3+
4+
This is the officially supported MongoDB Rust driver, a client side library that can be used to interact with MongoDB deployments in Rust applications. It uses the [`bson`](https://docs.rs/bson/latest) crate for BSON support. The driver contains a fully async API that requires [`tokio`](https://docs.rs/tokio). The driver also has a sync API that may be enabled via feature flags.
5+
6+
For more details, including features, runnable examples, troubleshooting resources, and more, please see the [official documentation](https://www.mongodb.com/docs/drivers/rust/current/).
337

348
## Installation
359
### Requirements
@@ -60,171 +34,18 @@ features = ["sync"]
6034

6135
### All Feature Flags
6236

63-
| Feature | Description | Extra dependencies | Default |
64-
|:---------------------|:--------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------|:--------|
65-
| `sync` | Expose the synchronous API (`mongodb::sync`). | n/a | no |
66-
| `aws-auth` | Enable support for the MONGODB-AWS authentication mechanism. | `reqwest` | no |
67-
| `zlib-compression` | Enable support for compressing messages with [`zlib`](https://zlib.net/) | `flate2` | no |
68-
| `zstd-compression` | Enable support for compressing messages with [`zstd`](http://facebook.github.io/zstd/). | `zstd` | no |
69-
| `snappy-compression` | Enable support for compressing messages with [`snappy`](http://google.github.io/snappy/) | `snap` | no |
70-
| `openssl-tls` | Switch TLS connection handling to use ['openssl'](https://docs.rs/openssl/0.10.38/). | `openssl` | no |
71-
72-
## Example Usage
73-
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/latest).
74-
75-
### Using the async API
76-
#### Connecting to a MongoDB deployment
77-
```rust
78-
use mongodb::{Client, options::ClientOptions};
79-
```
80-
```rust
81-
// Parse a connection string into an options struct.
82-
let mut client_options = ClientOptions::parse("mongodb://localhost:27017").await?;
83-
84-
// Manually set an option.
85-
client_options.app_name = Some("My App".to_string());
86-
87-
// Get a handle to the deployment.
88-
let client = Client::with_options(client_options)?;
89-
90-
// List the names of the databases in that deployment.
91-
for db_name in client.list_database_names(None, None).await? {
92-
println!("{}", db_name);
93-
}
94-
```
95-
#### Getting a handle to a database
96-
```rust
97-
// Get a handle to a database.
98-
let db = client.database("mydb");
99-
100-
// List the names of the collections in that database.
101-
for collection_name in db.list_collection_names(None).await? {
102-
println!("{}", collection_name);
103-
}
104-
```
105-
#### Inserting documents into a collection
106-
```rust
107-
use mongodb::bson::{doc, Document};
108-
```
109-
```rust
110-
// Get a handle to a collection in the database.
111-
let collection = db.collection::<Document>("books");
112-
113-
let docs = vec![
114-
doc! { "title": "1984", "author": "George Orwell" },
115-
doc! { "title": "Animal Farm", "author": "George Orwell" },
116-
doc! { "title": "The Great Gatsby", "author": "F. Scott Fitzgerald" },
117-
];
118-
119-
// Insert some documents into the "mydb.books" collection.
120-
collection.insert_many(docs, None).await?;
121-
```
122-
123-
A [`Collection`](https://docs.rs/mongodb/latest/mongodb/struct.Collection.html) can be parameterized with any type that implements the `Serialize` and `Deserialize` traits from the [`serde`](https://serde.rs/) crate, not just `Document`:
124-
125-
``` toml
126-
# In Cargo.toml, add the following dependency.
127-
serde = { version = "1.0", features = ["derive"] }
128-
```
129-
130-
``` rust
131-
use serde::{Deserialize, Serialize};
132-
133-
#[derive(Debug, Serialize, Deserialize)]
134-
struct Book {
135-
title: String,
136-
author: String,
137-
}
138-
```
139-
140-
``` rust
141-
// Get a handle to a collection of `Book`.
142-
let typed_collection = db.collection::<Book>("books");
143-
144-
let books = vec![
145-
Book {
146-
title: "The Grapes of Wrath".to_string(),
147-
author: "John Steinbeck".to_string(),
148-
},
149-
Book {
150-
title: "To Kill a Mockingbird".to_string(),
151-
author: "Harper Lee".to_string(),
152-
},
153-
];
154-
155-
// Insert the books into "mydb.books" collection, no manual conversion to BSON necessary.
156-
typed_collection.insert_many(books, None).await?;
157-
```
158-
159-
#### Finding documents in a collection
160-
Results from queries are generally returned via [`Cursor`](https://docs.rs/mongodb/latest/mongodb/struct.Cursor.html), a struct which streams the results back from the server as requested. The [`Cursor`](https://docs.rs/mongodb/latest/mongodb/struct.Cursor.html) type implements the [`Stream`](https://docs.rs/futures/latest/futures/stream/index.html) trait from the [`futures`](https://crates.io/crates/futures) crate, and in order to access its streaming functionality you need to import at least one of the [`StreamExt`](https://docs.rs/futures/latest/futures/stream/trait.StreamExt.html) or [`TryStreamExt`](https://docs.rs/futures/latest/futures/stream/trait.TryStreamExt.html) traits.
161-
162-
``` toml
163-
# In Cargo.toml, add the following dependency.
164-
futures = "0.3"
165-
```
166-
```rust
167-
// This trait is required to use `try_next()` on the cursor
168-
use futures::stream::TryStreamExt;
169-
use mongodb::{bson::doc, options::FindOptions};
170-
```
171-
```rust
172-
// Query the books in the collection with a filter and an option.
173-
let filter = doc! { "author": "George Orwell" };
174-
let find_options = FindOptions::builder().sort(doc! { "title": 1 }).build();
175-
let mut cursor = typed_collection.find(filter, find_options).await?;
176-
177-
// Iterate over the results of the cursor.
178-
while let Some(book) = cursor.try_next().await? {
179-
println!("title: {}", book.title);
180-
}
181-
```
182-
183-
### Using the sync API
184-
The driver also provides a blocking sync API. See the [Installation](#enabling-the-sync-api) section for instructions on how to enable it.
185-
186-
The various sync-specific types are found in the `mongodb::sync` submodule rather than in the crate's top level like in the async API. The sync API calls through to the async API internally though, so it looks and behaves similarly to it.
187-
```rust
188-
use mongodb::{
189-
bson::doc,
190-
sync::Client,
191-
};
192-
use serde::{Deserialize, Serialize};
193-
194-
#[derive(Debug, Serialize, Deserialize)]
195-
struct Book {
196-
title: String,
197-
author: String,
198-
}
199-
```
200-
```rust
201-
let client = Client::with_uri_str("mongodb://localhost:27017")?;
202-
let database = client.database("mydb");
203-
let collection = database.collection::<Book>("books");
204-
205-
let docs = vec![
206-
Book {
207-
title: "1984".to_string(),
208-
author: "George Orwell".to_string(),
209-
},
210-
Book {
211-
title: "Animal Farm".to_string(),
212-
author: "George Orwell".to_string(),
213-
},
214-
Book {
215-
title: "The Great Gatsby".to_string(),
216-
author: "F. Scott Fitzgerald".to_string(),
217-
},
218-
];
219-
220-
// Insert some books into the "mydb.books" collection.
221-
collection.insert_many(docs, None)?;
222-
223-
let cursor = collection.find(doc! { "author": "George Orwell" }, None)?;
224-
for result in cursor {
225-
println!("title: {}", result?.title);
226-
}
227-
```
37+
| Feature | Description |
38+
|:-----------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
39+
| `dns-resolver` | Enable DNS resolution to allow `mongodb+srv` URI handling. **Enabled by default.** |
40+
| `rustls-tls` | Use [`rustls`](https://docs.rs/rustls/latest/rustls/) for TLS connection handling. **Enabled by default.** |
41+
| `openssl-tls` | Use [`openssl`](https://docs.rs/openssl/latest/openssl/) for TLS connection handling. |
42+
| `sync` | Expose the synchronous API (`mongodb::sync`). |
43+
| `aws-auth` | Enable support for the MONGODB-AWS authentication mechanism. |
44+
| `zlib-compression` | Enable support for compressing messages with [`zlib`](https://zlib.net/) |
45+
| `zstd-compression` | Enable support for compressing messages with [`zstd`](http://facebook.github.io/zstd/). |
46+
| `snappy-compression` | Enable support for compressing messages with [`snappy`](http://google.github.io/snappy/) |
47+
| `in-use-encryption-unstable` | Enable support for client-side field level encryption and queryable encryption. This API is unstable and may be subject to breaking changes in minor releases. |
48+
| `tracing-unstable` | Enable support for emitting [`tracing`](https://docs.rs/tracing/latest/tracing/) events. This API is unstable and may be subject to breaking changes in minor releases. |
22849

22950
## Web Framework Examples
23051
### Actix
@@ -239,24 +60,7 @@ In order to connect to a pre-4.2 Atlas instance that's M2 or bigger, the `openss
23960

24061
## Windows DNS note
24162

242-
On Windows, there is a known issue in the `trust-dns-resolver` crate, which the driver uses to perform DNS lookups, that causes severe performance degradation in resolvers that use the system configuration. Since the driver uses the system configuration by default, users are recommended to specify an alternate resolver configuration on Windows until that issue is resolved. This only has an effect when connecting to deployments using a `mongodb+srv` connection string.
243-
244-
e.g.
245-
246-
``` rust
247-
use mongodb::{
248-
options::{ClientOptions, ResolverConfig},
249-
Client,
250-
};
251-
```
252-
``` rust
253-
let options = ClientOptions::parse_with_resolver_config(
254-
"mongodb+srv://my.host.com",
255-
ResolverConfig::cloudflare(),
256-
)
257-
.await?;
258-
let client = Client::with_options(options)?;
259-
```
63+
On Windows, there is a known issue in the `trust-dns-resolver` crate, which the driver uses to perform DNS lookups, that causes severe performance degradation in resolvers that use the system configuration. Since the driver uses the system configuration by default, users are recommended to specify an alternate resolver configuration on Windows (e.g. `ResolverConfig::cloudflare()`) until that issue is resolved. This only has an effect when connecting to deployments using a `mongodb+srv` connection string.
26064

26165
## Warning about timeouts / cancellation
26266

@@ -272,16 +76,6 @@ one option is to spawn tasks and time out on their
27276
the driver's futures directly. This will ensure the driver's futures will always be completely polled
27377
while also allowing the application to continue in the event of a timeout.
27478

275-
e.g.
276-
``` rust
277-
let collection = client.database("ok").collection("ok");
278-
let handle = tokio::task::spawn(async move {
279-
collection.insert_one(doc! { "x": 1 }, None).await
280-
});
281-
282-
tokio::time::timeout(Duration::from_secs(5), handle).await???;
283-
```
284-
28579
## Bug Reporting / Feature Requests
28680
To file a bug report or submit a feature request, please open a ticket on our [Jira project](https://jira.mongodb.org/browse/RUST):
28781
- Create an account and login at [jira.mongodb.org](https://jira.mongodb.org)
@@ -361,4 +155,4 @@ it will only happen in a minor or major version release.
361155

362156
This project is licensed under the [Apache License 2.0](https://github.com/10gen/mongo-rust-driver/blob/main/LICENSE).
363157

364-
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
158+
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (<http://www.openssl.org/>).

0 commit comments

Comments
 (0)