Skip to content

Connecting to MongoDB

  • MongoDB

A MongoDB connection profile says where the servers are and how to sign in. You can connect to one server, to a list of replica set members, to an SRV name (mongodb+srv) or through a connection URI, and sign in with a user and password (SCRAM or LDAP), with AWS IAM, with OIDC or with an X.509 client certificate.

  1. Open the Connection actions menu at the top of the side bar and choose New connection, or press Ctrl + Shift + N (Cmd + Shift + N on macOS).
  2. Pick the MongoDB card and choose Next, or double-click the card. To start from a URI instead, paste it into Paste a URI to fill the form and choose Fill from URI: the URI names the engine, so the form opens filled in.
  3. On the General tab, enter a Name, pick how Querybara reaches the servers under Connect with (see Endpoints) and fill in its fields.
  4. Still on General, pick how you sign in under Authentication (see Sign-in methods).
  5. On the Advanced tab, set the options you need.
  6. On the TLS tab, set the TLS mode, and the CA certificate, Client certificate and Client key if your server needs them. A new connection starts with TLS off; an SRV record, or tls or ssl in a pasted URI, turns it on.
  7. Choose Test Connection. Each step is shown as it runs: DNS lookup, TCP connect, SSH tunnel, TLS handshake, Authentication, Ping and Server version. The last step names the MongoDB version and the topology.
  8. Choose Save.

A tab that holds an invalid field shows a red dot, and Save or Test Connection opens it.

Connect with What you enter
Host and port Host and Port of one server.
Host list (replica set) Hosts: any members of the replica set (the driver finds the others), and an optional Replica set name such as rs0. Use Add host for more rows.
SRV record (mongodb+srv) SRV host name, such as cluster0.example.com.
Connection URI URI (without the password), such as mongodb://[email protected]:27017,db2.example.com:27017/catalog?replicaSet=rs0.

With SRV record (mongodb+srv), Querybara looks up the hosts (the _mongodb._tcp SRV record) and the default options in DNS, as a mongodb+srv:// URI does. The lookup happens on this computer, also when the servers are reached through an SSH tunnel or a proxy. An SRV record implies TLS, as in the MongoDB drivers: set TLS mode to Disable TLS only for a server that has none.

These fields are on the Advanced tab, for every endpoint except Connection URI, where the URI carries them.

Option What it does
Default database Optional. The database the connection starts in.
Read preference Driver default (primary), Primary, Primary preferred, Secondary, Secondary preferred or Nearest.
Direct connection With Host and port only. Talk to that host only instead of discovering the replica set from it.

Use Direct connection for a secondary, or for a member known by an address the other members do not use.

Authentication What you enter
None Nothing.
User and password Mechanism, User, the password and, except with a URI, the Authentication database (where the user is defined; empty uses admin).
X.509 client certificate The client certificate and key on the TLS tab. User is optional: the certificate’s subject, such as CN=app,OU=clients.

The Mechanism list offers SCRAM-SHA-256, SCRAM-SHA-1, LDAP (PLAIN), AWS IAM (MONGODB-AWS), OIDC (MONGODB-OIDC) and Negotiate with the server. LDAP, AWS IAM and OIDC identities sign in through $external, so with those mechanisms the authentication database is fixed to $external. See AWS IAM and OIDC for their fields.

An X.509 sign-in also happens in $external. You can choose one PEM file that holds both the certificate and the key for Client certificate and Client key.

Choose User and password under Authentication, then AWS IAM (MONGODB-AWS) as the Mechanism. The fields change:

Field What you enter
Access key ID The access key ID, or nothing to use the AWS credential chain
Secret access key The secret access key, kept like a password (see Passwords and keychain)

With Access key ID empty, the AWS credential chain applies: environment variables, the shared credential and config files (SSO profiles included), and the role of the instance or container Querybara runs on. Temporary credentials with a session token come through the chain too.

Choose User and password under Authentication, then OIDC (MONGODB-OIDC) as the Mechanism, and pick where the token comes from under Identity:

Identity What you enter
Sign in with the identity provider in the browser User is optional: it is suggested to the identity provider
Azure managed identity Token resource, and optionally the managed identity’s client ID in User
GCP service account Token resource
Kubernetes service account Nothing more

Token resource is the audience the token is issued for, such as api://<application id>.

With Sign in with the identity provider in the browser, Querybara opens the identity provider’s sign-in page in your browser when it connects. The page returns to http://localhost:27097/redirect. Querybara keeps the tokens in memory until it quits, and the connection’s tabs, IntelliShell included, share one sign-in. A job such as an export or a transfer runs in its own process and signs in again there; the browser usually completes that without asking.

A token from the browser sign-in is sent only to MongoDB Atlas hosts, localhost, and the hosts the connection names; for an SRV name, the hosts of its domain. A replica set whose members announce other names needs those names in a Host list (replica set).

A connection string with authMechanism=MONGODB-AWS or authMechanism=MONGODB-OIDC fills the same fields, and for OIDC its authMechanismProperties fill Identity (ENVIRONMENT) and Token resource (TOKEN_RESOURCE).

Host lists, SRV names and URIs that name several hosts or a replicaSet work through an SSH tunnel (jump hosts included) and through SOCKS5 and HTTP proxies. Each member is reached by the name it announces, resolved on the far side of the tunnel. A single host behind a tunnel connects with a direct connection.

SRV and TXT records are still looked up on this computer. If the SRV name does not resolve here, the connection fails with a hint: make the name resolvable on this computer, or use a host list.

See Replica sets, Sentinel and Cluster through tunnels.

querybara test runs the same stepwise check against a saved profile or a MongoDB URI:

Terminal window
querybara test "mongodb+srv://[email protected]/catalog"
querybara test "mongodb://[email protected]:27017/catalog" --ssh [email protected] --ssh-agent

It exits with 0 when every step passes and 1 when one fails, with a fix hint.

Documents Querybara 0.1.19 · built from89dc752