Chapter 19 · Firestore with MongoDB Compatibility: Drivers, MQL/BSON, Tools, and Serverless Differences

mongosh, Compass, mongoimport / export, mongodump / restore, Mongoose, and Tool Compatibility Boundaries

Use a tool-by-tool compatibility contract for mongosh, Compass, MongoDB Database Tools, and Mongoose; distinguish supported connection/use cases from unsupported admin, topology, schema-validation, and ODM assumptions.

Advanced · 180–240 minutesMongoDB compatibility · MQL/BSON · tools · serverless differencesNode 22.23.2 · mongodb 6.21.0 · Mongoose 8.24.4 · mongosh 2.10.0gcloud 585.0.0 · managed MongoDB-compatible database optional · local contract harness mandatoryLast reviewed: 17 September 2026

1. AtlasMart problem: “the tool connects” does not mean its whole workflow is supported

Execution and safety note

Use the Emulator Suite, a Firebase demo project, or an isolated test project for destructive, security-sensitive, billing-sensitive, migration, backup/restore, or write-heavy exercises unless the lesson explicitly marks managed verification as required. Treat shown output as expected evidence unless it is explicitly identified as captured output, and re-check current Firebase/Google Cloud edition, mode, quota, pricing, and security documentation before production execution.

A developer opens Compass, another runs mongosh, operations uses mongodump, and the app uses Mongoose plugins. All of these appear on the supported-tools page. That is useful—but it does not grant blanket compatibility to every panel, admin command, schema validator, session helper, plugin, index option, or backup assumption those tools can generate. AtlasMart needs tool contracts that state which workflows are supported and which must be replaced.

Chapter 19 reproducibility baseline · reviewed 17 September 2026

AtlasMart keeps the course-wide project identity demo-atlasmart-firestore. The mandatory compatibility harness is local/no-cost and targets Node.js 22.23.2 LTS with mongodb@6.21.0, a current Firestore-supported 6.x Node driver. Tool examples pin mongosh 2.10.0, MongoDB Compass 1.50.0, Mongoose 8.24.4, Google Cloud CLI 585.0.0, and retain Firebase CLI 15.30.0 for course continuity. The optional managed database is atlasmart-mongo-lab, Enterprise edition with MongoDB-compatible data access in an explicitly chosen supported location such as us-central1. Re-check location availability before creation.

Managed-service boundary

Unlike the Native-mode labs, current official documentation does not provide a Local Emulator Suite endpoint that emulates the MongoDB wire/API compatibility surface. Therefore the mandatory lab uses deterministic BSON/query/index/compatibility fixtures and executable contract tests without credentials. A real Firestore with MongoDB compatibility database is an optional verification layer: database creation requires an actual Google Cloud/Firebase project and billing enabled, and connection/authentication uses SCRAM or Google Cloud identity. No lesson fabricates a successful handshake, Query Explain result, billed unit count, p95/p99 latency, or tool connection that was not actually executed.

Learning outcomes

Use mongosh and Compass as compatibility/query tools without assuming MongoDB server administration features.

Separate MongoDB Database Tools data movement from Firestore managed export/import and disaster recovery.

Pin Mongoose to a supported underlying driver line and test generated queries/indexes/plugins.

Capture unsupported tool commands as expected contract failures.

Design credential handling so GUI/CLI convenience does not leak database passwords or access tokens.

2. Supported tool list is an entry point, not a guarantee matrix

Tool	Officially listed	Safe default use	Compatibility questions to test
mongosh	Yes	Interactive CRUD/query/explain scripts	Admin helpers, unsupported commands, shell-generated options
MongoDB Compass	Yes	Browse data, run supported queries, Query Explain	Server/admin panels may depend on unsupported stats/topology commands
mongoimport / mongoexport	Yes	Bounded data transfer	Extended JSON/BSON fidelity, indexes/security not automatically equivalent
mongodump / mongorestore	Yes	Logical dump/restore workflows	Do not confuse with Firestore managed backups/PITR or assume all metadata maps identically
Mongoose	Yes	ODM models/queries using supported operations	Plugins, validators, index options, transactions, middleware side effects

