Skip to content

Commit 23b4788

Browse files
rhedgpethrhedgpeth
committed
updates
1 parent 9c65ebc commit 23b4788

9 files changed

+268
-15
lines changed

‎README.md

+259-10
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,74 @@
11
# Get Started with MariaDB's NoSQL Listener
22

3-
This repository contains information on how to get started using the NoSQL Listener capability of MariaDB MaxScale.
3+
This repository contains information on how to create and use a [MariaDB MaxScale](https://mariadb.com/products/enterprise/components/#maxscale) NoSQL Listener with [MariaDB Community Server](https://mariadb.com/products/community-server/).
44

5-
## Requirements
5+
This `README` will walk you through the process of using a MongoDB driver to connect to and communicate with MariaDB, which includes storing and manage NoSQL document data within MariaDB.
6+
7+
# Table of Contents
8+
1. [Requirements](#requirements)
9+
2. [NoSQL Protocol Module](#nosql-protocol)
10+
2. [Getting Started](#get-started)
11+
3. [Exploring the Data](#explore)
12+
1. [Querying MariaDB](#query-mariadb)
13+
2. [MaxScale GUI](#maxscale-gui)
14+
3. [MongoDB Shell](#mongodb-shell)
15+
4. [Using the TODO Application Directly](#todo-app)
16+
5. [Support and contribution](#support-contribution)
17+
6. [License](#license)
18+
19+
## Requirements <a name="requirements"></a>
620

721
Before setting up this sample make sure you have the following installed on your machine.
822

923
* [Git](https://git-scm.com/downloads)
1024
* [Docker](https://www.docker.com/get-started)
1125

12-
## Instructions
26+
## NoSQL Protocol Module <a name="nosql-protocol"></a>
27+
28+
The [nosqlprotocol module](https://github.com/mariadb-corporation/MaxScale/blob/develop/Documentation/Protocols/NoSQL.md) allows a MariaDB server or cluster to be used as the backend of an application using a [MongoDB® client library](https://docs.mongodb.com/drivers/node/current/). Internally, all documents are stored in a table containing two columns; an `id` column for the object id and a `doc` column for the document itself.
29+
30+
When the MongoDB® client application issues [MongoDB protocol commands](https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/), either directly or indirectly via the client library, they are transparently converted into the equivalent SQL and executed against the MariaDB backend. The MariaDB responses are then in turn converted into the format expected by the MongoDB® client library and application.
31+
32+
<p align="center" spacing="10">
33+
<kbd>
34+
<img src="media/mql_to_sql.png" />
35+
</kbd>
36+
</p>
37+
38+
For more information on the full capabilities see the documentation [here](https://github.com/mariadb-corporation/MaxScale/blob/develop/Documentation/Protocols/NoSQL.md).
39+
40+
## Getting Started <a name="get-started"></a>
1341

1442
1. Clone this repository to your machine.
1543

1644
```bash
1745
$ git clone https://github.com/mariadb-corporation/dev-example-nosql-listener.git
1846
```
1947

20-
2. Create the container instances uses [Docker Compose](https://docs.docker.com/compose/).
48+
2. Create the container instances using [Docker Compose](https://docs.docker.com/compose/).
2149

2250
```bash
2351
$ docker-compose up
2452
```
2553

54+
The command above will acquire Docker images and create four container instances.
55+
56+
a. `mxs` - the official MariaDB MaxScale image.
57+
58+
b. `mdb` - the official MariaDB Community server image.
59+
60+
c. `todo_client` - a React.js web application that provides a user interface for managing tasks (on a todo list).
61+
62+
d. `todo_api` - a Node.js application programming interface (API) that exposes REST endpoints for managing data within a database using the [official MongoDB Node Driver](https://docs.mongodb.com/drivers/node/current/).
63+
64+
**Note**: You can confirm that the `docker-compose up` command has successfully pulled the images and created the containers by executing the following command:
65+
66+
```bash
67+
$ docker ps
68+
```
69+
70+
The result should show that the `mxs`, `mdb`, `todo_client` and `todo_api` are running.
71+
2672
3. Add a new MaxScale user to the MariaDB database.
2773

2874
a. Option 1 - Step into the `mdb` Docker container.
@@ -33,9 +79,9 @@ Before setting up this sample make sure you have the following installed on your
3379
2. ```bash
3480
$ mariadb --user root -pPassword123!
3581
```
36-
3. Copy, paste and execute the scripts [here](configuration/add_maxscale_user.sql).
82+
3. Copy, paste and execute the scripts [here](configuration/add_maxscale_user.sql) using the MariaDB command line interface (CLI) client.
3783

38-
b. Option 2 - Execute the [add_maxscale_user.sql](configuration/add_maxscale_user.sql) on the `mdb` server using the MariaDB CLI client.
84+
b. Option 2 - Execute the [add_maxscale_user.sql](configuration/add_maxscale_user.sql) on the MariaDB Community Server instance contained with the `mdb` containernusing the MariaDB CLI client.
3985

4086
```bash
4187
$ mariadb --host 127.0.0.1 --port 3307 --user root -pPassword123! < configuration/add_maxscale_user.sql
@@ -57,16 +103,219 @@ Before setting up this sample make sure you have the following installed on your
57103
$ vi etc/maxscale.cnf
58104
```
59105

60-
Press `i` (to enable insert ability)
106+
**VIM Edit Tips:**
61107

62-
Replace all the contents of the maxscale.cnf file with [this](configuration.maxscale.cnf).
108+
- Press `i` (to enable insert ability)
63109

64-
Press `escape`. Type `:wq` and press `Enter`.
110+
- Within insert mode replace all the contents of the maxscale.cnf file with [this](configuration.maxscale.cnf).
111+
112+
- To save, press `escape`, then type `:wq` and, finally, press `Enter` to confirm.
65113

66114
c. Restart MaxScale
67115

68116
```bash
69117
$ maxscale-restart
70118
```
71119

72-
5. Open a browser window and navigate to `http://localhost:3000`.
120+
5. Open a browser window and navigate to `http://localhost:3000`, which will load the TODO web application interface.
121+
122+
<p align="center" spacing="10">
123+
<kbd>
124+
<img src="media/demo.gif" />
125+
</kbd>
126+
</p>
127+
128+
The TODO application is made of two pieces:
129+
130+
1. UI - a React.js project that is hosted within the `todo_client` container and accessed at http://127.0.0.1:3000.
131+
132+
2. API - a Node.js (+ Express) project that exposes REST endpoints for performing CRUD (create-read-update-delete) operations on (JSON) document data stored, via the MaxScale NoSQL Listener functionality, within MariaDB. The API application is hosted within the `todo_api` container and access at http://127.0.0.1:8080/tasks.
133+
134+
The TODO application can be used to manage data within MariaDB
135+
136+
## Exploring the Data <a name="explore"></a>
137+
138+
After you've successfully walked through the setup instructions within [Getting Started](#get-started) you're now able to explore the NoSQL Listener capabilities within MariaDB.
139+
140+
### Querying MariaDB <a name="query-mariadb"></a>
141+
142+
If you've used the TODO application to add new `tasks` you can now explore the schema and data that have been added.
143+
144+
You can connect to the MariaDB Community Server instance, contained within the `mdb` container, directly by using the MariaDB client.
145+
146+
```bash
147+
$ mariadb --host 127.0.0.1 --port 3307 --user root -pPassword123!
148+
```
149+
150+
Once you've accessed through the MariaDB CLI client you see the database, named `todo`, that's been created.
151+
152+
```bash
153+
MariaDB [(none)]> show databases;
154+
+--------------------+
155+
| Database |
156+
+--------------------+
157+
| information_schema |
158+
| mysql |
159+
| performance_schema |
160+
| sys |
161+
| todo |
162+
+--------------------+
163+
```
164+
165+
Stepping into the `todo` you can also see the new table, `tasks`, that has been created to store the document data.
166+
167+
```bash
168+
MariaDB [(none)]> use todo;
169+
MariaDB [todo]> show create table tasks;
170+
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
171+
| Table | Create Table |
172+
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
173+
| tasks | CREATE TABLE `tasks` (
174+
`id` varchar(35) GENERATED ALWAYS AS (json_compact(json_extract(`doc`,'$._id'))) VIRTUAL,
175+
`doc` longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL CHECK (json_valid(`doc`)),
176+
UNIQUE KEY `id` (`id`),
177+
CONSTRAINT `id_not_null` CHECK (`id` is not null)
178+
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 |
179+
+-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
180+
```
181+
182+
Notice, that the `tasks` table contains two columns:
183+
184+
- `id`: holds the document data object id
185+
- `doc`: holds the document data itself
186+
187+
And you can query the data, using SQL, just as you can anything else within MariaDB.
188+
189+
```bash
190+
MariaDB [todo]> select * from tasks;
191+
+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
192+
| id | doc |
193+
+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
194+
| {"$oid":"612ad5859c58d2b2b46ca6fa"} | {"description": "Task 1", "_id": {"$oid": "612ad5859c58d2b2b46ca6fa"}, "id": "612ad5859c58d2b2b46ca6fa", "completed": 0} |
195+
| {"$oid":"612aec0aaa1de377a7071d92"} | {"description": "Task 2", "_id": {"$oid": "612aec0aaa1de377a7071d92"}, "id": "612aec0aaa1de377a7071d92", "completed": 1} |
196+
| {"$oid":"612aec10aa1de377a7071d93"} | { "description" : "Task 3", "_id" : { "$oid" : "612aec10aa1de377a7071d93", completed: 0} } |
197+
| {"$oid":"612aec4b923b0597463743f0"} | {"description": "Task 4", "_id": {"$oid": "612aec4b923b0597463743f0"}, "id": "612aec4b923b0597463743f0", "completed": 1} |
198+
+-------------------------------------+--------------------------------------------------------------------------------------------------------------------------+
199+
```
200+
201+
You can even take advantage of MariaDB's JSON querying functionality support.
202+
203+
```bash
204+
MariaDB [todo]> select json_value(doc, '$.description') description, json_value(doc, '$.completed') completed from tasks;
205+
+-------------+-----------+
206+
| description | completed |
207+
+-------------+-----------+
208+
| Task 1 | 0 |
209+
| Task 2 | 1 |
210+
| Task 3 | 0 |
211+
| Task 4 | 1 |
212+
+-------------+-----------+
213+
```
214+
215+
### MaxScale GUI <a name="maxscale-gui"></a>
216+
217+
The [MaxScale graphical user interface (GUI)](https://mariadb.com/resources/blog/getting-started-with-the-mariadb-maxscale-gui/) provides another way you that you can explore the data.
218+
219+
#### **Logging In**
220+
221+
Start by opening a browser window and navigating to http://localhost:8989. There you'll be prompted to login.
222+
223+
<p align="center" spacing="10">
224+
<kbd>
225+
<img src="media/maxscale_gui_login.png" />
226+
</kbd>
227+
</p>
228+
229+
**Note:** The default username is `admin` and the password is `maxscale`.
230+
231+
#### **Dashboard**
232+
233+
After you've logged in you'll be taken to a dashboard that gives you information on MaxScale, including the service and listener configuration information.
234+
235+
<p align="center" spacing="10">
236+
<kbd>
237+
<img src="media/maxscale_gui_dashboard.png" />
238+
</kbd>
239+
</p>
240+
241+
#### **Query Editor**
242+
243+
On the left side navigation you can select the "Query Editor" menu option.
244+
245+
<p align="center" spacing="10">
246+
<kbd>
247+
<img src="media/maxscale_gui_queryeditor.png" />
248+
</kbd>
249+
</p>
250+
251+
Then you'll be prompted for connection information. For this you can connect directly to a server and/or schema within MariaDB.
252+
253+
For example:
254+
255+
<p align="center" spacing="10">
256+
<kbd>
257+
<img src="media/maxscale_gui_connect.png" />
258+
</kbd>
259+
</p>
260+
261+
After you've connected you can use the Query Editor to execute SQL queries, display datasets and even visualize the data using graphs and charts.
262+
263+
<p align="center" spacing="10">
264+
<kbd>
265+
<img src="media/maxscale_gui_queryeditor_dashboard.png" />
266+
</kbd>
267+
</p>
268+
269+
### MongoDB Shell <a name="mongodb-shell"></a>
270+
271+
You can also use the [Mongo Shell client](https://docs.mongodb.com/v4.4/mongo/) to connect to and communicate with MariaDB (via MaxScale). You can find more information on how to do so [here](https://github.com/mariadb-corporation/MaxScale/blob/develop/Documentation/Protocols/NoSQL.md#client-authentication).
272+
273+
## Using the TODO Application Directly <a name="todo-app"></a>
274+
275+
Optionally, if you'd prefer to run the [TODO app](app) directly on your machine, rather than through a container, can do the following:
276+
277+
1. Make sure that you've installed the latest version of [Node.js](https://nodejs.org/en/) and [Node Package Manager (NPM)](https://www.npmjs.com/).
278+
279+
2. Install the node modules for the `client` and `api` applications.
280+
281+
Within a terminal...
282+
283+
a. Navigate to [app/client](app/client) and execute:
284+
285+
```bash
286+
$ npm install
287+
```
288+
289+
b. Navigate to [app/api](app/api) and execute:
290+
291+
```bash
292+
$ npm install
293+
```
294+
295+
3. Update the MongoDB driver connection string in [app/api/db.js](app/api/db.js) to `'mongodb://127.0.0.1:17017'`.
296+
297+
4. Start the `client` and `api` applications.
298+
299+
Within separate terminals...
300+
301+
a. Navigate to [app/client](app/client) and execute:
302+
303+
```bash
304+
$ npm start
305+
```
306+
307+
b. Navigate to [app/api](app/api) and execute:
308+
309+
```bash
310+
$ npm start
311+
```
312+
313+
## Support and Contribution <a name="support-contribution"></a>
314+
315+
Thanks so much for taking a look at this repository! As the NoSQL Listener capability is in the early stages, there's plenty of potential for improvement.
316+
317+
If you have any questions, comments, or would like to contribute to this or future projects like this please reach out to us directly at [[email protected]](mailto:[email protected]) or on [Twitter](https://twitter.com/mariadb).
318+
319+
## License <a name="license"></a>
320+
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=plastic)](https://opensource.org/licenses/MIT)
321+

‎app/client/src/components/Dashboard.js

+9-5
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ import AddTask from './AddTask';
55
import close from '../images/close.png';
66

77
export default class Dashboard extends Component {
8+
9+
todo_api_url = "http://127.0.0.1:8080/api/tasks";
10+
811
constructor(props) {
912
super(props);
1013
this.state = {
@@ -42,7 +45,8 @@ export default class Dashboard extends Component {
4245
async addTask(description) {
4346
this.toggleAddTaskModal();
4447
var task = {
45-
description: description
48+
description: description,
49+
completed: false
4650
};
4751
await this.saveTask(task);
4852
await this.loadTasks();
@@ -51,7 +55,7 @@ export default class Dashboard extends Component {
5155
async saveTask(task) {
5256
var res = null;
5357
if (task !== null && task.id != undefined) {
54-
res = await fetch('http://127.0.0.1:8080/api/tasks',{
58+
res = await fetch(this.todo_api_url,{
5559
method: 'PUT',
5660
body: JSON.stringify(task),
5761
headers: {"Content-Type": "application/json"}
@@ -61,7 +65,7 @@ export default class Dashboard extends Component {
6165
}
6266
}
6367
else {
64-
res = await fetch('http://127.0.0.1:8080/api/tasks',{
68+
res = await fetch(this.todo_api_url,{
6569
method: 'POST',
6670
body: JSON.stringify(task),
6771
headers: {"Content-Type": "application/json"}
@@ -77,7 +81,7 @@ export default class Dashboard extends Component {
7781
}
7882

7983
async deleteTask(id) {
80-
var res = await fetch('http://127.0.0.1:8080/api/tasks?id=' + id,{
84+
var res = await fetch(this.todo_api_url + '?id=' + id,{
8185
method: 'DELETE',
8286
headers: {"Content-Type": "application/json"}
8387
});
@@ -91,7 +95,7 @@ export default class Dashboard extends Component {
9195
}
9296

9397
async getTasks() {
94-
const response = await fetch('http://127.0.0.1:8080/api/tasks');
98+
const response = await fetch(this.todo_api_url);
9599
const body = await response.json();
96100
if (response.status !== 200) {
97101
throw Error(body.message)

‎media/demo.gif

233 KB
Loading

‎media/maxscale_gui_connect.png

91.2 KB
Loading

‎media/maxscale_gui_dashboard.png

271 KB
Loading

‎media/maxscale_gui_login.png

395 KB
Loading

‎media/maxscale_gui_queryeditor.png

93.2 KB
Loading

‎media/maxscale_gui_queryeditor_dashboard.png

441 KB
Loading

‎media/mql_to_sql.png

160 KB
Loading

0 commit comments

Comments
 (0)