Docs Menu
Docs Home
/ / /
Rust Driver
/

Databases and Collections

On this page

  • Overview
  • Access a Database
  • List Databases
  • Drop a Database
  • Access a Collection
  • Collection Parameterization
  • Create a Collection
  • List Collections
  • Drop a Collection
  • Additional Information

In this guide, you can learn how to use the Rust driver to access and manage MongoDB databases and collections.

MongoDB organizes data in a hierarchical structure. A MongoDB deployment contains one or more databases, and each database contains one or more collections. In each collection, MongoDB stores data as documents that contain field-and-value pairs.

To learn more about the document data format, see Documents in the Server manual.

You can access a database by retrieving a Database instance from your client. You can use a Database instance to perform database-level operations and access collections that the database contains.

Call one of the following methods on a Client instance to create a Database:

Tip

To specify the default database for your client, set the default_database field of your ClientOptions struct. If you do not set this field, the driver gets the default database from the defaultauthdb component of your connection string.

If you pass the name of a nonexistent database to the database() or database_with_options() methods, the driver still returns a Database instance. When you insert any data into collection in this database, the server creates it.

The following example uses the database() method to access a database called test_db:

let db = client.database("test_db");

To see a list of your deployment's databases, call the list_database_names() method on your Client instance. This method returns a Vec<String> type, a vector containing the database names as strings.

To see detailed information about each database, call the list_databases() method on your Client instance. This method returns a Vec<DatabaseSpecification> type. The DatabaseSpecification type contains fields describing each database, such as its size and whether it contains data.

The following example shows how to print a list of databases by using the list_database_names() method:

let db_list = client.list_database_names(doc! {}, None).await?;
println!("{:?}", db_list);

Dropping a database permanently deletes all the data in that database's collections. To drop a database, call the drop() method on your Database instance. The following code shows how to drop a database referenced by the db variable:

db.drop(None).await?;

Warning

Dropping a Database Deletes Data

Dropping a database permanently deletes all documents in the database's collections and all indexes on those collections. After you drop a database, you cannot access or restore any of its data.

You can access a collection by retrieving a Collection instance from your database. You can use a Collection instance to perform data operations, create aggregations, and manage indexes. Call one of the following methods on a Database instance to retrieve a Collection:

If you pass the name of a nonexistent collection to the collection() or collection_with_options() methods, the driver still returns a Collection instance. When you insert any data into this collection, the server creates it. To learn how to explicitly create a collection, see the Create a Collection section of this guide.

This example uses the collection_with_options() method to perform the following actions:

  • Access a collection called coll_xyz from a database referenced by the db variable

  • Set a write preference on the collection in the CollectionOptions type

let wc = WriteConcern::builder().journal(true).build();
let coll_opts = CollectionOptions::builder().write_concern(wc).build();
let my_coll: Collection<Document> = db.collection_with_options("coll_xyz", coll_opts);

To learn more about write concerns, see Write Concern in the Server manual.

You must parameterize your Collection instance by specifying what data type you want to serialize the collection's data into. When you call a method on a Collection instance that is parameterized with a specific type, the method accepts or returns instances of this type.

Note

If you do not parameterize your Collection instance, the compiler infers the generic type when you perform a CRUD operation with a specified data type in the same scope.

The following example shows equivalent ways of parameterizing a collection with the Document type:

let my_coll: Collection<Document> = client.database("test_db").collection("coll_xyz");
let my_coll = client.database("test_db").collection::<Document>("coll_xyz");

Tip

We recommend that you parameterize your Collection instance with a custom type that models your data instead of the Document type. You can avoid repetitive serialization and validation by defining a type that models your specific data.

To learn more about serialization in the Rust driver, see the guide on Data Modeling and Serialization.

You can explicitly create a collection by calling the create_collection() method on a Database instance. This method takes the collection name and an optional CreateCollectionOptions type as parameters. You can use a Collection instance to perform data operations, create aggregations, and manage indexes.

The following code shows how to create a collection called coll_abc within a database referenced by the db variable:

db.create_collection("coll_abc", None).await?;

When creating a collection, you can implement schema validation to maintain a consistent document schema and control whether any write operations can bypass the validation rules. To learn how to enable this feature, see the guide on Schema Validation.

To see the names of the collections in a database, call the list_collection_names() method on your Database instance. This method returns a Vec<String> type, a vector containing the collection names as strings.

To see detailed information about each collection, call the list_collections() method on your Database instance. This method returns a Vec<CollectionSpecification> type. The CollectionSpecification type contains fields describing each collection, such as its type and settings.

The following example shows how to print the names of the collections in a database referenced by the db variable by using the list_collection_names() method:

let coll_list = db.list_collection_names(doc! {}).await?;
println!("{:?}", coll_list);

Dropping a collection permanently deletes all the data in that collection. To drop a collection, call the drop() method on your Collection instance. The following code shows how to drop a collection referenced by the my_coll variable:

my_coll.drop(None).await?;

Warning

Dropping a Collection Deletes Data

Dropping a collection from your database permanently deletes all documents within that collection and all indexes on that collection. After you drop a collection, you cannot access or restore any of its data.

For more information about the concepts in this guide, see the following documentation:

← Data Modeling and Serialization