🌜
🌞
gatsby-source-mongodb

gatsby-source-mongodb

v4.20.0

Source plugin for pulling data into Gatsby from MongoDB collections

npm install gatsby-source-mongodb

README

gatsby-source-mongodb

Source plugin for pulling data into Gatsby from MongoDB collections.

Installation

npm install gatsby-source-mongodb

How to use

// In your gatsby-config.js
module.exports = {
  plugins: [
    /*
     * Gatsby's data processing layer begins with “source” plugins. Here we
     * setup the site to pull data from the "documents" collection in a local
     * MongoDB instance
     */
    {
      resolve: `gatsby-source-mongodb`,
      options: { dbName: `local`, collection: `documents` },
      query: { documents: { as_of: { $gte: 1604397088013 } } },
    },
  ],
}

multiple collections

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-mongodb`,
      options: { dbName: `local`, collection: [`documents`, `vehicles`] },
    },
  ],
}

Plugin options

  • connectionString: if you need to use a connection string compatible with later versions of MongoDB, or for connections to MongoDB Atlas, you can enter the entire string, minus the dbName and extraParams. In this case, the authentication information should already be embedded in the string ex. mongodb+srv://<USERNAME>:<PASSWORD>@<SERVERNANE>-fsokc.mongodb.net. Pass dbName and extraParams as options per below.
  • dbName: indicates the database name that you want to use
  • typePrefix: the prefix you want to add to your entity types (dbName by default)
  • collection: the collection name within Mongodb, this can also be an array for multiple collections
  • query: add a query when retriving a collection. This is a key value object where key's are collection names, and value is the query object. Defaults to {} (i.e. the whole collection)
  • server: contains the server info, with sub properties address and port ex. server: { address: ds143532.mlab.com, port: 43532 }. Defaults to a server running locally on the default port.
  • auth: the authentication data to login a Mongodb collection, with sub properties user and password. ex. auth: { user: admin, password: 12345 }
  • extraParams: useful to set additional parameters for the connection, like authSource, ssl or replicaSet (needed for connecting to MongoDB Atlas db as a service), ex: extraParams: { replicaSet: test-shard-0, ssl: true, authSource: admin }. These are the types of options that can be appended as query parameters to the connection URI: https://docs.mongodb.com/manual/reference/connection-string/#connections-connection-options
  • clientOptions: for setting options on the creation of a MongoClient instance. By default, we pass useNewUrlParser: true to handle the various connection URI's necessary for newer versions of MongoDB Atlas, as well as useUnifiedTopology: true to opt in to using the MongoDB driver's new topology engine, which improves server discovery and monitoring. You can override the default by passing either an empty object literal or filled with other valid connection options. All options specified in the MongoClient documentation are valid for usage.
  • preserveObjectIds: for preserving nested ObjectIDs within documents, set this to the Boolean true, ex: preserveObjectIds: true.

Mapping mediatype feature

Gatsby supports transformer plugins that know how to transform one data type to another e.g. markdown to html. In the plugin options you can setup "mappings" for fields in your collections. You can tell Gatsby that a certain field is a given media type and with the correct transformer plugins installed, your data will be transformed automatically.

Let's say we have a markdown field named body in our mongoDB collection documents. We want to author our content in markdown but want to transform the markdown to HTML for including in our React components.

To do this, we modify the plugin configuration in gatsby-config.js like follows:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-mongodb`,
      options: {
        dbName: `local`,
        collection: `documents`,
        // highlight-start
        map: {
          documents: { body: `text/markdown` },
        },
        // highlight-end
      },
    },
  ],
}

The GraphQL query to get the transformed markdown would look something like this.

query ($id: String!) {
  mongodbCloudDocuments(id: { eq: $id }) {
    id
    name
    url
    body {
      childMarkdownRemark {
        id
        html
      }
    }
  }
}

How to query your MongoDB data using GraphQL

Below is a sample query for fetching all MongoDB document nodes from a db named 'Cloud' and a collection named 'documents'.

query {
  allMongodbCloudDocuments {
    edges {
      node {
        id
        url
        name
      }
    }
  }
}

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
53.6K
Community Interest
62.7K
Number of Forks
10.4K

Maintenance

Commits
10/219/220200
Last Commit
Open Issues
92
Closed Issues
13.5K
Open Pull Requests
156
Closed Pull Requests
3,510

Versions

Versions Released
10/219/2208
Latest Version Released
Aug 2, 2022
Current Tags
latest4.20.0
next4.21.0-next.0
v3rc3.0.0-v3rc.0
otp-test2.1.10-otp-test.31
pr-207412.1.30-pr-20741.260
alpha-qe-sm3.14.0-alpha-qe-sm.46
alpha-9689ff4.0.0-alpha-9689ff.13
alpha-ts-jit4.6.0-alpha-ts-jit.60
image-helpers2.5.0-image-helpers.13
image-service4.8.0-alpha-image-service.24
unifiedroutes2.2.3-unifiedroutes.76
wp-image-cdn-auth4.15.0-alpha-wp-image-cdn-auth.48
drupal-self-reference4.18.0-alpha-drupal-self-reference.18

Contributors

KyleAMathews
KyleAMathews
Commits: 3,014
pieh
pieh
Commits: 884
wardpeet
wardpeet
Commits: 506
LekoArts
LekoArts
Commits: 436
sidharthachatterjee
sidharthachatterjee
Commits: 436
m-allanson
m-allanson
Commits: 354
DSchau
DSchau
Commits: 354
muescha
muescha
Commits: 301
vladar
vladar
Commits: 268
shannonbux
shannonbux
Commits: 268
pvdz
pvdz
Commits: 240
ascorbic
ascorbic
Commits: 240
fk
fk
Commits: 217
ChristopherBiscardi
ChristopherBiscardi
Commits: 186
tesseralis
tesseralis
Commits: 158