Places

Places

Places is a web application written in React.js and Node.js that, backed by the power of the MariaDB Node.js Connector and MariaDB platform, allows you to record all of your favorite locations!

The following will walk you through the steps for getting this application up and running (locally) within minutes! This application is completely open source. Please feel free to use it and the source code as you see fit.

Table of Contents

1. Environment and Compatibility
2. Overview
   1. Introduction to MariaDB
   2. Using JSON in a relational database
3. Requirements
4. Getting started
   1. Grab the code
   2. Build the code
   3. Run the app
5. JSON Data Models
6. Support and Contribution
7. License

Environment and Compatibility

This application was created using the following techologies:

• MariaDB
• React.js (v.16.11.0)
• Node.js (v.12.x)
• NPM (v.6.11.3)

This application was tested on macOS Mojave v.10.14.6.

Overview

Introduction to MariaDB

MariaDB platform unifies MariaDB TX (transactions) and MariaDB AX (analytics) so transactional applications can retain unlimited historical data and leverage powerful, real-time analytics in order to provide data-driven customers with more information, actionable insight and greater value – and businesses with endless ways to monetize data. It is the enterprise open source database for hybrid transactional/analytical processing at scale.

Using JSON in a relational database

JSON is fast becoming the standard format for data interchange and for unstructured data, and MariaDB Platform (in fact, all MariaDB versions 10.2 and later) include a range of JSON supporting functions.

The Places application uses only a single table for all location, and uses JSON to store more specific information based on the location type.

CREATE TABLE `Locations` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(100) NOT NULL DEFAULT '',
  `description` varchar(500) DEFAULT '',
  `type` char(1) NOT NULL DEFAULT '',
  `latitude` decimal(9,6) NOT NULL,
  `longitude` decimal(9,6) NOT NULL,
  `attr` longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL CHECK (json_valid(`attr`)),
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=19 DEFAULT CHARSET=utf8mb4;

For more information on how JSON can be used within MariaDB please check out this blog post!

Requirements

This project assumes you have familiarity with building web applications using ReactJS and NodeJS technologies.

• Download and install MariaDB.
• Download and install NodeJS.
• git (Optional) - this is required if you would prefer to pull the source code from GitHub repo.
  • Create a free github account if you don’t already have one
  • git can be downloaded from git-scm.org

Getting started

In order to run the Places application you will need to have a MariaDB instance to connect to. For more information please check out "Get Started with MariaDB".

In order to build and run the Places applications you will need to have NodeJS installed. You can find more information here.

Create the schema

Using CLI or SQL client run the following SQL command:

CREATE TABLE `Locations` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(100) NOT NULL DEFAULT '',
  `description` varchar(500) DEFAULT '',
  `type` char(1) NOT NULL DEFAULT '',
  `latitude` decimal(9,6) NOT NULL,
  `longitude` decimal(9,6) NOT NULL,
  `attr` longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL CHECK (json_valid(`attr`)),
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=19 DEFAULT CHARSET=utf8mb4;

Grab the code

Download this code directly or use git (through CLI or a client) to retrieve the code.

Configure the code

The gist; Add a Google Maps API Key and database connection information to the code.

1. Once you've obtained a Google Maps API Key place add it to the code here.

export default GoogleApiWrapper({
    apiKey: ("ENTER_GOOGLE_API_KEY")
})(MapContainer)

2. Configure the MariaDB connection by adding an .env file to the Node.js project.

Example implementation:

DB_HOST=<host_address>
DB_PORT=<port_number>
DB_USER=<username>
DB_PASS=<password>
DB_NAME=<database>

The environmental variables from .env are used within the db.js for the MariaDB Node.js Connector configuration pool settings:

var mariadb = require('mariadb');
require('dotenv').config();

const pool = mariadb.createPool({
    host: process.env.DB_HOST, 
    user: process.env.DB_USER, 
    password: process.env.DB_PASS,
    port: process.env.DB_PORT,
    multipleStatements: true,
    connectionLimit: 5
});

Build the code

Once you have retrieved a copy of the code you're ready to build and run the project! However, before running the code it's important to point out that the application uses several Node Packages.

Executing the CLI command

npm install

within

• src: the Node.js project
• client: the React.js project

folders will target the the relative package.json file and install all dependencies.

Run the app

Once you've pulled down the code and have verified that all of the required Node packages are installed you're ready to run the application! It's as easy as 1,2,3.

1. Using a command line interface (CLI) navigate to where to the src directory of Places.

2. Run the command:

npm start

3. Open a browser window and navigate to http://localhost:3000.

JSON Data Models

Below are samples of the data model per Location Type.

Attraction

{
   "category":"Landmark",
   "lastVisitDate":"11/5/2019"
}

Location

{
   "details":{
      "foodType":"Pizza",
      "menu":"www.giodanos.com/menu"
   },
   "favorites":[
      {
         "description":"Classic Chicago",
         "price":24.99
      },
      {
         "description":"Salad",
         "price":9.99
      }
   ]
}

Sports Venue

{
   "details":{
      "yearOpened":1994,
      "capacity":23500
   },
   "events":[
      {
         "date":"10/18/2019",
         "description":"Bulls vs Celtics"
      },
      {
         "date":"10/21/2019",
         "description":"Bulls vs Lakers"
      },
      {
         "date":"11/5/2019",
         "description":"Bulls vs Bucks"
      },
      {
         "date":"11/5/2019",
         "description":"Blackhawks vs Blues"
      }
   ]
}

Support and Contribution

Thanks so much for taking a look at the Places app! As this is a very simple example,there's a lot of potential for customization!

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] or on Twitter.

License