Skip to content
Snippets Groups Projects
Commit 2291c02a authored by daffie's avatar daffie
Browse files

Issue #3448274 by daffie: Update the readme for the alpha1 release

parent d5ccf077
No related branches found
No related tags found
3 merge requests!31Fixed node_access query.,!283.x,!20Updated the readme.MD file for the alpha1 release
Hide whitespace changes
Inline Side-by-side
Showing
with 139 additions and 35 deletions
readme.MD
+ 139
− 35
View file @ 2291c02a
# Install Drupal on MongoDB # Drupal on MongoDB
This install guide uses the DDEV development environment.
This install guide is based on the following DDEV [guide](https://ddev.readthedocs.io/en/stable/users/quickstart/#drupal).
## Requirements
The full support database driver for MongoDB has the following minimum requirements: The full support database driver for MongoDB has the following minimum requirements:
- Drupal 11.0 - Drupal 11.0
- MongoDB 7.0 with a replica set. The replica set offers support for [multi document transactions](https://www.mongodb.com/docs/v5.2/core/transactions/). - MongoDB 7.0 with a replica set. The replica set offers support for [multi document transactions](https://www.mongodb.com/docs/v5.2/core/transactions/).
## Install steps (for Drupal Core [11.0.0-beta1](https://www.drupal.org/project/drupal/releases/11.0.0-beta1))
1 Create a directory for the Drupal on MongoDB project.
```
mkdir your-directory && cd your-directory
```
2 Configure your DDEV project. Disable the default management settings and the default database. We do not need a MySQL database. ## How is Drupal's entity data stored in MongoDB
```
ddev config --project-type=drupal --php-version=8.3 --docroot=web --omit-containers=db --disable-settings-management=true
ddev start
ddev composer create drupal/recommended-project:11.0.0-beta1
ddev config --update
ddev restart
```
3 Install the MongoDB database with the replica set. All entity instances are stored in JSON documents.
``` Each entity instance is stored in its own JSON document.
ddev get drupal-daffie/ddev-mongo-replicaset All entity data including all revisional data, all translations and all field data belonging to an entity instance are stored in the same JSON document.
ddev restart Because all entity data for an entity instance is stored in the same JSON document, loading an entity instance from a MongoDB database is always a single row from a single table. Or in MongoDB jargon: A single document from a single collection.
``` No more complicated join queries are required for loading an entity from the relational database (MySQL, MariaDB or PostgreSQL).
4 Add the MongoDB database driver module to the project An example of how entity data is stored in MongoDB (user #1):
``` ```
ddev composer require drupal/mongodb:3.0.0-alpha1 {
_id: ObjectId('664afdd4a3a001e71e0b49c7'),
uid: 1,
uuid: '841149cd-fe56-47c4-a112-6d23f561332f',
langcode: 'en',
user_translations: [
{
uid: 1,
uuid: '841149cd-fe56-47c4-a112-6d23f561332f',
langcode: 'en',
preferred_langcode: 'en',
name: 'root',
pass: '$2y$10$kjGuIsPOTDa2TseuWMFGS.veLzH/khl0SfsuZNAeRPRtABgfq5GSC',
mail: 'admin@finalist.nl',
timezone: 'Europe/Amsterdam',
status: true,
created: ISODate('2024-05-20T07:37:54.000Z'),
changed: ISODate('2024-05-20T07:42:08.000Z'),
access: ISODate('2024-05-20T08:46:47.000Z'),
login: ISODate('2024-05-20T07:44:16.000Z'),
init: 'admin@finalist.nl',
default_langcode: true,
user_translations__roles: [
{
bundle: 'user',
deleted: false,
langcode: 'en',
entity_id: 1,
revision_id: 1,
delta: 0,
roles_target_id: 'administrator'
}
]
}
],
login: ISODate('2024-05-20T07:44:16.000Z'),
access: ISODate('2024-05-20T08:46:47.000Z')
}
``` ```
5 Drupal Core needs to be patched to make it all work. - Every JSON document in MongoDB has its own unique ID with its own key `_id`.
``` - Timestamps are stored as ISODate objects. Timestamps are stored with their timezone. Timestamps can be printed in many ways including other timezones.
cd web - Boolean values are stored as real booleans, not as integers as is currently the case in Drupal.
git apply -v modules/contrib/mongodb/patches/drupal-core-11.0.0-beta1.patch - The user entity and therefore all entity data that is translatable is stored in an embedded table. For the user entity the embedded table name is `user_translations`. In the example the root user has only a single translation. Every translation is given its own row in the embedded translations table. Revisional data is also stored in its own embedded tables. An entity that is revisionable has 3 embedded tables, one for the current revision, one for all revisions and one for the latest revision. This is needed to support entity queries.
cd .. - Entity field data is stored in its own embedded table. Every field has its own embedded table. In the given example the root user has the role "administrator". Every role that the user is given its own row in the embedded table `user_translations__roles`.
```
6 Install Drush When entity instances are revisionable, translatable and/or have field data attached to it, may result in big JSON documents. For instance when you install the Unami profile the node with the recipe 'Deep mediterranean quiche' has 2 revisions, 2 translations and 10 fields with data. When you view the JSON document for this node in the Mongo Express it is 1764 lines long. The size is about 65K bytes. The maximum size of a JSON document is 16M bytes. The maximum JSON document size is big, but not endless.
```
ddev composer require drush/drush
ddev drush cr
``` ## Current status of the database driver
- All the base functions of Drupal Core are functional.
- Installing a Drupal site with Drupal UI process are functional. Over 90% of the Drupal Core kerneltests and functionaltests pass successfully.
- Drupal's Database API is supported. Some complicated queries, like with subqueries are not supported.
- Drupal's EntityStorage API is supported.
- Drupal's EntityQuery API is supported with the exception of relationship queries.
- Drupal's views module is supported with the exception of views with groupwise max functionality.
- Bugs occur when using the modules content_moderation, workflows and workspaces.
- The database driver is not tested with contrib or custom modules.
## Install Drupal on MongoDB (for Drupal Core [11.0.0-beta1](https://www.drupal.org/project/drupal/releases/11.0.0-beta1))
This install guide uses the DDEV development environment.
This install guide is based on the following DDEV [guide](https://ddev.readthedocs.io/en/stable/users/quickstart/#drupal).
### 1. Create a directory for the Drupal on MongoDB project.
```mkdir your-project-directory && cd your-project-directory```
### 2. Configure your DDEV project. Disable the default management settings and the default database. We do not need a MySQL database.
```ddev config --project-type=drupal --php-version=8.3 --docroot=web --omit-containers=db --disable-settings-management=true```
```ddev start```
7 Do a regular site install with the UI. ```ddev composer create drupal/recommended-project:11.0.0-beta1```
```ddev config --update```
```ddev restart```
### 3. Install the MongoDB database with the replica set.
```ddev get drupal-daffie/ddev-mongo-replicaset```
```ddev restart```
### 4. Add the MongoDB database driver module to the project
```ddev composer require drupal/mongodb:3.0.0-alpha1```
### 5. Drupal Core needs to be patched to make it all work.
```cd web```
```git apply -v modules/contrib/mongodb/patches/drupal-core-11.0.0-beta1.patch```
```cd ..```
### 6. Optional: Install Drush
```ddev composer require drush/drush```
### 7. Do a regular site install with the UI.
On the database configuration page select **MongoDB (Experimental)** On the database configuration page select **MongoDB (Experimental)**
...@@ -62,3 +136,33 @@ On the database configuration page select **MongoDB (Experimental)** ...@@ -62,3 +136,33 @@ On the database configuration page select **MongoDB (Experimental)**
![Database options to set](database-settings-example.png) ![Database options to set](database-settings-example.png)
## Installing for the contributing ([Drupal Core 11.x](https://www.drupal.org/project/drupal/releases/11.x))
It is the same as a regular installation, with a couple of changes:
- In step 2 change the used repository to: ```ddev composer create drupal/recommended-project:^11.x-dev```
- In step 4 change the used repository to: ```ddev composer require drupal/mongodb:3.x-dev```
- In step 5 change the used patch to: ```git apply -v modules/contrib/mongodb/patches/drupal-core-11.x.patch```
- In step 5 also apply the patch for testing: ```git apply -v modules/contrib/mongodb/patches/drupal-core-tests-11.x.patch```
It is possible the patches do not apply, because of currently unforeseen changes in Drupal Core.
**Contributions to this project are highly appreciated.**
## Connect to MongoDB with [Mongo Express](https://github.com/mongo-express/mongo-express)
Mongo Express is a web based admin interface to a MongoDB database. To log in use the username `db` and the password `db`.
## Connect to MongoDB with MongoDB's [Compass](https://www.mongodb.com/products/tools/compass) tool
MongoDB has a great FREE tool to connect to a MongoDB database.
> Compass is a free interactive tool for querying, optimizing, and analyzing your MongoDB data. Get key insights, drag and drop to build pipelines, and more.
The connection string that I use, and yes it can be improved, is:
```
mongodb://db:db@your-project-directory.ddev.site:27017/?directConnection=true&replicaSet=dbrs
```
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment