Docs: MongoDB - Initial Draft

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9403 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com> Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> Co-authored-by: Brandon Martin <40686+codedmart@users.noreply.github.com> GitOrigin-RevId: a2279a425d93f7cab22c47de9eda4cd913fbefe8
2024-09-11 10:46:25 +03:00 · 2023-06-08 06:50:27 -04:00 · 2023-06-08 06:50:27 -04:00 · a35e8ef691
commit a35e8ef691
parent 88ca45fca3
13 changed files with 512 additions and 3 deletions
--- a/docs/docs/databases/mongodb/_category_.json
+++ b/docs/docs/databases/mongodb/_category_.json
@ -0,0 +1,5 @@
+{
+  "label": "MongoDB",
+  "position": 90,
+  "className": "beta-cat"
+}
--- a/docs/docs/databases/mongodb/docker.mdx
+++ b/docs/docs/databases/mongodb/docker.mdx
@ -0,0 +1,364 @@
+---
+sidebar_label: Docker
+sidebar_position: 2
+description: Hasura with Docker for MongoDB
+keywords:
+  - hasura
+  - docs
+  - databases
+  - mongodb
+  - docker
+---
+
+import Thumbnail from '@site/src/components/Thumbnail';
+
+# Get Started with Docker (Hasura & MongoDB)
+
+## Introduction
+
+This guide will help you get set up with the [Enterprise Edition](/enterprise/overview.mdx) of Hasura GraphQL Engine
+with our MongoDB integration using Docker Compose. This is the easiest way to set up Hasura Enterprise Edition and the
+MongoDB GraphQL Data Connector.
+
+:::info Supported versions:
+
+Hasura GraphQL Engine `v2.27.0` onwards
+
+:::
+
+:::tip Supported features
+
+Currently, Hasura supports read-only queries on MongoDB.<br/> Other limitations which are actively on the roadmap and
+will be supported soon include:
+
+- Embedded document queries and permissions.
+- Cross-Collection relationships (executed within the database).
+- Logical Models to support schema customization (removing the MongoDB validation schema as a dependency) and bespoke
+  query execution.
+
+:::
+
+## Deploying Hasura Enterprise with Docker
+
+### Prerequisites
+
+This tutorial assumes that the following prerequisites have been met:
+
+- You have [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
+  working on your machine.
+- You have [MongoDB Compass](https://www.mongodb.com/products/compass) installed on your machine.
+
+### Step 1: Get the Docker Compose file
+
+The [install manifests](https://github.com/hasura/graphql-engine/tree/master/install-manifests) repo contains all
+installation manifests required to deploy Hasura anywhere. The Docker Compose manifest also contains a Postgres database
+in order to store the Hasura metadata and a Redis instance for caching.
+
+```bash
+# in a new directory run
+wget https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/enterprise/mongodb/docker-compose.yaml
+# or run
+curl https://raw.githubusercontent.com/hasura/graphql-engine/master/install-manifests/enterprise/mongodb/docker-compose.yaml -o docker-compose.yml
+```
+
+:::info Four containers are created
+
+When you use these to launch the services, you'll see four containers running. The first two are Hasura GraphQL Engine
+and a Postgres Database for storing Hasura's metadata. The third container is the MongoDB GraphQL Connector agent. The
+forth container is a copy of [MongoDB Community Edition](https://hub.docker.com/_/mongo).
+
+:::
+
+### Step 2: Set the Hasura Enterprise Edition license key and the admin secret
+
+Edit the downloaded `docker-compose.yaml` and set the license key and admin secret. If you've been provided a license
+key by the Hasura team, you can enter it according to the directions below.
+
+```yaml {5-6}
+---
+graphql-engine:
+  image: hasura/graphql-engine:v2.27.0
+  environment:
+    HASURA_GRAPHQL_EE_LICENSE_KEY: <license key>
+    HASURA_GRAPHQL_ADMIN_SECRET: <your secretkey>
+```
+
+An [admin secret key](/deployment/securing-graphql-endpoint.mdx) is required to make sure that your GraphQL endpoint and
+the Hasura Console are not publicly accessible.
+
+:::info I don't have a license key
+
+If you don't already have a license key and are interested in trying out Hasura Enterprise Edition with MongoDB, you can
+start a free 30-day trial. Leave the `HASURA_GRAPHQL_EE_LICENSE_KEY` environment variable commented out we'll return to
+this in Step 6.
+
+:::
+
+:::caution Secure the admin secret
+
+The `HASURA_GRAPHQL_ADMIN_SECRET` should never be passed from the client to the Hasura GraphQL Engine as it would give
+the client full admin rights to your Hasura instance. See [Authentication & Authorization](/auth/overview.mdx) for
+information on setting up auth in Hasura.
+
+:::
+
+### Step 3: Run the containers
+
+The following command will create and run the containers in the Docker Compose manifest:
+
+```bash
+docker compose up -d
+```
+
+### Step 4: Create a MongoDB database
+
+:::info I already have a MongoDB database
+
+This guide assumes you don't have a MongoDB instance already set up. If you do, you can skip to
+[Step 6](#step-6-load-the-hasura-console).
+
+:::
+
+Open MongoDB Compass and create a new connection using this connection string:
+
+```
+mongodb://mongouser:mongopassword@localhost:27017/?authMechanism=DEFAULT
+```
+
+Create a new database called demo using the MongoShell at the bottom of the MongoDB compass screen by entering the
+command:
+
+```
+use demo;
+```
+
+Via MongoShell, create a new `users` collection:
+
+```javascript
+db.createCollection('users', {
+  validator: {
+    $jsonSchema: {
+      bsonType: 'object',
+      required: ['name', 'age'],
+      properties: {
+        name: {
+          bsonType: 'string',
+        },
+        age: {
+          bsonType: 'int',
+          minimum: 18,
+        },
+        email: {
+          bsonType: 'string',
+          pattern: '^.+@.+$',
+        },
+        user_meta: {
+          bsonType: 'object',
+          properties: {
+            user_role: {
+              bsonType: 'string',
+            },
+            email_verified: {
+              bsonType: 'bool',
+            },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+:::info Why do I need a validation schema in my Collection?
+
+Currently, Hasura uses the validation schema to build your GraphQL schema.
+
+Future versions of the Hasura MongoDB connector will allow on-the-fly editing of the GraphQL schema, will continue to
+work with the MongoDB validation schema, but will not have it as a dependency.
+
+Read more about the
+[MongoDB validation schema](https://www.mongodb.com/docs/manual/core/schema-validation/specify-json-schema/#std-label-schema-validation-json)
+and how to set it up for your database.
+
+:::
+
+If you don't see your changes, you can refresh your databases on the left-hand sidebar. Once applied, you can view the
+`users` Collection in MongoDB Compass:
+
+<Thumbnail
+  src="/img/databases/mongodb/mongo-collection.png"
+  alt="Creating your first MongoDB Collection."
+  width="1000px"
+/>
+
+### Step 5: Insert your first sample Documents
+
+Insert a few sample documents to query on afterwards.
+
+```javascript
+db.users.insertMany([
+  {
+    name: 'John',
+    age: 44,
+    email: 'john@example.com',
+    user_meta: {
+      user_role: 'user',
+      email_verified: true,
+    },
+  },
+  {
+    name: 'Jane',
+    age: 24,
+    email: 'jane@example.com',
+    user_meta: {
+      user_role: 'user',
+      email_verified: true,
+    },
+  },
+  {
+    name: 'Emma',
+    age: 36,
+    email: 'emma@example.com',
+    user_meta: {
+      user_role: 'manager',
+      email_verified: true,
+    },
+  },
+  {
+    name: 'Liam',
+    age: 64,
+    email: 'liam@example.com',
+    user_meta: {
+      user_role: 'manager',
+      email_verified: true,
+    },
+  },
+]);
+```
+
+You should see an output similar to this:
+
+<Thumbnail
+  src="/img/databases/mongodb/mongo-documents.png"
+  alt="Inserting your sample Documents in MongoDB."
+  width="1000px"
+/>
+
+### Step 6: Load the Hasura Console
+
+Open the Hasura Console by navigating to `http://localhost:8080/console`. You will need to input your admin secret key
+as set in your Docker Compose file to log in.
+
+:::info 30-day free trial
+
+If you don't already have a license key, you can start a 30-day free trial by clicking the `ENTERPRISE` button in the
+top navigation. You can read more details [here](/enterprise/try-hasura-enterprise-edition.mdx).
+
+<Thumbnail
+  src="/img/enterprise/Trials_Register_Button.png"
+  alt="Enterprise Edition Trial register button"
+  width="1146px"
+/>
+
+:::
+
+### Step 7: Connect to MongoDB
+
+Visit `Data` > `Manage` to connect your MongoDB database. **If you've connected using the Docker guide above, your
+MongoDB data connector should be pre-connected to your Hasura instance.** Select the `Connect Database` button and
+follow head to [Step 8](#step-8-tracking-collections).
+
+You can check this by selecting the `Data Connector Agents` dropdown from the Data Manager:
+
+If it is not connected and you're using the `docker-compose.yml` file above, you can use the following details to
+connect to your agent as in the screenshot below:
+
+- Agent Name: `mongodb`
+- URL: `http://mongo-data-connector:3000`
+
+Then click, `Connect`:
+
+<Thumbnail src="/img/databases/mongodb/data-connector.png" alt="Connecting to MongoDB - Connector" width="1000px" />
+
+Connect your database using the following details:
+
+- Database Name: `mongodb`
+- Connection: `mongodb://mongouser:mongopassword@mongodb:27017`
+- db: `demo`
+
+<Thumbnail src="/img/databases/mongodb/connecting.gif" alt="Connecting to MongoDB - Connections" width="1000px" />
+
+If you're using a MongoDB instance hosted on MongoDB Atlas or elsewhere, simply add the connection details for your
+instance and click `Connect Database`.
+
+### Step 8: Tracking Collections
+
+Once your database has been connected, select the database name from the left-hand sidebar.
+
+You should see your `users` Collection listed here. Select it, and select `Track Selected`.
+
+<Thumbnail src="/img/databases/mongodb/track-table.png" alt="Connecting to MongoDB - Track Tables." width="1000px" />
+
+Your `users` Collection is now added to your GraphQL API! 🎉
+
+:::info Make your Collection available to other roles
+
+By default, this Collection is only available to `admin` users. To make it available for more user groups, select the
+Collection name from the left-hand sidebar, and select `Permissions` to setup permission rules for the Collection. You
+can read more about permissions [here](/auth/authorization/index.mdx).
+
+:::
+
+### Step 9: Running your first query
+
+Select API from your header, this will take you to GraphiQL, our API testing utility.
+
+Entering the following query and running will return all your users:
+
+```graphql
+query allUsers {
+  users {
+    _id
+    age
+    email
+    name
+    user_meta {
+      email_verified
+      user_role
+    }
+  }
+}
+```
+
+<Thumbnail
+  src="/img/databases/mongodb/gql-query.png"
+  alt="Connecting to MongoDB - Making a GraphQL query."
+  width="1000px"
+/>
+
+Entering the following will only return users with the names 'John' or 'Jane':
+
+```graphql
+query userFiltered {
+  users(where: { name: { _in: ["John", "Jane"] } }) {
+    _id
+    age
+    email
+    name
+    user_meta {
+      email_verified
+      user_role
+    }
+  }
+}
+```
+
+## Keep up to date
+
+Please watch this space to get the latest docs on how you can try these features out via the Console or by manipulating
+Metadata in JSON/YAML directly.
+
+If you'd like to stay informed about the status of MongoDB support, subscribe to our newsletter and join our discord!
+
+- [https://hasura.io/newsletter/](https://hasura.io/newsletter/)
+- [https://discord.com/invite/hasura](https://discord.com/invite/hasura)
--- a/docs/docs/databases/mongodb/index.mdx
+++ b/docs/docs/databases/mongodb/index.mdx
@ -0,0 +1,58 @@
+---
+slug: index
+description: Hasura MongoDB database support
+keywords:
+  - hasura
+  - docs
+  - databases
+  - mongodb
+  - nosql
+  - olap
+  - oltp
+---
+
+# MongoDB
+
+:::tip MongoDB Beta Availability
+
+The Hasura MongoDB connector is currently in `beta` for Hasura Enterprise Edition customers and is available
+from Hasura GraphQL Engine `v2.27.0` onwards.
+
+Hasura Cloud support for MongoDB will be coming soon. Once the MongoDB connector is generally available (GA), it will be
+available **only** for Hasura Cloud Enterprise and Enterprise Edition customers.
+
+:::
+
+## Introduction
+
+Hasura supports connecting to a [MongoDB](https://www.mongodb.com/) service to automatically build a GraphQL API based
+on its validation schema.
+
+## Get Started
+
+To try Hasura with MongoDB, you'll need a new or existing MongoDB instance (either self-hosted, or available through
+MongoDB Atlas).
+
+You can currently get started with Hasura and MongoDB using [Docker](/databases/mongodb/docker.mdx).
+
+## Keep up to date
+
+:::info Note
+
+Currently, Hasura supports read-only queries on MongoDB.<br/> Other limitations which are actively on the roadmap and
+will be supported soon include:
+
+- Embedded document queries and permissions.
+- Cross-Collection relationships (executed within the database).
+- Logical models to support schema customization and bespoke query execution.
+
+:::
+
+If you'd like to stay informed about the status of MongoDB support, subscribe to our newsletter and join our discord!
+
+- [https://hasura.io/newsletter/](https://hasura.io/newsletter/)
+- [https://discord.com/invite/hasura](https://discord.com/invite/hasura)
+
+## Know more
+
+- [Get started](/databases/mongodb/docker.mdx)
--- a/docs/docs/databases/overview.mdx
+++ b/docs/docs/databases/overview.mdx
@ -17,6 +17,7 @@ import PostgreSQL from '@site/static/img/databases/logos/postgresql.png';
 import SQLServer from '@site/static/img/databases/logos/sql-server.png';
 import BigQuery from '@site/static/img/databases/logos/bigquery.png';
 import MariaDB from '@site/static/img/databases/logos/mariadb.png';
+import MongoDB from '@site/static/img/databases/logos/mongodb.png';
 import MySQL from '@site/static/img/databases/logos/mysql.png';
 import Snowflake from '@site/static/img/databases/logos/snowflake.png';
 import AmazonAthena from '@site/static/img/databases/logos/amazon-athena.png';
@ -101,7 +102,7 @@ import Oracle from '@site/static/img/databases/logos/oracle.png';
      <div className="card">
        <img src={MySQL} title="MySQL" alt="Connect MySQL to Hasura" />
      </div>
-      <h5>MySQL (Beta)</h5>
+      <h5>MySQL</h5>
    </div>
  </VersionedLink>
  <VersionedLink to="/databases/oracle/index/">
@ -109,7 +110,7 @@ import Oracle from '@site/static/img/databases/logos/oracle.png';
      <div className="card">
        <img src={Oracle} title="Oracle" alt="Connect Oracle to Hasura" />
      </div>
-      <h5>Oracle (Beta)</h5>
+      <h5>Oracle</h5>
    </div>
  </VersionedLink>
  <VersionedLink to="/databases/mariadb/index/">
@ -117,7 +118,15 @@ import Oracle from '@site/static/img/databases/logos/oracle.png';
      <div className="card">
        <img src={MariaDB} title="MariaDB" alt="Connect MariaDB to Hasura" />
      </div>
-      <h5>MariaDB (Beta)</h5>
+      <h5>MariaDB</h5>
+    </div>
+  </VersionedLink>
+  <VersionedLink to="/databases/mongodb/index/">
+    <div className="card-wrapper">
+      <div className="card">
+        <img src={MongoDB} style={{ width: '172px' }} title="MongoDB" alt="Connect MongoDB to Hasura" />
+      </div>
+      <h5>MongoDB (Beta)</h5>
    </div>
  </VersionedLink>
 </div>
--- a/docs/docs/enterprise/overview.mdx
+++ b/docs/docs/enterprise/overview.mdx
@ -90,6 +90,12 @@ import Enterprise from '@site/static/icons/features/enterprise.svg';
      <p>Learn how to connect Hasura to MariaDB using Hasura Enterprise Edition.</p>
    </div>
  </VersionedLink>
+  <VersionedLink to="/databases/mongodb/index/">
+    <div className="card">
+      <h3>MongoDB</h3>
+      <p>Learn how to connect Hasura to MongoDB using Hasura Enterprise Edition.</p>
+    </div>
+  </VersionedLink>
  <h2 style={{ gridColumn: `1 / -1`, marginTop: `1.2rem`, marginBottom: `.3rem`, justifySelf: `start`, fontSize: `1.8rem` }}>Performance</h2>
  <VersionedLink to="/enterprise/caching/">
    <div className="card">
--- a/docs/static/img/databases/logos/mongodb.png
+++ b/docs/static/img/databases/logos/mongodb.png
--- a/docs/static/img/databases/mongodb/connecting.gif
+++ b/docs/static/img/databases/mongodb/connecting.gif
--- a/docs/static/img/databases/mongodb/data-connector.png
+++ b/docs/static/img/databases/mongodb/data-connector.png
--- a/docs/static/img/databases/mongodb/gql-query.png
+++ b/docs/static/img/databases/mongodb/gql-query.png
--- a/docs/static/img/databases/mongodb/mongo-collection.png
+++ b/docs/static/img/databases/mongodb/mongo-collection.png
--- a/docs/static/img/databases/mongodb/mongo-documents.png
+++ b/docs/static/img/databases/mongodb/mongo-documents.png
--- a/docs/static/img/databases/mongodb/track-table.png
+++ b/docs/static/img/databases/mongodb/track-table.png
--- a/install-manifests/enterprise/mongodb/docker-compose.yaml
+++ b/install-manifests/enterprise/mongodb/docker-compose.yaml
@ -0,0 +1,67 @@
+version: "3.7"
+services:
+  redis:
+    image: redis:7
+    restart: always
+    # ports:
+    #   - 6379:6379
+  postgres:
+    image: postgres:15
+    restart: always
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_DB: postgres
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgrespassword
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}" ]
+      interval: 10s
+      timeout: 5s
+      retries: 25
+  mongodb:
+    image: mongo:6
+    restart: always
+    volumes:
+      - mongo_data:/data/db
+    ports:
+      - 127.0.0.1:27017:27017
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: mongouser
+      MONGO_INITDB_ROOT_PASSWORD: mongopassword
+  hasura:
+    image: hasura/graphql-engine:v2.27.0
+    restart: always
+    ports:
+      - 8080:8080
+    environment:
+      ## Add your license key below
+      # HASURA_GRAPHQL_EE_LICENSE_KEY: ""
+      HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
+      ## The metadata database for this Hasura GraphQL project. Can be changed to a managed postgres instance
+      HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
+      
+      ## Optional settings
+      ## enable the console served by server
+      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
+      ## enable required apis; metrics api exposes a prometheus endpoint, uncomment to enable
+      # HASURA_GRAPHQL_ENABLED_APIS: 'graphql,metadata,config,developer,pgdump,metrics'
+      ## secure metrics endpoint with a secret, uncomment to enable
+      # HASURA_GRAPHQL_METRICS_SECRET: 'secret'
+      ## enable debugging mode. It is recommended to disable this in production
+      HASURA_GRAPHQL_DEV_MODE: "true"
+      # HASURA_GRAPHQL_LOG_LEVEL: debug
+      HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: "/srv/console-assets"
+      HASURA_GRAPHQL_REDIS_URL: redis://redis:6379
+      HASURA_GRAPHQL_RATE_LIMIT_REDIS_URL: "redis://redis:6379"
+      HASURA_GRAPHQL_MAX_CACHE_SIZE: "200"
+    depends_on:
+      postgres:
+        condition: service_healthy
+  mongo-data-connector:
+    image: hasura/mongo-data-connector:v2.27.0
+    ports:
+      - 3000:3000
+volumes:
+  db_data:
+  mongo_data: