# 2.2. Connecting to MongoDB

Connections in MongoEngine are registered globally and are identified with aliases. If no alias is provided during the connection, it will use “default” as alias.

To connect to a running instance of mongod, use the `connect()` function. The first argument is the name of the database to connect to:

    from mongoengine import connect
    connect('project1')

By default, MongoEngine assumes that the mongod instance is running on localhost on port 27017. If MongoDB is running elsewhere, you should provide the `host` and `port` arguments to `connect()`:

    connect('project1', host='192.168.1.35', port=12345)

If the database requires authentication, `username`, `password` and `authentication_source` arguments should be provided:

    connect('project1', username='webapp', password='pwd123', authentication_source='admin')

URI style connections are also supported – just supply the URI as the `host` to `connect()`:

    connect('project1', host='mongodb://localhost/database_name')

Note

Database, username and password from URI string overrides corresponding parameters in `connect()`:

    connect(
        db='test',
        username='user',
        password='12345',
        host='mongodb://admin:qwerty@localhost/production'
    )

will establish connection to `production` database using `admin` username and `qwerty` password.

Note

Calling `connect()` without argument will establish a connection to the “test” database by default

## 2.2.1. Replica Sets

MongoEngine supports connecting to replica sets:

    from mongoengine import connect

    # Regular connect
    connect('dbname', replicaset='rs-name')

    # MongoDB URI-style connect
    connect(host='mongodb://localhost/dbname?replicaSet=rs-name')

Read preferences are supported through the connection or via individual queries by passing the read_preference

    Bar.objects().read_preference(ReadPreference.PRIMARY)
    Bar.objects(read_preference=ReadPreference.PRIMARY)

## 2.2.2. Multiple Databases

To use multiple databases you can use `connect()` and provide an alias name for the connection - if no alias is provided then “default” is used.

In the background this uses `register_connection()` to store the data and you can register all aliases up front if required.

### 2.2.2.1. Documents defined in different database

Individual documents can be attached to different databases by providing a db_alias in their meta data. This allows `DBRef` objects to point across databases and collections. Below is an example schema, using 3 different databases to store data:

    connect(alias='user-db-alias', db='user-db')
    connect(alias='book-db-alias', db='book-db')
    connect(alias='users-books-db-alias', db='users-books-db')

    class User(Document):
        name = StringField()

        meta = {'db_alias': 'user-db-alias'}

    class Book(Document):
        name = StringField()

        meta = {'db_alias': 'book-db-alias'}

    class AuthorBooks(Document):
        author = ReferenceField(User)
        book = ReferenceField(Book)

        meta = {'db_alias': 'users-books-db-alias'}

### 2.2.2.2. Disconnecting an existing connection

The function `disconnect()` can be used to disconnect a particular connection. This can be used to change a connection globally:

    from mongoengine import connect, disconnect
    connect('a_db', alias='db1')

    class User(Document):
        name = StringField()
        meta = {'db_alias': 'db1'}

    disconnect(alias='db1')

    connect('another_db', alias='db1')

Note

Calling `disconnect()` without argument will disconnect the “default” connection

Note

Since connections gets registered globally, it is important to use the disconnect function from MongoEngine and not the disconnect() method of an existing connection (pymongo.MongoClient)

Note

`Document` are caching the pymongo collection. using disconnect ensures that it gets cleaned as well

## 2.2.3. Context Managers

Sometimes you may want to switch the database or collection to query against. For example, archiving older data into a separate database for performance reasons or writing functions that dynamically choose collections to write a document to.

### 2.2.3.1. Switch Database

The `switch_db` context manager allows you to change the database alias for a given class allowing quick and easy access to the same User document across databases:

    from mongoengine.context_managers import switch_db

    class User(Document):
        name = StringField()

        meta = {'db_alias': 'user-db'}

    with switch_db(User, 'archive-user-db') as User:
        User(name='Ross').save()  # Saves the 'archive-user-db'

### 2.2.3.2. Switch Collection

The `switch_collection()` context manager allows you to change the collection for a given class allowing quick and easy access to the same Group document across collection:

    from mongoengine.context_managers import switch_collection

    class Group(Document):
        name = StringField()

    Group(name='test').save()  # Saves in the default db

    with switch_collection(Group, 'group2000') as Group:
        Group(name='hello Group 2000 collection!').save()  # Saves in group2000 collection

Note

Make sure any aliases have been registered with `register_connection()` or `connect()` before using the context manager.