Connect MongoG to MongoDB Atlas or a Local Server

Before you connect

MongoG connects with the official MongoDB Node.js driver. You need a reachable MongoDB deployment, valid credentials when authentication is enabled, and network access from the computer running MongoG.

For MongoDB Atlas, add your current network to the Atlas access list and create a database user with only the roles the work requires. For a local deployment, confirm the server is running and listening on the expected interface.

Create a connection profile

Open Connections and create a profile. The Basic editor covers common values; the Advanced editor accepts driver-compatible options for deployments that need them.

1. Give the profile a recognizable name such as Tutorial — Local or Tutorial — Atlas.
2. Enter the connection URI in the connection form, not in a query script.
3. Set mongog_tutorial as the default database for these lessons.
4. Test and save the profile, then connect from the Explorer.

Saved secrets are encrypted with the operating system's secure storage and remain on the local device. MongoG does not place credentialed URIs in query history, result data, or renderer state.

Local and Atlas URI shapes

A local deployment commonly uses this shape:

mongodb://localhost:27017

An Atlas deployment provides an SRV URI shaped like this:

mongodb+srv://<username>:<password>@<cluster-host>/

Treat both as secrets when they contain credentials or tokens. Copy the actual value directly into MongoG's connection editor. Never commit it to a repository, paste it into documentation, or print it from a script.

Verify the connection

Open a query tab for the saved connection and run a read-only command:

print("Connected database:", db.databaseName);
db.command({ ping: 1 });

The db global is a real driver Db object for the active database. The ping result should include ok: 1.

Switch to the tutorial database when needed:

use("mongog_tutorial");
print("Active database:", db.databaseName);
db.listCollections({}, { nameOnly: true });

use() updates the script's active db value. It does not create the database by itself; MongoDB creates persisted database data after a successful write.

Troubleshoot common failures

Authentication failed

Check the username, password, authentication database, and assigned roles. A successful login does not imply permission for every database operation.

Server selection timed out

Confirm DNS, VPN, firewall, Atlas network access, host names, and ports. For a replica set, every advertised member must be reachable from the desktop.

TLS or certificate error

Use the deployment's intended certificate chain and driver options. Do not disable certificate verification as a permanent fix.

Writes are rejected

The MongoDB user may have read-only roles, or the MongoG profile may be marked read-only. Server roles are authoritative and should enforce production access.

Choose connection options deliberately

The Advanced editor exposes settings for authentication, TLS, read preference, timeouts, and other driver-compatible behavior. Start with deployment defaults and change an option only to satisfy a known requirement.

• serverSelectionTimeoutMS bounds how long topology selection waits before reporting failure; lowering it does not repair DNS or firewall problems.
• connectTimeoutMS concerns establishing an individual socket connection.
• Read preference can route eligible reads, but it changes consistency and topology behavior. primary remains the safe default for ordinary read-after-write expectations.
• Authentication source identifies the database that stores the user credentials; it is not necessarily the database the application reads.
• TLS options must match the deployment’s certificate configuration. Permanent certificate verification bypasses hide trust problems.

For a replica set, use the URI and member names provided by the deployment. Every advertised host must resolve and be reachable from the machine running MongoG.

Separate profiles by purpose

Create distinct profiles for local development, staging investigation, production read-only access, and approved production maintenance. Give them visually distinct names, colors, and groups so the selected target is obvious.

A production inspection profile should combine MongoG’s read-only switch with a MongoDB user that has read-only roles. Keep a separate writable profile disconnected until an approved task requires it. This reduces the chance that a correct script runs against the wrong environment with excessive permission.

Diagnose with bounded commands

After ping, inspect the topology and authorization only as far as your role permits:

printjson({
  database: db.databaseName,
  clientType: client.constructor.name,
});

const collections = await db.listCollections({}, { nameOnly: true }).toArray();
print("Visible collections:", collections.length);

The explicit toArray() is bounded here only if the database has a manageable number of collections. For large metadata sets, iterate the cursor instead.

Practice by creating two profiles for the same tutorial deployment: one writable and one server-authorized read-only. Confirm both can ping and query, then verify that a write fails through the read-only account for the expected authorization reason.

Common mistakes

• Putting a URI in the query editor bypasses the purpose of an encrypted connection profile and risks saving it in history.
• Allowing all public IP addresses in Atlas is broader than most development workflows require.
• Giving an everyday profile administrator roles increases the impact of an accidental script.
• Assuming the default database changes authorization ignores roles granted on other databases.
• Shortening timeouts until an error appears faster does not solve an unreachable or incorrectly advertised deployment.
• Reusing one administrator profile for every environment removes an important visual and authorization boundary.

Continue learning

Move on to the MongoG query editor workflow, compare the broader MongoDB client workflow, or choose a platform-specific build for macOS, Windows, or Linux RPM. For deployment-specific parameters, use the official driver connection guide.