3. `mongosh 2.10.0`: use scripts that ask only supported questions

mongosh is a shell around MongoDB driver behavior. The current shell itself has many helpers for sharding and server administration that are irrelevant or unsupported against Firestore. AtlasMart maintains a small script of known-supported commands so operator muscle memory does not accidentally become a migration dependency.

atlasmart-smoke.mongodb.js

printjson(db.runCommand({ hello: 1 }));printjson(db.runCommand({ buildInfo: 1 }));printjson(db.products.find({tenantId:"tenant-a"}).sort({_id:1}).limit(3).toArray());printjson(db.products.getIndexes());printjson(db.products.find({tenantId:"tenant-a"}).explain("executionStats"));

Wrong approach

Running sh.status(), serverStatus(), profiler controls, replica-set commands, or shard-management helpers because “mongosh supports them.” Tool capability and service capability are different sets.

4. Compass: excellent query surface, incomplete operational truth

Compass can connect to the compatible endpoint and is useful for document inspection, filters, aggregations, indexes, and explain where supported. But panels that expect MongoDB server statistics, topology, profiler, storage-engine, or role-management commands may be unavailable or semantically different. AtlasMart's runbook labels every Compass screenshot by purpose: data/query evidence, not “server health proof.”

Compass connection checklist

1. Use the exact Firestore connection string for atlasmart-mongo-lab.2. Confirm TLS and loadBalanced=true.3. Confirm retryWrites=false.4. Do not paste a long-lived password into screenshots/tickets.5. Run the same bounded query used by the automated contract.6. Compare result IDs, then use Explain for managed evidence.7. Do not interpret unavailable server-stat panels as a database outage.

5. Database Tools: data movement is not migration completeness

mongoexport/mongoimport and mongodump/mongorestore are listed supported tools. They can help with small rehearsals, fixtures, and logical movement. They do not automatically translate source IAM/users/roles, application secrets, every index option, unsupported BSON, operational dashboards, backup policy, or all MongoDB server metadata. Managed Firestore export/import is a different service with its own billing, Cloud Storage, and recovery semantics.

bounded tool rehearsal · optional managed lab

# Never point this at production by accident.mongoexport --uri "$ATLASMART_MONGO_URI" \  --collection compat_products \  --query '{"testRun":"ch19-tools"}' \  --out compat_products.jsonmongoimport --uri "$ATLASMART_MONGO_URI" \  --collection compat_products_copy \  --file compat_products.jsonmongodump --uri "$ATLASMART_MONGO_URI" \  --collection compat_products \  --out ./dump-ch19# Restore only into the disposable lab namespace/collection plan after review.

Record counts and sampled canonical values before/after. A successful command without data verification is not a restore test.

6. Mongoose compatibility: the ODM can generate unsupported behavior for you

Mongoose is officially listed as a supported tool, but an ODM is not a semantic shield. Schemas, middleware, validators, population patterns, plugins, index declarations, sessions, and query helpers eventually produce driver operations. AtlasMart pins Mongoose 8.24.4 because its underlying driver generation remains compatible with the documented 6.x line, then tests the exact model behaviors the app uses.

minimal Mongoose compatibility model

import mongoose from "mongoose";await mongoose.connect(process.env.ATLASMART_MONGO_URI, {  serverSelectionTimeoutMS: 10000});const Product = mongoose.model("CompatProduct", new mongoose.Schema({  _id: String,  tenantId: {type:String, required:true},  sellerId: {type:String, required:true},  name: {type:String, required:true},  price: Number,  stock: Number,  published: Boolean}, { collection:"compat_products", versionKey:false }));const rows = await Product.find({tenantId:"tenant-a", published:true})  .sort({price:1, _id:1}).lean();console.log(rows.map(x => x._id));

7. Do not assume MongoDB schema validation exists because Mongoose validates

Mongoose validation executes in application code. It does not prove a database-side MongoDB validator is available or enforced for writes from other clients. Current compatibility tables do not support every MongoDB schema-validation surface (for example, $jsonSchema query support is not universal, and create-collection validator options differ). If AtlasMart requires cross-client schema enforcement, it must design that requirement explicitly rather than relying on ODM validation as a database invariant.

