Connection Manager

The Connection Manager is your central hub for organizing and managing all MongoDB database connections. Create, edit, test, and organize connections into projects and environments for streamlined database access across your team.

Connection Organization

VisualLeaf offers flexible connection management through three organizational levels:

Organization Hierarchy

• Projects - Top-level containers for grouping related connections (e.g., "E-Commerce App", "Analytics Platform")
• Environments - Sub-groups within projects for deployment stages (e.g., Development, Staging, Production). Each environment has a color-coded label for quick visual identification
• Connections - Individual database connection configurations within environments
• Ungrouped - Standalone connections not assigned to any project

View Modes

Use the sidebar to filter your connection display:

• All Connections - Shows both ungrouped connections and all projects
• By Project - Shows only project-organized connections
• Ungrouped - Shows only standalone connections

Project and Environment Tags

Every project and environment can carry lightweight metadata that VisuaLeaf uses for search, filtering, and workspace grouping:

• Environment color labels — red, amber, green, blue, or purple badges surface in the sidebar, connection cards, and every open workspace tab so you always know which environment is active
• Project descriptions — free-text summaries that appear on hover and in the project header
• Environment tags — short keyword tags (e.g., prod, eu-west-1, pci) that participate in the sidebar search

Connection Presets

Presets are reusable connection templates that let you standardize how your team connects to common deployments. Use the "Save as preset" action on a fully configured connection to capture Server, SSL/TLS, SSH, and Options settings as a template; then apply the preset when creating a new connection to pre-fill everything except the per-user credentials.

• Presets are stored per user and can be exported alongside connections
• Applying a preset never overwrites an existing connection — it only fills empty fields in the new connection form
• Common preset targets: MongoDB Atlas free-tier defaults, corporate SSH bastion, mutual-TLS gold cluster, Kerberos-joined enterprise cluster

Creating and Editing Connections

The connection form provides comprehensive configuration across five tabs: Server, Authentication, SSL, SSH, and Options.

Quick Actions

