MongoDB Compass for VS CodeAn independent MongoDB GUI for VS Code: connections, document browsing with a query bar, CRUD, an aggregation pipeline editor and visual stage builder with It also deploys and operates MongoDB: create standalone servers, replica sets and sharded clusters on Docker, as local processes, on Kubernetes (Percona Operator, MongoDB Community operator or a plain StatefulSet) or in MongoDB Atlas; see the cluster topology; add and remove members, shards and routers; change the primary; shard collections; and run rolling restarts and upgrades — with safety checks before every topology change.
Built on the official FeaturesConnections (Compass
|
| Docker | Local processes | Kubernetes | MongoDB Atlas | |
|---|---|---|---|---|
| Standalone / replica set / sharded | ✔ / ✔ / ✔ | ✔ / ✔ / ✔ | StatefulSet: standalone, replica set · Percona Operator: replica set, sharded · MongoDB Community: replica set | M0, Flex, dedicated replica set / sharded |
| Add / remove members, scale | ✔ (any member type) | ✔ | ✔ (through the operator, or the extension for StatefulSets) | node count 3 / 5 / 7 |
| Add / remove shards and routers | ✔ (shard draining included) | ✔ | Percona | shards |
| Start / stop | ✔ | ✔ | Percona (pause), StatefulSet (scale to 0) | pause / resume (M10+) |
| Restart node, rolling restart | ✔ | ✔ | ✔ (pod deletion) | — |
| Upgrade | rolling, node by node | rolling, from a new binaries folder | through the resource | major version |
| Failure simulation | kill, freeze (pause) | kill, freeze (SIGSTOP) | kill pod | test failover |
| Logs, shell, describe | ✔ | ✔ | ✔ | logs download, process info |
| Export | docker-compose with an init service | bash script | resource YAML | API request body |
- Docker: members share one network namespace, each mongod on its own port published on
127.0.0.1, so the replica set config useslocalhost:<port>and drivers can discover members and fail over from this machine. Authentication uses a generated keyfile and admin password (OS keychain) - Kubernetes: pick a kubectl context and namespace; the Percona Operator (1.22) or MongoDB Controllers for Kubernetes are installed on demand. Connections go through
kubectl port-forward(restarted automatically); members are reachable for the cluster view through per-pod forwards. Existing Percona / MongoDBCommunity resources and mongo StatefulSets can be attached. Contexts matchingmongoCompass.kubernetes.protectedContexts(default*prod*) require typing the context name before any change - Atlas: sign in with a service account or an API key; create clusters (with a database user and an IP access list entry) or import existing ones
- Rolling operations follow MongoDB's order: config servers, then shards, then routers; secondaries one at a time (waiting until healthy and caught up), then the primary after a step-down; the balancer is paused meanwhile
- Back up a deployment with mongodump (
--oplogon replica sets), copy its password or connection string, forget it without deleting anything, or destroy it (keeping data if you like)
Export to Language (Compass compass-export-to-language)
- mongosh, JavaScript, TypeScript, Python, Java, C#, Go, PHP, Ruby, Rust, Compass
Getting started
Requirements
- VS Code 1.85 or newer.
- A reachable MongoDB deployment. Standalone servers, replica sets, sharded clusters and MongoDB Atlas are supported by the official Node.js driver.
mongosh,mongodump, andmongorestoremust be installed separately and available onPATHfor the corresponding commands.mongodump/mongorestorerequire MongoDB Database Tools 100.3.0 or newer.- Deployments need, depending on the target: Docker (Docker Desktop or Engine),
mongod/mongosonPATHor inmongoCompass.local.binDir,kubectlwith a kubeconfig (plushelmfor the MongoDB Community operator), or an Atlas service account / API key. - Cluster administration needs a user with
clusterManager/clusterAdmin(sharding commands:clusterManageron a mongos).
npm install
npm run build # or: npm run watch
Press F5 in VS Code to launch the Extension Development Host.
- Click the MongoDB icon in the Activity Bar.
- Add Connection (or Connect with URI), e.g.
mongodb://localhost:27017. - Expand a connection → databases → collections.
- Click a collection to open the Documents view, or use the context menu for Aggregation / Indexes / Schema / Validation / Explain / Export.
Deploy a cluster
- In the Deployments view click New Deployment (
+). - Choose where it runs (Docker, local processes, Kubernetes or Atlas), the topology (standalone, replica set or sharded), the version and the number of members, shards and routers.
- When it is ready, choose Connect & show cluster: the deployment appears under Connections, its topology under Cluster, and the Cluster Overview panel opens.
- Manage it from the context menus: add or remove members and shards, make a member primary, restart nodes, simulate failures, run a rolling upgrade, export it as docker-compose / YAML, or destroy it.
Existing clusters work too: connect to them as usual to use the Cluster view, attach Kubernetes deployments with Attach Kubernetes Deployment, or import Atlas clusters with Import Atlas Clusters.
Configuration
| Setting | Default | Description |
|---|---|---|
mongoCompass.defaultLimit |
20 |
Page size for the documents view |
mongoCompass.maxTimeMS |
60000 |
Server-side query time limit |
mongoCompass.resultView |
list |
Default documents view mode |
mongoCompass.schemaSampleSize |
1000 |
Documents sampled for schema analysis |
mongoCompass.confirmDangerousOperations |
true |
Confirm drops/deletes |
mongoCompass.queryHistoryLimit |
200 |
Max history entries |
mongoCompass.hideSystemDatabases |
false |
Hide admin/local/config |
mongoCompass.showSystemCollections |
true |
Show system.* collections |
mongoCompass.readPreference |
primary |
Default read preference |
mongoCompass.connectionTimeoutMS |
30000 |
Server selection timeout |
mongoCompass.oidc.deviceAuthFlow |
false |
Allow OIDC sign-in with a code on another device (Remote SSH, WSL, containers, Codespaces) |
mongoCompass.oidc.redirectURI |
"" |
Redirect URI registered with the identity provider (default http://localhost:27097/redirect) |
mongoCompass.exportBatchSize |
1000 |
Export batch size |
mongoCompass.autoPreviewPipeline |
true |
Auto re-run aggregation preview |
mongoCompass.cluster.monitorIntervalSeconds |
30 |
Health checks of connected clusters (0 = off) |
mongoCompass.cluster.lagWarningSeconds |
30 |
Replication lag that triggers a warning |
mongoCompass.cluster.notifications |
true |
Notify about elections, members down / back, lag |
mongoCompass.deployments.refreshIntervalSeconds |
15 |
Deployments view refresh while visible (0 = off) |
mongoCompass.local.binDir |
"" |
Folder with mongod / mongos for local deployments |
mongoCompass.kubernetes.protectedContexts |
["*prod*"] |
Contexts where changes require typing the context name |
mongoCompass.kubernetes.perconaOperatorVersion |
1.22.0 |
Percona Operator version installed / used as crVersion |
mongoCompass.kubernetes.communityOperatorChart |
mongodb/mongodb-kubernetes |
Helm chart for MongoDBCommunity resources |
Architecture
src/
core/ # driver-agnostic services (mirrors Compass packages)
connectionManager.ts # compass-connections
connectionStore.ts # connection-storage (SecretStorage)
dataService.ts # mongodb-data-service
bsonParser.ts # mongodb-query-parser (shell syntax)
shellFormat.ts # BSON → mongosh source (lossless round-trip with bsonParser)
fieldPaths.ts # field paths + types sampled for autocomplete
schemaAnalyzer.ts # mongodb-schema
explainHelper.ts # explain-plan-helper
exportToLanguage.ts # bson-transpilers / export-to-language
importExport.ts # compass-import-export
queryHistory.ts # recent queries
myQueries.ts # my-queries-storage
config.ts, logger.ts, types.ts
cluster/
clusterService.ts # topology, elections, reconfig, sharding, balancer, zones, users, profiler
safety.ts # replica set config / majority checks before replSetReconfig
nodeClients.ts # direct connections to single members (+ host / credential resolvers)
clusterMonitor.ts # background health checks, election / lag notifications, status bar
deploy/
types.ts # DeploymentProvider interface, specs, records
registry.ts # deployments, passwords (SecretStorage), saved connections
managedCluster.ts # bootstrap / membership / shards for localhost:<port> layouts
rolling.ts # rolling restart / upgrade orchestration
docker/, local/ # Docker containers, local mongod processes
kubernetes/ # kubectl, port-forwards, Percona / Community / StatefulSet manifests
atlas/ # Atlas Admin API v2 client (service account / API key) and provider
explorer/ # TreeView (sidebar navigation): connections, cluster, deployments, tools
webviews/ # webview panels
baseWebview.ts # shared panel infra (CSP, messaging)
documentsPanel.ts # compass-crud
aggregationPanel.ts # compass-aggregations
dataPanel.ts # indexes/schema/validation/explain/stats/history/…
clusterPanel.ts # cluster overview: topology, members, sharding, users, config editor
documents/, aggregation/, dataview/ # webview front-ends
aggregation/builder.ts # visual pipeline builder ($lookup / $graphLookup forms)
shared/ # shared CSS + client helpers (highlighting, autocomplete)
commands/ # connection form, cluster and deployment commands (incl. the deployment wizard)
extension.ts # activation + command registration
Packaging
npm ci
npm run package # produces mongo-compass-<version>.vsix
Install the resulting file with Extensions: Install from VSIX... before publishing it.
Security and privacy
- Connection strings are stored in VS Code
SecretStorage, backed by the operating system credential store. - OIDC tokens are stored in
SecretStorageper connection and deleted with the connection, when its connection string changes, or with Forget OIDC Sign-in. They are sent only to Atlas, localhost, or the hosts of a connection you marked as trusted. - Query history and saved queries are stored locally in VS Code global storage.
- The extension does not include telemetry or send database contents to an external service.
- Database queries and commands are sent only to the MongoDB deployment selected by the user.
- Review the target database before using destructive operations such as drop, delete, restore,
$outor$merge. - Deployment admin passwords and Atlas credentials are stored in SecretStorage. Keyfiles and passwords reach containers and pods over stdin, never as command-line arguments; Docker ports are published on
127.0.0.1only. - Kubernetes changes in contexts matching
mongoCompass.kubernetes.protectedContextsneed the context name typed; deleting a deployment the extension did not create needs its name typed.
Support
Report defects through the repository issue tracker. Include the extension version, VS Code version, MongoDB server version and relevant output from MongoDB: Show Output Channel. Do not include credentials or unredacted connection strings.
If the extension saves you time, you can support its development on Boosty.
Notes & limitations
- This is an independent implementation inspired by MongoDB Compass; it is not affiliated with MongoDB, Inc.
- Atlas Search indexes require an Atlas deployment.
- The webview editors are lightweight textareas with their own highlighting and autocomplete rather than a full code editor; colours follow the VS Code theme's debug / symbol colours because webviews cannot read the editor's token theme.
- Autocomplete field names come from a sample of 100 documents, so rarely used fields may be missing. Collection names are not suggested inside
$lookup.fromin Text mode (the Builder form lists them). - Editing a pipeline in Builder mode reformats its text and drops comments.
- Data modeling diagrams, the embedded mongosh, and the GenAI assistant from Compass are out of scope.
- Kubernetes replica sets are reached through a port-forward to the primary with
directConnection=true; after a failover, reconnect to follow the new primary. Sharded clusters go through the mongos service. - With an operator (Percona, MongoDB Community) membership changes go through the custom resource — the operator would revert a manual
replSetReconfig. Kubernetes removes the highest pod ordinal when scaling down. - Local-process deployments keep running when VS Code closes; stop or destroy them from the Deployments view.
- Atlas M0 / Flex clusters can not be paused, scaled or failed over through the API.
License
MIT