# winston-mongodb

> A MongoDB transport for winston

Latest version **7.0.1** (published 2025-08-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install winston-mongodb
pnpm add winston-mongodb
yarn add winston-mongodb
bun add winston-mongodb
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 7.0.1 |
| Published | 2025-08-17 |
| First published | 2011-06-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.20.1 |
| Dependencies | 2 |
| Unpacked size | 34.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 295 |
| Author | Charlie Robbins |
| Maintainers | chjj, indexzero, dabh, yurijmikhalevich |
| Keywords | logging, sysadmin, tools, winston, mongodb, log, logger |

## Links

- npm: https://www.npmjs.com/package/winston-mongodb
- Repository: https://github.com/winstonjs/winston-mongodb
- Homepage: https://github.com/winstonjs/winston-mongodb#readme
- Issues: https://github.com/winstonjs/winston-mongodb/issues
- npm.io page: https://npm.io/package/winston-mongodb

## Dependencies (2)

- [mongodb](https://npm.io/package/mongodb.md) ^6.5.0
- [winston-transport](https://npm.io/package/winston-transport.md) ^4.4.0

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 7.0.1 (latest) — 2025-08-17
- 7.0.0 — 2025-06-10
- 6.0.0 — 2024-09-25
- 5.1.1 — 2023-01-27
- 5.1.0 — 2022-09-21
- 5.0.7 — 2021-02-11
- 5.0.6 — 2021-02-09
- 5.0.5 — 2020-09-13
- 5.0.4 — 2020-09-04
- 5.0.3 — 2020-08-21
- 5.0.2 — 2020-08-21
- 5.0.1 — 2019-11-06
- 5.0.0 — 2019-03-13
- 4.0.9 — 2019-03-13
- 4.0.8 — 2019-03-13
- … 57 more at https://npm.io/package/winston-mongodb/versions

## README

# winston-mongodb

A MongoDB transport for [winston][0].

Current version supports only mongodb driver version 3.x and newer and winston 3.x and newer.
If you want to use winston-mongodb with mongodb version 1.4.x use winston-mongodb <1.x. 
For mongodb 2.x use winston-mongodb <3.x.

## Motivation
`tldr;?`: To break the [winston][0] codebase into small modules that work
together.

The [winston][0] codebase has been growing significantly with contributions and
other logging transports. This is **awesome**. However, taking a ton of
additional dependencies just to do something simple like logging to the Console
and a File is overkill.  

## Usage
``` js
const winston = require('winston');
// Requiring `winston-mongodb` will expose winston.transports.MongoDB`
require('winston-mongodb');

const log = winston.createLogger({
  level: 'info',
  transports: [
    // write errors to console too
    new winston.transports.Console({format: winston.format.simple(), level:'error'})
  ],
});

// logging to console so far
log.info('Connecting to database...');

const MongoClient = require('mongodb').MongoClient;
const url = "mongodb://localhost:27017/mydb";

const client = new MongoClient(url);
await client.connect();

const transportOptions = {
  db: await Promise.resolve(client),
  collection: 'log'
};

log.add(new winston.transports.MongoDB(transportOptions));

// following entry should appear in log collection and will contain
// metadata JSON-property containing url field
log.info('Connected to database.',{url});

```

The MongoDB transport takes the following options. Only option `db` is required:

| Option |  Description                                     |
| ------ | :----------------------------------------------- |
| db     | **REQUIRED**. MongoDB connection uri, pre-connected `MongoClient` object or promise which resolves to a pre-connected `MongoClient` object. |
| dbName | The database name to connect to, defaults to DB name based on connection URI if not provided, ignored if using a pre-connected connection. |
| options| MongoDB connection parameters.<br/>Defaults to `{maxPoolSize: 2}`). |
| collection | The name of the collection you want to store log messages in.<br/>Defaults to `log`. |
| level  | Level of messages that this transport should log.<br/>Defaults to `info`. |
| silent | Boolean flag indicating whether to suppress output.<br/>Defaults to `false`. |
| storeHost | Boolean indicating if you want to store machine hostname in logs entry, if set to true it populates MongoDB entry with 'hostname' field, which stores os.hostname() value. |
| label  | If set to true, then label attribute content will be stored in `label` field, if detected in meta-data. |
| name | Transport instance identifier. Useful if you need to create multiple MongoDB transports. |
| capped | In case this property is true, winston-mongodb will try to create new log collection as capped.<br/>Defaults to `false`. |
| cappedSize | Size of logs capped collection in bytes.<br/>Defaults to 10,000,000. |
| cappedMax | Size of logs capped collection in number of documents. |
| tryReconnect | Will try to reconnect to the database in case of fail during initialization. Works only if __db__ is a string.<br/>Defaults to `false`. |
| decolorize | Will remove color attributes from the log entry message.<br/>Defaults to `false`. |
| leaveConnectionOpen| Will leave MongoClient connected after transport shuts down. |
| metaKey | Configure name of the field which is used to store metadata in the logged info object.<br/>Defaults to `metadata` to remain compatible with the [metadata format](https://github.com/winstonjs/logform/blob/master/examples/metadata.js) |
| expireAfterSeconds |Seconds before the entry is removed. Works only if __capped__ is not set. |

*Logging unhandled exceptions:* For logging unhandled exceptions specify
winston-mongodb as `handleExceptions` logger according to winston documentation.

## Querying and streaming logs

Besides supporting the main options from winston, this transport supports the
following extra options:

* __includeIds:__ Whether the returned logs should include the `_id` attribute
settled by mongodb, defaults to `false`.

## Installation

``` bash
  $ npm install winston
  $ npm install winston-mongodb
```

## [Changelog](https://github.com/winstonjs/winston-mongodb/releases)

#### Author: [Charlie Robbins](http://blog.nodejitsu.com)
#### Contributors: [Yurij Mikhalevich](https://github.com/yurijmikhalevich), [Kendrick Taylor](https://github.com/sktaylor), [Yosef Dinerstein](https://github.com/yosefd), [Steve Dalby](https://github.com/stevedalby)

[0]: https://github.com/winstonjs/winston

---
_Source: https://npm.io/package/winston-mongodb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._