• Test Connection - Validates your connection settings without saving. Shows step-by-step progress including network connectivity, authentication, SSL/TLS handshake, and database access verification.
• Create from URL - Import connection settings from a MongoDB connection string (mongodb:// or mongodb+srv://). Automatically populates all form fields across all tabs.
• Export to URL - Generate a standard MongoDB connection string from your current form settings for sharing or use in other applications.

Connection String Auto-Fill

Paste a MongoDB connection string directly into the form to automatically populate all fields:

• Standard format: mongodb://username:password@host:port/database
• DNS Seedlist format: mongodb+srv://username:password@cluster.mongodb.net/database
• Supports query parameters for SSL, authentication, and connection options

Database Type

At the top of the connection form, you'll find the Database Type selector. This determines which database platform you're connecting to.

Database Type	Status	Description
MongoDB	Available	Full support for MongoDB databases including Atlas, standalone, replica sets, and sharded clusters
Amazon DocumentDB 8.0+	Coming Soon	Native connectivity to Amazon DocumentDB, including compatibility with MongoDB APIs, query execution, schema visualization, and data exploration - making it easy to manage DocumentDB clusters with the same VisuaLeaf experience you use for MongoDB.
Azure Cosmos DB 4.2+	Coming Soon	Native support for Azure Cosmos DB (MongoDB API), enabling seamless connections, query execution, schema visualization, and data exploration within VisuaLeaf.
Redis 7.0+	Coming Soon	Native connectivity to Redis databases, enabling key exploration, data type visualization, TTL management, and real-time monitoring within VisuaLeaf.

Note: Currently only MongoDB is fully supported. Additional database platforms will be added in future releases. The interface will adapt based on the selected database type to show relevant configuration options.

Server Tab

Configure the database server connection details and deployment topology.

Connection Types

Type	Description	When to Use
Standalone	Single MongoDB server instance	Development, testing, or small deployments without high availability requirements
Replica Set	Group of MongoDB servers maintaining the same data for redundancy	Production deployments requiring high availability, automatic failover, and read scaling
Sharded Cluster	Horizontally partitioned database across multiple shards	Large-scale deployments with massive datasets that exceed single-server capacity
DNS Seedlist	Dynamic server discovery using DNS SRV records (mongodb+srv://)	MongoDB Atlas or cloud deployments with dynamic IP addresses

Standalone Configuration

Field	Description	Default
Host	Server hostname or IP address	localhost
Port	MongoDB server port number	27017
Database Name	Default database to connect to (optional)	None
Read Preference	How to route read operations (Primary, Secondary, Nearest)	Nearest

Replica Set Configuration

Field	Description	Required
Replica Set Name	Name of the replica set (must match server configuration)	Yes
Replica Hosts	List of host:port pairs for replica set members	Yes (at least one)
Read From Hidden Nodes	Allow reads from hidden replica set members	No
Resolve Cluster Members	Automatically discover all replica set members	No

Sharded Cluster Configuration

Field	Description	Required
Mongos Hosts	List of host:port pairs for mongos routers	Yes (at least one)
Read Preference	Routing preference for read operations across shards	No

DNS Seedlist Configuration

Field	Description	Default
Connection URI	DNS hostname for SRV record lookup (e.g., cluster.mongodb.net)	None
SRV Service Name	Custom SRV service name (optional)	mongodb

Authentication Tab

Configure how VisualLeaf authenticates with your MongoDB server. Multiple authentication mechanisms are supported.

Authentication Mechanisms

Mechanism	Description	Use Case
None	No authentication required	Local development servers without security
SCRAM-SHA-256	Salted Challenge Response Authentication (recommended)	Default for MongoDB 4.0+ deployments
SCRAM-SHA-1	Legacy SCRAM authentication	MongoDB 3.x or servers configured for SHA-1
X.509	Certificate-based authentication	High-security environments requiring mutual TLS
Kerberos (GSSAPI)	Kerberos ticket-based authentication using the GSSAPI mechanism	Enterprise deployments with Active Directory or MIT Kerberos KDCs
LDAP (PLAIN)	LDAP directory authentication using the PLAIN SASL mechanism	MongoDB Enterprise deployments federated with an LDAP or Active Directory server
AWS IAM (MONGODB-AWS)	AWS Identity and Access Management with support for static keys, STS session tokens, and SSO-cached credentials	MongoDB Atlas on AWS — including mongodb+srv:// seedlist connections — when authenticating with IAM roles or AWS SSO profiles
OIDC (MONGODB-OIDC)	OpenID Connect token-based authentication	Modern SSO integrations with Okta, Auth0, Azure AD, or any OIDC identity provider

SCRAM-SHA-256 / SCRAM-SHA-1 Configuration

Field	Description	Required
Username	MongoDB username	Yes
Password	MongoDB password (click eye icon to show/hide)	Yes
Auth Database	Database containing user credentials. Defaults to 'admin'	No

X.509 Configuration

X.509 authentication uses client certificates instead of a username and password. No additional fields are required on the Authentication tab beyond enabling the mechanism — the credential is the certificate itself, configured on the SSL/TLS tab.

• Authentication database is always $external
• Username is extracted from the client certificate's Subject DN by the server
• Requires SSL/TLS tab configuration with a valid client certificate and private key
• The server must trust the CA that signed the client certificate

Equivalent connection string:

mongodb://mongo.example.com:27017/?authMechanism=MONGODB-X509&authSource=$external&tls=true&tlsCertificateKeyFile=/path/to/client.pem

AWS IAM Configuration

AWS IAM authentication uses the MONGODB-AWS SASL mechanism and always resolves against the $external authentication database. VisuaLeaf accepts three credential shapes:

• Long-lived IAM user keys — Access Key ID plus Secret Access Key
• Temporary STS credentials — Access Key ID, Secret Access Key, and Session Token from sts:AssumeRole, AssumeRoleWithSAML, or AssumeRoleWithWebIdentity
• AWS SSO / IAM Identity Center cached credentials — leave the fields blank and VisuaLeaf will resolve credentials from your local AWS SSO cache (the same one used by the AWS CLI). As of the February 2026 release, SSO-cached credentials are correctly forwarded on mongodb+srv:// Atlas connections.

Field	Description	Required
Access Key ID	AWS IAM access key (e.g., AKIAIOSFODNN7EXAMPLE). Leave blank to use SSO cache.	Only when using static keys
Secret Access Key	AWS IAM secret key (click eye icon to show/hide). Leave blank to use SSO cache.	Only when using static keys
Session Token	Temporary session token for STS AssumeRole credentials	Only for temporary credentials

Equivalent connection strings for a standalone MongoDB Enterprise cluster:

mongodb://AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI%2FK7MDENG%2FbPxRfiCYEXAMPLEKEY@mongo.example.com:27017/?authMechanism=MONGODB-AWS&authSource=$external

With a temporary STS session token (passed via the AWS_SESSION_TOKEN auth mechanism property):

mongodb://ASIA...:...@mongo.example.com:27017/?authMechanism=MONGODB-AWS&authSource=$external&authMechanismProperties=AWS_SESSION_TOKEN:IQoJb3JpZ2luX2VjE...

MongoDB Atlas SRV seedlist connection (credentials can be supplied inline, or omitted so VisuaLeaf resolves them from the AWS SSO cache):

mongodb+srv://cluster0.abcde.mongodb.net/?authMechanism=MONGODB-AWS&authSource=$external&retryWrites=true&w=majority

LDAP (PLAIN) Configuration

LDAP authentication uses the PLAIN SASL mechanism to proxy credentials to your directory server through MongoDB Enterprise. The auth source is always $external.

Field	Description	Required
LDAP Username	LDAP directory username (e.g., user@domain.com or CN=user,DC=domain,DC=com)	Yes
Password	LDAP password (transmitted over the TLS-secured channel)	Yes

Note: Because PLAIN transmits the password in cleartext at the SASL layer, always enable TLS on the SSL/TLS tab before using LDAP authentication.

Equivalent connection string:

mongodb://alice%40corp.example.com:secret@mongo.example.com:27017/?authMechanism=PLAIN&authSource=$external&tls=true

Kerberos (GSSAPI) Configuration

Kerberos authentication uses the GSSAPI SASL mechanism and delegates ticket acquisition to the operating system's Kerberos stack (MIT Kerberos on Linux/macOS, SSPI on Windows). VisuaLeaf resolves credentials from your active ticket cache — run kinit before connecting if no ticket is present.

Field	Description	Required
Principal	Fully qualified Kerberos principal (e.g., alice@EXAMPLE.COM)	Yes
Service Name	Kerberos service name registered for MongoDB (default mongodb)	No
Service Realm	Realm of the MongoDB service, if different from the principal's realm	No

Equivalent connection string:

mongodb://alice%40EXAMPLE.COM@mongo.example.com:27017/?authMechanism=GSSAPI&authSource=$external&authMechanismProperties=SERVICE_NAME:mongodb

OIDC Configuration

OIDC authentication uses the MONGODB-OIDC mechanism to exchange short-lived access tokens issued by an OpenID Connect identity provider (Okta, Auth0, Azure AD, Google, etc.). VisuaLeaf launches the OIDC device-authorization flow in your default browser during the first connection attempt, then caches and refreshes tokens automatically.

Field	Description	Required
Principal (Username)	OIDC subject or username hint used to pre-fill the login screen	No
Provider Name	Named provider configured on the MongoDB server, when multiple IdPs are registered	No

Equivalent connection string:

mongodb://mongo.example.com:27017/?authMechanism=MONGODB-OIDC&authSource=$external

SSL/TLS Tab

Configure SSL/TLS encryption for secure communication with MongoDB. Essential for production deployments and cloud services like MongoDB Atlas.

SSL Mode

Toggle SSL/TLS encryption on or off using the switch at the top of the tab.

Certificate Configuration

Option	Description	When to Use
Use own Root CA file	Validate server certificate against a specific CA certificate file	Self-signed certificates or internal CAs
Accept OS-trusted certificates	Trust certificates signed by system-trusted CAs	MongoDB Atlas or certificates from public CAs
Accept any certificates	Skip certificate validation (insecure)	Development/testing only - NOT for production

CA Certificate (Root CA File)

Field	Description	Format
CA Certificate	Path to Certificate Authority file (--sslCAFile). Click Browse to select file.	PEM format (.pem, .crt)

Client Certificate (Mutual TLS)

Enable the "Use Client Certificate" toggle to configure client-side authentication for mutual TLS:

Field	Description	Format
Client Certificate	Client certificate file path. Click Browse to select file.	PEM format (.pem, .crt)
Private Key	Private key file path (if separate from certificate). Click Browse to select file.	PEM format (.pem, .key)
Has Passphrase	Toggle if private key is encrypted with a passphrase	Checkbox
Passphrase	Passphrase to decrypt the private key (if encrypted)	Text (hidden)

SSH Tunnel Tab

Configure SSH tunneling to connect to MongoDB servers behind firewalls or in private networks. The SSH tunnel creates a secure connection through an intermediate server.

SSH Tunnel Mode

Toggle SSH tunneling on or off using the switch at the top of the tab.

SSH Connection Settings

Field	Description	Default
SSH Host	Hostname or IP address of the SSH server (bastion host)	None
SSH Port	SSH server port number	22
SSH Username	SSH login username	None

SSH Authentication Modes

Mode	Required Fields	Description
Password	SSH Password (hidden input with show/hide toggle)	Simple password authentication for SSH connection
Private Key	Private Key File Path, Has Passphrase (checkbox), Passphrase (optional)	Public key authentication using SSH key pair. More secure than password. Enable "Has passphrase" if key is encrypted.

How SSH Tunneling Works

1. VisualLeaf connects to the SSH server using your credentials
2. A secure tunnel is established through the SSH connection
3. MongoDB traffic is forwarded through the tunnel to the database server
4. This allows connecting to databases in private networks without exposing them publicly

Options Tab

Configure advanced connection behavior including timeouts, connection pooling, retry logic, and write concerns. These settings directly affect performance and reliability.

Timeout Settings

Field	Description	Default
Socket Timeout	Maximum time to wait for data during read operations. Increase for long-running queries and aggregations.	300 seconds
Connect Timeout	Maximum time to wait when establishing a new connection. Increase for slow networks.	30 seconds
Server Selection	Maximum time to wait for selecting appropriate server (replica set/sharded cluster).	30 seconds

Connection Pool Settings

Field	Description	Default
Max Pool Size	Maximum connections in the pool. Higher values allow more concurrent operations but use more memory.	100
Min Pool Size	Minimum connections to maintain. Keeps connections ready for faster response. Must be ≤ Max Pool Size.	0
Max Idle Time	Maximum time a connection can remain idle before being closed. Helps release unused connections.	10 minutes

Behavior Settings

Field	Description	Default
Retry Writes	Automatically retry write operations that fail due to network errors or replica set elections. Recommended for production.	Enabled
Retry Reads	Automatically retry read operations that fail due to network errors. Improves reliability for read-heavy workloads.	Enabled
Compress (zlib)	Compress data between client and server using zlib. Reduces network bandwidth but adds CPU overhead. Useful for slow networks.	Enabled
Load Balanced	Enable load balanced mode for MongoDB Atlas or other load balancer deployments. Only enable if connecting through a load balancer.	Disabled
App Name	Identifier sent to MongoDB server. Appears in logs, db.currentOp(), and profiler output. Useful for debugging and monitoring.	VisuaLeaf
Read-Only Mode	Locks the connection to read-only operations at the client. When enabled, VisuaLeaf disables document editing, insert, update, delete, drop, and DDL actions for every workspace opened against this connection. Ideal for production or shared credentials.	Disabled

Tip: Read-only mode is enforced by the UI even if the underlying MongoDB user has write privileges — combine it with a color-coded production environment label for an extra safety net. For server-enforced restrictions, pair it with a MongoDB user that only holds the read role (see the Access Control guide).

Write Concern Settings

Field	Description	Default
W (Acknowledgment)	majority: Wait for majority of replica set members (recommended) 1: Wait for primary only (faster, less safe) 0: No acknowledgment (fire-and-forget, not recommended)	majority
Timeout (ms)	Maximum time to wait for write concern acknowledgment. If exceeded, write returns error even if it succeeded.	No timeout
Journal	Wait for write to be committed to on-disk journal before acknowledging. Provides durability guarantee but adds latency.	Server Default

Reset to Defaults

Click the "Reset to Defaults" button at the top of the Options tab to restore all settings to their recommended values.

Testing Connections

The Test Connection feature validates your configuration before saving. It performs comprehensive checks across all connection aspects.

Test Connection Steps

1. Network Connectivity - Verifies the server is reachable at the specified host and port
2. SSH Tunnel - Establishes SSH tunnel if configured
3. SSL/TLS Handshake - Validates SSL certificates and establishes encrypted connection
4. Authentication - Verifies credentials using the selected authentication mechanism
5. Database Access - Confirms ability to list databases and collections
6. Permissions Check - Validates user has necessary privileges

Each step shows a status indicator (pending, in progress, success, or error). If any step fails, detailed error messages help diagnose the issue.

Connection Actions

Main Actions

• New Connection - Create a new database connection. Opens the connection form with default values.
• New Project - Create a new project container. Projects include a default environment which can be renamed and color-coded.
• Import - Import connections from a JSON file. Supports both individual connections and bulk imports.
• Export - Export all connections or selected connections to a JSON file for backup or sharing.
• Select All / Select None - Toggle selection of all connections for bulk operations like export or delete.

Connection Card Actions

Each connection card provides quick actions:

• Connect - Establish connection to the database
• Edit - Modify connection settings
• Clone - Duplicate connection with a new name
• Delete - Remove connection (with confirmation)
• Favorite - Mark as favorite for quick access

Drag and Drop Organization

Organize connections intuitively with drag and drop:

• Drag connections to different projects or environments
• Drag to "Ungrouped" to remove from projects
• Reorder projects by dragging the project headers
• Reorder environments within a project

Context Menus

Right-click on different elements to access context-specific actions:

Connection Context Menu

• Edit - Open connection form
• Clone - Duplicate connection
• Delete - Remove connection
• Test Connection - Validate settings

Project Context Menu

• New Connection - Create connection in first environment
• Add Environment - Create new environment in project
• Rename - Change project name
• Delete - Remove project (connections move to Ungrouped)

Environment Context Menu

• New Connection - Create connection in this environment
• Rename - Change environment name
• Delete - Remove environment (connections move to Ungrouped)

Ungrouped Context Menu

• New Connection - Create ungrouped connection

Search and Navigation

Search Functionality

Use the search bar in the header to quickly find connections:

• Type connection name to filter the list
• Press Enter or Arrow Down to jump to next match
• Press Arrow Up to jump to previous match
• Matched connection is highlighted and scrolled into view
• Search works across all view modes (All, Projects, Ungrouped)

Sidebar View Filters

The sidebar allows quick filtering of connections:

• All Connections - Shows everything
• By Project - Shows only project-organized connections
• Ungrouped - Shows only standalone connections

Sidebar Collapse

Click the chevron icon or the collapsed sidebar edge to toggle sidebar visibility. On mobile devices, the sidebar automatically collapses and appears as an overlay when opened.

Pro Tips

1. Color-code environments - Click the server icon next to environment names to assign colors (red for production, green for development, etc.). This visual distinction helps prevent accidentally working on the wrong environment.
2. Use connection string import - When setting up a new connection, paste your MongoDB connection string into the auto-fill field instead of manually entering each field. This is especially useful for MongoDB Atlas connections.
3. Test before saving - Always click "Test Connection" before saving to catch configuration errors early. Pay attention to the step-by-step progress to identify exactly where issues occur.
4. Organize with projects - Group related connections into projects (e.g., "E-Commerce App") with environments (Dev, Staging, Prod). This makes team collaboration and deployment workflows much clearer.
5. Export for backup - Regularly export your connections to a JSON file as backup. This also allows you to share connection configurations (without passwords) with team members.
6. Adjust timeouts for slow queries - If you run long aggregations or bulk operations, increase the Socket Timeout in the Options tab (e.g., 600 seconds) to prevent premature disconnections.
7. Use Read Preference wisely - For replica sets, use "Nearest" for best latency, "Secondary" to offload reads from primary, or "Primary" when you need the absolute latest data.
8. SSH tunneling for security - When connecting to databases in private networks or behind firewalls, use SSH tunneling instead of exposing MongoDB ports publicly. This adds an extra layer of security.
9. Double-click to rename - Double-click on project or environment names in the sidebar to quickly rename them inline without opening a context menu.
10. Save & Connect for speed - When creating a new connection, use the "Save & Connect" button to save your configuration and immediately connect in one action, skipping the connection manager reopening step.

Related Features

• Workspace Manager - Save and restore the UI state (open tabs, split views, expanded nodes) for different connection contexts
• Sidebar - After connecting, explore databases, collections, views, and GridFS buckets in the left sidebar tree
• Collection Activity - Once connected, view and edit documents in your collections
• VisuaLeaf Config - Configure application-wide preferences that affect all connections