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.
Create a MongoDB connection
Section titled “Create a MongoDB connection”- 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).
- 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.
- On the General tab, enter a Name, pick how Querybara reaches the servers under Connect with (see Endpoints) and fill in its fields.
- Still on General, pick how you sign in under Authentication (see Sign-in methods).
- On the Advanced tab, set the options you need.
- 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
tlsorsslin a pasted URI, turns it on. - 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.
- Choose Save.
A tab that holds an invalid field shows a red dot, and Save or Test Connection opens it.
Endpoints
Section titled “Endpoints”| 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.
Options
Section titled “Options”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.
Sign-in methods
Section titled “Sign-in methods”| 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.
AWS IAM
Section titled “AWS IAM”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).
Sign-in from a pasted URI
Section titled “Sign-in from a pasted URI”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).
Replica sets through SSH and proxies
Section titled “Replica sets through SSH and proxies”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.
From the command line
Section titled “From the command line”querybara test runs the same stepwise check against a saved profile or a MongoDB URI:
It exits with 0 when every step passes and 1 when one fails, with a fix hint.
Related
Section titled “Related”Documents Querybara 0.1.19 · built from89dc752