Flask configuration

Flask-mongoengine does not provide any configuration defaults. User is responsible for setting up correct database settings, to exclude any possible misconfiguration and data corruption.

There are several options to set connection. Please note, that all except recommended are deprecated and may be removed in future versions, to lower code base complexity and bugs. If you use any deprecated connection settings approach, you should update your application configuration.

By default, flask-mongoengine open the connection when extension is instantiated, but you can configure it to open connection only on first database access by setting the 'connect' dictionary parameter or its MONGODB_CONNECT flat equivalent to False.

Note

Due lack of developers we are unable to answer/solve not recommended connection methods errors. Please switch to recommended method before posting any issue. Thank you.

Recommended: List of dictionaries settings

Recommended way for setting up connections is to set MONGODB_SETTINGS in you application config. MONGODB_SETTINGS is a list of dictionaries, where each dictionary is configuration for individual database (for systems with multi-database) use.

Each dictionary in MONGODB_SETTINGS will be passed to mongoengine.connect(), which will bypass settings to mongoengine.register_connection(). All settings related to mongoengine.connect() and mongoengine.register_connection() will be extracted by mentioned functions, any other keyword arguments will be silently followed to pymongo.mongo_client.MongoClient.

This allows complete and flexible database configuration.

Example:

import flask
from flask_mongoengine import MongoEngine

db = MongoEngine()
app = flask.Flask("example_app")
app.config["MONGODB_SETTINGS"] = [
    {
        "db": "project1",
        "host": "localhost",
        "port": 27017,
        "alias": "default",
    }
]
db.init_app(app)

Deprecated: Passing database configuration to MongoEngine class

Deprecated since version 2.0.0.

You can pass database dictionary of dictionaries directly to MongoEngine class initialization. Lists of settings not supported.

import flask
from flask_mongoengine import MongoEngine

db_config = {
    "db": "project1",
    "host": "localhost",
    "port": 27017,
    "alias": "default",
}
db = MongoEngine(config=db_config)
app = flask.Flask("example_app")

db.init_app(app)

Deprecated: Passing database configuration to MongoEngine.init_app method

Deprecated since version 2.0.0.

You can pass database dictionary of dictionaries directly to flask_mongoengine.MongoEngine.init_app() class initialization. Lists of settings not supported.

import flask
from flask_mongoengine import MongoEngine

db_config = {
    "db": "project1",
    "host": "localhost",
    "port": 27017,
    "alias": "default",
}
db = MongoEngine()
app = flask.Flask("example_app")

db.init_app(app, config=db_config)

Deprecated: MONGODB_ inside MONGODB_SETTINGS dictionary

Deprecated since version 2.0.0.

Flask-mongoengine will cut off MONGODB_ prefix from any parameters, specified inside MONGODB_SETTINGS dictionary. This is historical behaviour, but may be removed in the future. Providing such settings may raise config errors, when parent packets implement case-sensitive keyword arguments checks. Check issue #451 for example historical problem.

Currently, we are handling all possible case-sensitive keyword settings and related users errors (based on pymongo 4.1.1), but amount of such settings may be increased in future pymongo versions.

Usage of recommended settings approach completely remove this possible problem.

Deprecated: URI style settings

Deprecated since version 2.0.0.

URI style connections supported as supply the uri as the host in the MONGODB_SETTINGS dictionary in app.config.

Warning

It is not recommended to use URI style settings, as URI style settings parsed and manupulated in all parent functions/methods. This may lead to unexpected behaviour when parent packages versions changed.

Warning

Database name from uri has priority over name. (MongoEngine behaviour).

If uri presents and doesn’t contain database name db setting entirely ignore and db name set to test:

import flask
from flask_mongoengine import MongoEngine

db = MongoEngine()
app = flask.Flask("example_app")
app.config['MONGODB_SETTINGS'] = {
    'db': 'project1',
    'host': 'mongodb://localhost/database_name'
}
db.init_app(app)

Deprecated: Flat MONGODB_ style configuration settings

Deprecated since version 2.0.0.

Connection settings may also be provided individually by prefixing the setting with MONGODB_ in the app.config:

import flask
from flask_mongoengine import MongoEngine

db = MongoEngine()
app = flask.Flask("example_app")
app.config['MONGODB_DB'] = 'project1'
app.config['MONGODB_HOST'] = '192.168.1.35'
app.config['MONGODB_PORT'] = 12345
app.config['MONGODB_USERNAME'] = 'webapp'
app.config['MONGODB_PASSWORD'] = 'pwd123'
db.init_app(app)

This method does not support multi-database installations.

By default, flask-mongoengine open the connection when extension is instantiated, but you can configure it to open connection only on first database access by setting the MONGODB_SETTINGS['connect'] parameter or its MONGODB_CONNECT flat equivalent to False.