From e31f9150d26f2ea7c7ecb09445a0cb39c2a2fd4d Mon Sep 17 00:00:00 2001 From: Bastien Gerard Date: Sun, 28 Feb 2021 14:32:46 +0100 Subject: [PATCH] improve connect() doc and put more emphasis on URI string --- docs/guide/connecting.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst index fea5e97b..d9b8bdbf 100644 --- a/docs/guide/connecting.rst +++ b/docs/guide/connecting.rst @@ -25,30 +25,35 @@ and :attr:`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 :attr:`host` to -:func:`~mongoengine.connect`:: +URI string connection is also supported and **is the recommended way to connect**. The URI string is +forwarded to the driver as is, so it follows the same scheme as the `MongoDB URI `_. +Just supply the URI as the :attr:`host` to :func:`~mongoengine.connect`:: + + connect(host="mongodb://user:password@hostname:port/db_name") + +URI string can be used to configure advanced parameters like ssl, replicaSet, etc:: + + connect(host="mongodb://user:password@hostname:port/db_name?ssl=true&replicaSet=globaldb") - connect('project1', host='mongodb://localhost/database_name') .. note:: URI containing SRV records (e.g mongodb+srv://server.example.com/) can be used as well as the :attr:`host` -.. note:: Database, username and password from URI string overrides - corresponding parameters in :func:`~mongoengine.connect`: :: +.. note:: The URI string has precedence over keyword args so if you accidentally call :: connect( db='test', username='user', password='12345', - host='mongodb://admin:qwerty@localhost/production' + host='mongodb://admin:qwerty@localhost/my_db' ) - will establish connection to ``production`` database using - ``admin`` username and ``12345`` password. + it will ignore the db, username and password argument and establish the connection to ``my_db`` database using + ``admin`` username and ``qwerty`` password. .. note:: Calling :func:`~mongoengine.connect` without argument will establish a connection to the "test" database by default + Replica Sets ============