gatsby-source-harperdb
Description
HarperDB is a fast, flexible database that allows you to perform rapid application development, distributed computing, SaaS, and many more. On the other hand, Gatsbyjs is a React-based framework that allows you to build fast, secure, and robust websites.
Gatsby's massive plugin ecosystem allows us to pull data from several data sources, avail themes, and many more use-cases. The gatsby-source-harperdb
plugin allows you to use the HarperDB
as the data source so that a Gatsby project can pull the data at the build time.
It will help any Gatsbyjs
app to create a prebuilt markup with the data from HarperDB
.
Learning Resources
Here a few learning resources you may find helpful,
How to install
To install the plugin for your Gatsby project, use this command,
npm i gatsby-source-harperdb
# If you are using yarn, try this,
# yarn add gatsby-source-harperdb
Please note: Gatsby
documentation uses npm
for installation. It is the recommended approach for plugins as well. However, my test with yarn
also went well.
When do I use this plugin?
You would use this plugin when you want to fetch data from the HarperDB
in advance at the build time. The gatsby build
command will build the project and create prebuilt markups along with the data. Thus, it will make the initial page load of your application faster. The bonus is, you achieve Jamstack
as well.
Please note: To get the dynamic data at a later point of time from the
HarperDB
, you need to perform regular calls usingaxios
,node-fetch
, etc.
Examples of usage
In your Gatsbyjs project, make an entry in the plugins
array in the gatsby-config.js
file.
plugins: [
...
{
resolve: `gatsby-source-harperdb`,
options: {
secret: "_YOUR_HARPERDB_SECRET_KEY_",
url: "_YOUR_HARPERDB_URL_",
payload: {
"operation": "sql",
"sql":"SELECT * FROM library.book"
},
type: "books"
},
},
],
The options are,
-
secret
: Provide theHarperDB
secret key. After setting up an instance on HarperDB, you can find it in theexample code
section. We use this secret key in theAuthorization
header. -
url
: The URL to connect to the HarperDB instance. For example, if you have created an instance on the cloud, you may have got a URL like,https://xxxxxx.harperdbcloud.com
-
payload
: Here, you pass the type of operation and the query to perform on the HarperDB database. In most cases, you would use aSELECT
query here. You can also pass a query using joins. -
type
: It can be any string of your choice. It is the name under which your data will appear in Gatsby GraphQL queries. For example, if we specifybooks
as the type name, Gatsby will create GraphQL queries asallBooks
andbooks
.
How to query for data
To query the data use GraphQL query like this,
query MyQuery {
allBooks {
nodes {
rating
publisher
}
}
}
It will return the rating and the publisher name of all the books in the database.
{
"data": {
"allBooks": {
"nodes": [
{
"rating": 0,
"publisher": "Manning"
},
{
"rating": 0,
"publisher": "O'Reilly Media"
},
{
"rating": 0,
"publisher": "No Starch Press"
},
{
"rating": 0,
"publisher": "O'Reilly Media"
},
{
"rating": 0,
"publisher": "O'Reilly Media"
},
{
"rating": 4.5,
"publisher": "No Starch Press"
},
{
"rating": 4,
"publisher": "O'Reilly Media"
},
{
"rating": 5,
"publisher": "O'Reilly Media"
}
]
}
},
"extensions": {}
}
How about applying a filter? Let's query the books with a rating of more than 4.
query MyQuery {
allBooks(filter: {rating: {gt: 4}}) {
nodes {
rating
title
}
}
}
It will output,
{
"data": {
"allBooks": {
"nodes": [
{
"rating": 4.5,
"title": "Understanding ECMAScript 6"
},
{
"rating": 5,
"title": "You Don't Know JS"
}
]
}
},
"extensions": {}
}
Now, you can use queries like these in the Gatsbyjs pages and components.
How to contribute
Thank you for using gatsby-source-harperdb,
and I hope you find it helpful. If you face any issues or got an enhancement request, please consider logging the issue or opening a pull request. All contributions are welcome.