MongoDB Atomic Updates
A single-document update is atomic. Put a capacity condition in the same operation as its decrement instead of relying on an earlier read.
How it works
K1 starts with three free units. A request for two matches the available>=2 filter and decrements the document. A second request for two then matches nothing and leaves the remaining unit intact. The teaching amounts are fixed positive integers; a real request boundary must validate its quantity and identity before building the authored filter.
Run in a separate MongoDB lab
Start a disposable lab automatically: in a separate empty learning folder, save package.json, run-lab.mjs and this lesson’s source with its displayed filename. Run npm install --ignore-scripts, then node run-lab.mjs atomic-updates.mongosh.js. mongosh lessons also need mongosh installed on PATH. The launcher downloads the pinned MongoDB server on first use, starts one authenticated loopback replica-set member, supplies private child-process credentials, runs the lesson and stops that server. Its cache, generated data and diagnostic files stay in the private .bhylu-mongodb-lab folder; it installs no service. Review downloaded code before executing it.
The following manual connection route is an alternative for readers who already have a suitable separate lab instance.
The reviewed baseline is MongoDB 8.0.12, mongosh 2.14.0, Node.js 22.15.1 and driver 6.17.0. These are tested versions, not a newest-release claim. Use a private authenticated learning server on 127.0.0.1 and an explicit non-default port, not your normal database or an Atlas project. These scripts intentionally refuse port 27017 and remote hosts. Bhylu has no MongoDB browser runner; a plain JavaScript playground cannot provide this database.
Supply your own lab connection through the child process environment variable BHYLU_MONGO_URI and set BHYLU_MONGO_LAB=YES. Keep credentials private; do not save them in source or public commands. The lab role needs permission to create and drop its generated databases and collections. No PHP, Apache or normal XAMPP service change is needed.
Save the complete download as atomic-updates.mongosh.js and run mongosh --nodb --norc --quiet --file atomic-updates.mongosh.js in a separate child process. It reads its private connection from the environment. The file uses actual mongosh APIs; it is not a Node.js module.
Every run generates a new bhylu_mongo_ database name, refuses an existing collection set, writes its own ownership marker, seeds the complete fictional dataset and finally removes only that owned database after checking the marker. Do not change the generated name to a valuable existing database. Closing the child process releases its client connections.
Example
// Bhylu MongoDB 8.0.12 lab: Atomic Updates
// Run only against your separate authenticated loopback learning instance.
async function main() {
if (process.env.BHYLU_MONGO_LAB !== "YES")
throw new Error("Set BHYLU_MONGO_LAB=YES for a private lab");
const raw = process.env.BHYLU_MONGO_URI;
if (!raw)
throw new Error("Set BHYLU_MONGO_URI privately; do not commit credentials");
const address = new URL(raw);
if (
address.protocol !== "mongodb:" ||
address.hostname !== "127.0.0.1" ||
!address.port ||
address.port === "27017"
)
throw new Error("Use a private loopback MongoDB on a non-default port");
const marker = new ObjectId().toString(),
dbName = "bhylu_mongo_" + marker;
const connection = new Mongo(raw);
const db = connection.getDB(dbName);
let owned = false;
const emit = (value) => print(JSON.stringify(value));
try {
if ((await db.getCollectionNames()).length)
throw new Error("Refusing an existing database");
await db.createCollection("_bhylu_owner");
await db.getCollection("_bhylu_owner").insertOne({ _id: marker });
owned = true;
await db.getCollection("kits").insertMany([
{
_id: "K1",
label: "Birdwatch pack",
category: "observation",
available: 3,
condition: "ready",
location: { room: "North", shelf: 2 },
tags: ["outdoor", "compact"],
notes: null,
checks: [
{ kind: "lens", passed: true },
{ kind: "strap", passed: false },
],
},
{
_id: "K2",
label: "Stream sampler",
category: "sampling",
available: 1,
condition: "ready",
location: { room: "South", shelf: 1 },
tags: ["outdoor", "washable"],
checks: [
{ kind: "lens", passed: false },
{ kind: "strap", passed: true },
],
},
{
_id: "K3",
label: "Soil survey set",
category: "sampling",
available: 0,
condition: "repair",
location: { room: "North", shelf: 3 },
tags: ["washable"],
notes: "Replace pouch",
checks: [],
},
{
_id: "K4",
label: "Weather logger",
category: "observation",
available: 2,
condition: "ready",
location: { room: "South", shelf: 2 },
tags: [],
notes: null,
checks: [],
},
]);
await db.getCollection("members").insertMany([
{ _id: "M1", name: "Asha", area: "North" },
{ _id: "M2", name: "Dev", area: "South" },
{ _id: "M3", name: "Noor", area: "West" },
]);
await db.getCollection("loans").insertMany([
{
_id: "L1",
kitId: "K1",
memberId: "M1",
quantity: 1,
status: "returned",
openedAt: new Date("2026-01-10T09:00:00Z"),
},
{
_id: "L2",
kitId: "K1",
memberId: "M2",
quantity: 2,
status: "open",
openedAt: new Date("2026-01-11T09:00:00Z"),
},
{
_id: "L3",
kitId: "K2",
memberId: "M1",
quantity: 1,
status: "open",
openedAt: new Date("2026-01-11T10:00:00Z"),
},
{
_id: "L4",
kitId: "K3",
memberId: "M2",
quantity: 1,
status: "returned",
openedAt: new Date("2026-01-10T11:00:00Z"),
},
{
_id: "L5",
kitId: "K4",
memberId: null,
quantity: 1,
status: "planned",
openedAt: new Date("2026-01-12T09:00:00Z"),
},
]);
const kits = db.getCollection("kits"),
loans = db.getCollection("loans"),
members = db.getCollection("members");
// Lesson commands begin here.
const first = await kits.updateOne(
{ _id: "K1", available: { $gte: 2 } },
{ $inc: { available: -2 } },
);
const second = await kits.updateOne(
{ _id: "K1", available: { $gte: 2 } },
{ $inc: { available: -2 } },
);
emit({
accepted: [first.modifiedCount, second.modifiedCount],
remaining: (await kits.findOne({ _id: "K1" })).available,
});
} finally {
if (owned) {
const owner = await db
.getCollection("_bhylu_owner")
.findOne({ _id: marker });
if (!owner || !/^bhylu_mongo_[a-f0-9]{24}$/.test(dbName))
throw new Error("Refusing cleanup without matching ownership marker");
await db.dropDatabase();
}
// The noninteractive mongosh process closes its connection when it exits.
}
}
main().catch((error) => {
console.error(error.message);
exit(1);
});
Focus on the lesson operations
This excerpt omits connection guards, seed and cleanup. Use the complete download to run it.
const first=await kits.updateOne({_id:'K1',available:{$gte:2}},{$inc:{available:-2}});
const second=await kits.updateOne({_id:'K1',available:{$gte:2}},{$inc:{available:-2}});
emit({accepted:[first.modifiedCount,second.modifiedCount],remaining:(await kits.findOne({_id:'K1'})).available});
Expected result
{"accepted":[1,0],"remaining":1}The script emits JSON so these small results are unambiguous. Interactive shell formatting may look different. Object IDs and owned database names are not hard-coded expected values.
The database decides the match and write together. Two real concurrent contenders are checked in the separate boundary review. This rule protects the stock document only; a separate loan record requires an appropriate cross-document transaction or another deliberate consistency design.