mongodb

The internal:mongodb plugin executes operations against a MongoDB database using the official MongoDB Node.js driver.

Registration

x-plenum-upstream:
  kind: "plugin"
  plugin: "internal:mongodb"
  options:
    host: "${{ env.DB_HOST }}"
    port: "${{ env.DB_PORT }}"
    database: "${{ env.DB_NAME }}"
    user: "${{ env.DB_USER }}"
    password: "${{ env.DB_PASSWORD }}"
  permissions:
    env: ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"]
    net: ["${{ env.DB_HOST }}"]

Connection config

Options passed to the plugin at registration become the MongoDB connection configuration:

Field	Type	Default	Description
`uri`	`string`	—	Full MongoDB connection URI. If set, `host`, `port`, `user`, `password` are ignored
`host`	`string`	`"localhost"`	Database host
`port`	`string \| number`	`27017`	Database port
`database`	`string`	`"test"`	Database name. If using `uri`, defaults to the path segment of the URI
`user`	`string`	—	Database user (combined with `password` in the connection URI)
`password`	`string`	—	Database password

Connection is verified at startup by sending a ping command. If the connection fails, the gateway refuses to start.

Per-operation config

Pass operation configuration via x-plenum-backend:

actions:
  - target: "$.paths['/users'].get"
    update:
      x-plenum-backend:
        collection: "users"
        operation: "find"
        filter:
          role: "admin"
  - target: "$.paths['/users/{id}'].get"
    update:
      x-plenum-backend:
        collection: "users"
        operation: "findOne"
        filter:
          _id: "${{path.id}}"
        returns: "/0"

Field	Type	Default	Description
`collection`	`string`	— (required)	MongoDB collection name
`operation`	`string`	— (required)	One of: `find`, `findOne`, `insertOne`, `updateOne`, `deleteOne`
`filter`	`object`	`{}`	Query filter document. `${{...}}` tokens are resolved by the gateway before the plugin runs
`document`	`object`	`{}`	Document for `insertOne` and `updateOne` operations. Tokens resolved by gateway
`fields`	`Record<string, string>`	—	Map field names in results
`returns`	`string`	—	JSON Pointer. `"/0"` returns the first document as an object instead of an array

Operations

find

Returns an array of matching documents:

x-plenum-backend:
  collection: "users"
  operation: "find"
  filter:
    role: "admin"

findOne

Returns a single document as an array element (resolved to plain object if returns: "/0"):

x-plenum-backend:
  collection: "users"
  operation: "findOne"
  filter:
    _id: "${{path.id}}"
  returns: "/0"

Returns 404 if no document matches.

insertOne

Inserts a document and returns it with the generated _id:

x-plenum-backend:
  collection: "users"
  operation: "insertOne"
  document:
    name: "${{body.name}}"
    email: "${{body.email}}"

updateOne

Updates a matching document using $set and returns the updated document:

x-plenum-backend:
  collection: "users"
  operation: "updateOne"
  filter:
    _id: "${{path.id}}"
  document:
    name: "${{body.name}}"

Returns 404 if no document matches the filter.

deleteOne

Deletes a matching document. Returns 404 if no document matched:

x-plenum-backend:
  collection: "users"
  operation: "deleteOne"
  filter:
    _id: "${{path.id}}"

Field mapping

Rename fields in the result using fields:

x-plenum-backend:
  collection: "users"
  operation: "find"
  fields:
    _id: "id"
    email_address: "email"

Returns pointer

Use returns: "/0" to unwrap the result array. Works with findOne, insertOne, and updateOne where a single document is expected:

x-plenum-backend:
  collection: "users"
  operation: "findOne"
  filter:
    _id: "${{path.id}}"
  returns: "/0"

Error responses

Status	Condition
`200`	Operation succeeded
`404`	Document not found (`findOne`, `updateOne`, `deleteOne`) or `returns: "/0"` resulted in `null`
`500`	Client not initialised, missing config, or operation error

The 500 response body includes the error message from the driver.