8. Tool compatibility test ledger

tool-ledger.json

[  {"tool":"mongosh","version":"2.10.0","case":"find+sort+limit","expected":"supported"},  {"tool":"mongosh","version":"2.10.0","case":"serverStatus","expected":"unsupported"},  {"tool":"Compass","version":"1.50.0","case":"find+explain","expected":"supported"},  {"tool":"mongoexport","case":"bounded JSON export","expected":"supported"},  {"tool":"mongodump","case":"single collection dump","expected":"supported"},  {"tool":"mongoose","version":"8.24.4","case":"model find/update","expected":"test exact app behavior"}]

Each ledger row eventually gets observed output, timestamp, database UID/ID, tool version, and a redacted error code when failure is expected. This makes tool upgrades auditable.

9. Failure injection: choose a tool feature the service does not implement

A useful lab is to issue serverStatus or another clearly unsupported administrative command in the isolated managed database. The test passes when it receives an unsupported-command outcome and the runbook says “not a health signal.” This inoculates operators against treating MongoDB server runbooks as Firestore runbooks.

negative-tool-contract.mjs

const negativeCases = [  {name:"serverStatus", migrationMeaning:"replace with Cloud Monitoring / Firestore observability"},  {name:"mapReduce", migrationMeaning:"replace query logic"},  {name:"GridFS", migrationMeaning:"move blob storage to object storage"}];for (const c of negativeCases) console.log(`EXPECTED_UNSUPPORTED ${c.name}: ${c.migrationMeaning}`);

10. Security: convenience tools are credential exfiltration surfaces if handled casually

SCRAM passwords are generated secrets. Temporary Google Cloud access tokens are short-lived but still sensitive. Do not paste URIs with credentials into issue trackers, shell history, screenshots, or course files. Prefer OIDC/service identity for managed application workloads; for human diagnostics use short-lived credentials where practical and scope IAM narrowly.

Verification checklist

Every tool has a pinned version or an evidence-recorded version.
Supported-data operations and unsupported-admin operations are separated.
Dump/export tests validate counts and values, not just exit status.
Mongoose model/query/plugin behavior is covered by tests.
No database credential appears in source, screenshots, shell transcript, or ZIP.
MongoDB server monitoring/runbooks are not reused without translation.

Bridge to Lesson 4

The tools now have explicit boundaries. Lesson 4 goes deeper than tool support and compares the database semantics that matter most in production: isolation/read concern, retry behavior, indexing, change streams, search, errors, scaling, and operational ownership.

Knowledge check

Does official support for Compass mean every Compass panel works identically?
Is mongodump equivalent to Firestore managed backup/PITR?
Why test Mongoose plugins?
What proves a tool restore worked?
What should an unsupported serverStatus result mean?

Review the answers

1. No. Data/query workflows can be supported while server/topology/admin panels rely on unsupported commands.

2. No. They are different recovery/data-movement mechanisms with different metadata, billing, RPO/RTO, and operational workflows.

3. They can generate driver commands/index options/query patterns beyond the simple model APIs that were initially validated.

4. Counts, sampled/canonical values, required indexes, and application query tests—not merely a zero exit code.

5. Use Firestore/Google Cloud observability instead; do not classify it as database failure.

Summary and next step

This lesson established the working contract for mongosh, Compass, mongoimport/export, mongodump/restore, Mongoose, and Tool Compatibility Boundaries. Keep its edition/mode assumptions, trust boundary, verification evidence, and operational constraints explicit when reusing the pattern.

Next, continue to Behavior Differences from MongoDB: Commands, Transactions/Features, Indexing, Change Semantics, and Operational Model.

Authoritative references

Keep knowledge open

Help the academy stay free and grow.

If these tutorials save you time, a small donation supports new lessons, technical review, diagrams, examples, and long-term maintenance.

ETHEthereum / ERC-20 only

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0

Send only Ethereum or ERC-20 compatible assets to this address.