{"id":42960,"library":"koa-mongo","title":"koa-mongo","description":"koa-mongo is a MongoDB middleware for Koa 2 that provides connection pool management via generic-pool. Version 1.9.3 is the latest stable release. It attaches an initialized MongoClient to `ctx.mongo` and a database handle to `ctx.db`, allowing direct access to native MongoDB driver methods. Supports both URI and separate host/port configuration. Compared to alternatives like koa-mongodb, koa-mongo is lightweight and explicitly integrates with Koa's middleware pattern, but relies on the deprecated MongoDB driver v3.x API and lacks built-in TypeScript types.","status":"maintenance","version":"1.9.3","language":"javascript","source_language":"en","source_url":"https://github.com/nswbmw/koa-mongo","tags":["javascript","koa","mongo","mongodb"],"install":[{"cmd":"npm install koa-mongo","lang":"bash","label":"npm"},{"cmd":"yarn add koa-mongo","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-mongo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for MongoDB driver; koa-mongo uses MongoClient from mongodb package","package":"mongodb","optional":true},{"reason":"Used for connection pool management; bundled dependency","package":"generic-pool","optional":false}],"imports":[{"note":"Default export; CommonJS require works directly (const mongo = require('koa-mongo')).","wrong":"const mongo = require('koa-mongo').default","symbol":"mongo","correct":"import mongo from 'koa-mongo'"},{"note":"ObjectId is a property on the default export, not a named export.","wrong":"import { ObjectId } from 'koa-mongo'","symbol":"mongo.ObjectId","correct":"import mongo from 'koa-mongo'; const { ObjectId } = mongo"},{"note":"CommonJS require works; no named exports available.","wrong":"","symbol":"mongo","correct":"const mongo = require('koa-mongo')"}],"quickstart":{"code":"const Koa = require('koa');\nconst mongo = require('koa-mongo');\n\nconst app = new Koa();\n\napp.use(mongo({\n  uri: process.env.MONGO_URI || 'mongodb://localhost:27017/test'\n}));\n\napp.use(async (ctx) => {\n  const result = await ctx.db.collection('users').insertOne({ name: 'example' });\n  ctx.body = { id: result.insertedId };\n});\n\napp.listen(3000, () => console.log('Server running on port 3000'));","lang":"javascript","description":"Demonstrates basic setup with URI configuration and a simple insert operation using ctx.db."},"warnings":[{"fix":"Replace insert() with insertOne() and remove() with deleteOne() or deleteMany(), and ensure _id is a string if needed.","message":"MongoDB driver v3.x methods like insert() and remove() are deprecated; use insertOne()/insertMany() and deleteOne()/deleteMany() instead.","severity":"deprecated","affected_versions":">=1.0"},{"fix":"Use the uri option for connection and pass native driver options as a second argument.","message":"The default connection uses host/port and db options; the URI option is preferred but may not support all MongoDB connection string options.","severity":"deprecated","affected_versions":"<1.9"},{"fix":"Use ctx.mongo.db('otherDb') to access a different database.","message":"ctx.db is bound to a specific database; if you need multiple databases, you must call ctx.mongo.db(dbName) manually.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Install @types/koa-mongo or write custom type declarations.","message":"Library does not export TypeScript type definitions; you may encounter type errors in TS projects.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use koa@2.x or higher.","message":"In koa-mongo 1.x, the middleware expects koa@2; it will not work with koa@1.","severity":"breaking","affected_versions":">=1.0"}],"env_vars":null,"search_vec":"'1.9.3':24 '2':13 'access':45 'allow':43 'altern':60 'api':86 'attach':31 'built':90 'built-in':89 'compar':58 'configur':57 'connect':16 'ctx.db':42 'ctx.mongo':36 'databas':39 'deprec':82 'direct':44 'driver':49,84 'explicit':71 'generic':21 'generic-pool':20 'handl':40 'host/port':56 'initi':33 'integr':72 'javascript':94 'koa':2,5,12,63,66,74,95 'koa-mongo':1,4,65 'koa-mongodb':62 'lack':88 'latest':27 'lightweight':69 'like':61 'manag':18 'method':50 'middlewar':10,76 'mongo':3,6,67,96 'mongocli':34 'mongodb':9,48,64,83,97 'nativ':47 'pattern':77 'pool':17,22 'provid':15 'releas':29 'reli':79 'separ':55 'stabl':28 'support':51 'type':93 'typescript':92 'uri':53 'v3.x':85 'version':23 'via':19","created_at":"2026-06-05T16:57:29.760654+00:00","updated_at":"2026-06-05T16:57:29.760654+00:00","problems":[{"fix":"Ensure mongo() middleware is added before any route handlers and that the MongoDB server is running.","cause":"Middleware not applied or ctx.db is undefined because connection failed.","error":"TypeError: Cannot read properties of undefined (reading 'collection')"},{"fix":"Run: npm install mongodb","cause":"mongodb is not installed as a peer dependency.","error":"MongoError: Cannot find module 'mongodb'"},{"fix":"Replace insert() with insertOne() or insertMany().","cause":"Using deprecated insert() method which is removed in newer mongodb driver versions.","error":"TypeError: ctx.db.collection(...).insert is not a function"},{"fix":"Provide user, pass, and authSource in options or use a URI with authentication.","cause":"Incorrect credentials or authSource not set.","error":"MongoError: Authentication failed."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/nswbmw/koa-mongo#readme","github":"https://github.com/nswbmw/koa-mongo","docs":null,"changelog":null,"pypi":null,"npm":"koa-mongo","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}