# @joshdb/mongo

> MongoDB Provider for JOSH

Latest version **1.1.6** (published 2021-06-14) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @joshdb/mongo
pnpm add @joshdb/mongo
yarn add @joshdb/mongo
bun add @joshdb/mongo
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.1.6 |
| Published | 2021-06-14 |
| First published | 2021-01-15 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 21 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 74 |
| Author | Evelyne Lachance |
| Maintainers | eslachance |

## Links

- npm: https://www.npmjs.com/package/@joshdb/mongo
- Repository: https://github.com/eslachance/josh
- Homepage: https://github.com/eslachance/josh#readme
- Issues: https://github.com/eslachance/josh/issues
- npm.io page: https://npm.io/package/@joshdb/mongo

## Dependencies (1)

- [mongodb](https://npm.io/package/mongodb.md) ^3.6.3

## Recent versions

- 1.1.6 (latest) — 2021-06-14
- 3.0.0-next.8799c4a.0 (next) — 2025-11-02
- 3.0.0-next.b080164.0 — 2025-09-14
- 3.0.0-next.ba734aa.0 — 2025-09-07
- 3.0.0-next.6766723.0 — 2025-09-07
- 3.0.0-next.3b4d984.0 — 2025-09-07
- 3.0.0-next.ac86f9a.0 — 2025-08-31
- 3.0.0-next.0a154dd.0 — 2025-01-12
- 3.0.0-next.71f3b62.0 — 2025-01-12
- 3.0.0-next.4b1f96e.0 — 2024-11-03
- 3.0.0-next.829eea5.0 — 2024-11-03
- 3.0.0-next.b8543c0.0 — 2024-11-03
- 3.0.0-next.0a7d2a7.0 — 2024-10-27
- 3.0.0-next.d685c59.0 — 2024-10-27
- 3.0.0-next.214f98c.0 — 2024-10-27
- … 333 more at https://npm.io/package/@joshdb/mongo/versions

## README

# MongoDB Provider for JOSH

The MongoDB provider uses the `mongodb` module for persistent storage of JOSH data.

## Installation

The installation of the mongodb module is fairly straightforward and does not have any pre-requisites.

However, you must ensure that you have an available MongoDB server running. `josh-mongo` **does not** automatically create a server for you!

If you don't know, or don't *want*, to host a Mongo DB server instance, you can create a free one on [MongoDB Atlas](https://cloud.mongodb.com/). See specific instructions below for that service.

### Running the installer

In your project folder, you should be able to install using this command: 

```
npm i @joshdb/mongo
** OR **
yarn add @joshdb/mongo
```

## Usage

Using the mongo provider goes as such: 

```js
const Josh = require('@joshdb/core');
const JoshMongo = require('@joshdb/mongo');

const db = new Josh({
  name: 'testing',
  provider: JoshMongo,
  // See below for all provider options.
  providerOptions: {
    collection: 'testing',
    dbName: "yourclustername",
    url: "mongodb+srv://<username>:<password>@cluster0.0zbvd.mongodb.net/<dbName>?retryWrites=true&w=majority"
  }
});

db.defer.then( async () => {
  console.log(`Connected, there are ${await db.size} rows in the database.`);
});
```

## Provider Options

Let's try to make some sense of the options. In the above example I use the URL for the connection, using a Mongo Atlas cluster.

Here is a list of full options this provider supports: 

| Param | Type | Description |
| --- | --- | --- |
| [providerOptions] | <code>Object</code> | The Provider Options Object, with the below properties: |
| [providerOptions.collection] | <code>string</code> | Required. The name of the collection in which to save the data. |
| [providerOptions.dbName] | <code>string</code> | Optional, defaults to `josh`. The name of the database to which collections are written. |
| [providerOptions.user] | <code>string</code> | Optional if not using a URL. The username for the mongodb connection. |
| [providerOptions.password] | <code>string</code> | Optional if not using a URL. The password for the mongodb connection. |
| [providerOptions.port] | <code>string</code> | Optional, defaults to `27017`. The port where mongodb is hosted. |
| [providerOptions.host] | <code>string</code> | Optional, defaults to `localhost`. The host/machine/URL where the mongodb connection is located. Should never be an HTTP address! |
| [providerOptions.url] | <code>string</code> | Optional, single-line configuration. If used, ignores all other options except `options.collection`, and requires the full connection string to access the database, *including the database name* |

## Mongo Atlas Configuration

Mongo Atlas is a free mongodb hosting service made by, if that wasn't obvious, the Mongo people. While there are some limitations to the free service, it's still very useable for any small implementation.

The setup for Mongo Atlas goes something like this: 
- Get an account at [mongodb.com](https://www.mongodb.com/cloud/atlas)
- Once created, setup your cluster: 
  - Provider & Region: Up to you, I chose AWS in my test (but you might have a closer free region!). Make sure to select a "FREE TIER AVAILABLE" region!
  - Keep the M0 cluster tier (the only free one). You may select backups if you want, other additional options are paid.
  - Type in a cluster name of your choice. Something like `guidebot-cluster`.
  - Click **Create Cluster**.
  - Go make a sandwich, setup can take a while...
  - Click the Collection button in the middle of the page.
  - Click Create Database. Enter a name such as `guidebot-session` then a collection name such as `sessions`.
- Now that the cluster is created, we now need to get a connection string. But we need to create a user, which there's a wizard for. 
  - Click **Command Line Tools** at the top of the cluster window, then click **Connect Instructions**.
  - Click **Add your Current IP** if you're on the machine that will host your bot. Otherwise, click **Add a Different IP Address** and enter it on the left. Click **Add IP Address**.
  - Enter a database access *username* and *password*, then click **Create MongoDB User**.
  - Click **Choose a connection method**.
  - Click **Connect your Application**
  - Change the driver version to **3.0 or later**.
  - Your connection string is here! Keep the page open to copy it later in the setup stage.

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