File tree

8 files changed

+531
-0
lines changed

8 files changed

+531
-0
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "src/client"]
2+
path = src/client
3+
url = https://.com/mariadb-developers/todo-app-client
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# TODO
2+
3+
**TODO** is a web application that introduces you to the power, performance, and simplicity of [MariaDB](https://mariadb.com/products/).
4+
5+
This project uses the [MariaDB Python connector](https://.com/mariadb-corporation/mariadb-connector-python) in combination with the [SQLAlchemy (SQL and object-relational mapping toolkit)](https://www.sqlalchemy.org/) to connect to and communicate to a MariaDB database instance.
6+
7+
<p align="center" spacing="10">
8+
<kbd>
9+
<img src="media/demo.gif" />
10+
</kbd>
11+
</p>
12+
13+
This application is made of two parts:
14+
15+
* Client
16+
- web UI that communicates with REST endpoints available through an API app (see below).
17+
- is a React.js project located in the [client](src/client) folder.
18+
* API
19+
- uses the [MariaDB Python Connector](https://.com/mariadb-corporation/mariadb-connector-python) with [SQLAlchemy](https://www.sqlalchemy.org/) to connect to MariaDB.
20+
- is a Python project located int the [api](src/api) folder.
21+
22+
This README will walk you through the steps for getting the TODO web application up and running using MariaDB.
23+
24+
# Table of Contents
25+
1. [Requirements](#requirements)
26+
2. [Getting started with MariaDB](#mariadb)
27+
3. [Get the code](#code)
28+
4. [Create the database and table](#schema)
29+
5. [Configure, build and run the apps](#app)
30+
1. [Configure](#configure-api-app)
31+
2. [Create and activate a Python virtual environment](#activate-virtual-env)
32+
3. [Install Python packages](#install-python-packages)
33+
4. [Build and run the Python API app](#build-run-api)
34+
5. [Build and run the Client app](#build-run-client)
35+
6. [Support and contribution](#support-contribution)
36+
7. [License](#license)
37+
38+
## Requirements <a name="requirements"></a>
39+
40+
This sample application requires the following to be installed/enabled on your machine:
41+
42+
* [Python (v. 3+)](https://www.python.org/downloads/)
43+
* [MariaDB Connector/C (v. 3.1.5+)](https://mariadb.com/products/skysql/docs/clients/mariadb-connector-c-for-skysql-services/) (used by Connector/Python)
44+
* [Node.js (v. 12+)](https://nodejs.org/docs/latest-v12.x/api/index.html) (for the Client/UI app)
45+
* [NPM (v. 6+)](https://docs.npmjs.com/) (for the Client/UI app)
46+
* [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) (optional), used to connect to MariaDB database instances.
47+
48+
## 1.) Getting Started with MariaDB <a name="mariadb"></a>
49+
50+
[MariaDB](https://mariadb.com) is a community-developed, commercially supported relational database management system, and the database you'll be using for this application.
51+
52+
If you don't have a MariaDB database up and running you can find more information on how to download, install and start using a MariaDB database in the [MariaDB Quickstart Guide](https://.com/mariadb-developers/mariadb-getting-started).
53+
54+
## 2.) Get the code <a name="code"></a>
55+
56+
First, use [git](git-scm.org) (through CLI or a client) to retrieve the code using `git clone`:
57+
58+
```
59+
$ git clone https://.com/mariadb-developers/todo-app-python.git
60+
```
61+
62+
Next, because this repo uses a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), you will need to pull the [client application](https://.com/mariadb-developers/todo-app-client) using:
63+
64+
```bash
65+
$ git submodule update --init --recursive
66+
```
67+
68+
## 3.) Create the database and table <a name="schema"></a>
69+
70+
[Connect to your MariaDB database](https://mariadb.com/products/skysql/docs/clients/) (from [Step #2](#mariadb)) and execute the following SQL scripts using the following options:
71+
72+
a.) Use the [MariaDB command-line client](https://mariadb.com/products/skysql/docs/clients/mariadb-clients/mariadb-client/) to execute the SQL contained within [schema.sql](schema.sql).
73+
74+
_Example command:_
75+
```bash
76+
$ mariadb --host HOST_ADDRESS --port PORT_NO --user USER --password PASSWORD < schema.sql
77+
```
78+
79+
**OR**
80+
81+
b.) Copy, paste and execute the raw SQL commands contained in [schema.sql](schema.sql) using a [client of your choice](https://mariadb.com/products/skysql/docs/clients/).
82+
83+
```sql
84+
CREATE DATABASE todo;
85+
86+
CREATE TABLE todo.tasks (
87+
id INT(11) unsigned NOT NULL AUTO_INCREMENT,
88+
description VARCHAR(500) NOT NULL,
89+
completed BOOLEAN NOT NULL DEFAULT 0,
90+
PRIMARY KEY (id)
91+
);
92+
```
93+
94+
## 4.) Configure, Build and Run the App <a name="app"></a>
95+
96+
This application is made of two parts:
97+
98+
* Client
99+
- web UI that communicates with REST endpoints available through an API app (see below).
100+
- is a React.js project located in the [client](src/client) (/src/client) folder.
101+
* API
102+
- uses the [MariaDB Python Connector](https://.com/mariadb-corporation/mariadb-connector-python) with [SQLAlchemy](https://www.sqlalchemy.org/) to connect to MariaDB.
103+
- is a Python project located int the [api](src/api) folder.
104+
105+
The following steps, `a` through `e`, will walk you through the process of configuring, building and running the `api` and `client` applications.
106+
107+
### a.) Configure the app <a name="configure-api-app"></a>
108+
109+
Configure the MariaDB connection by adding an [.env file](https://pypi.org/project/python-dotenv/) to the project within the root folder.
110+
111+
Example implementation:
112+
113+
```
114+
DB_HOST=<host_address>
115+
DB_PORT=<port_number>
116+
DB_USER=<username>
117+
DB_PASS=<password>
118+
DB_NAME=todo
119+
```
120+
121+
**Configuring the connection**
122+
123+
The environmental variables from `.env` are used within [tasks.py](src/api/tasks.py) to confire the [SQLAlchemy connection engine](https://docs.sqlalchemy.org/en/13/core/connections.html) :
124+
125+
```python
126+
engine = sqlalchemy.create_engine(
127+
"mariadb+mariadbconnector://{0}:{1}@{2}:{3}/{4}".format(os.getenv("DB_USER"),os.getenv("DB_PASS"),os.getenv("DB_HOST"),os.getenv("DB_PORT"),os.getenv("DB_NAME")),
128+
echo=True)
129+
```
130+
131+
**Configuring .env and tasks.py for the MariaDB cloud database service [SkySQL](https://mariadb.com/products/skysql/)**
132+
133+
Note: MariaDB SkySQL requires SSL additions to connection. Details coming soon!
134+
135+
### b.) Create and activate a Python virtual environment <a name="activate-virtual-env"></a>
136+
137+
A virtual environment is a directory tree which contains Python executable files and other files which indicate that it is a virtual environment. Basically, it's the backbone for running your Python Flask app.
138+
139+
Creation of [virtual environments](https://docs.python.org/3/library/venv.html) is done by executing the following command (within [/src/api](src/api)):
140+
141+
```
142+
$ python3 -m venv venv
143+
```
144+
145+
**Tip**: Tip: pyvenv is only available in Python 3.4 or later. For older versions please use the [virtualenv](https://virtualenv.pypa.io/en/latest/) tool.
146+
147+
Before you can start installing or using packages in your virtual environment, you’ll need to activate it. Activating a virtual environment will put the virtual environment-specific python and pip executables into your shell’s PATH.
148+
149+
Activate the virtual environment using the following command (within [/src/api](src/api)):
150+
151+
```bash
152+
$ . venv/bin/activate activate
153+
```
154+
155+
### c.) Install Python packages <a name="install-python-packages"></a>
156+
157+
[Flask](https://flask.palletsprojects.com/en/1.1.x/?ref=hackernoon.com) is a micro web framework written in Python. It is classified as a [microframework](https://en.wikipedia.org/wiki/Microframework) because it does not require particular tools or libraries.
158+
159+
**TL;DR** It's what this app uses for the API.
160+
161+
This app also uses the MariaDB Python Connector to connect to and communicate with MariaDB databases.
162+
163+
Install the necessary packages by executing the following command (within [/src/api](src/api)):
164+
165+
```bash
166+
$ pip3 install flask mariadb python-dotenv SQLAlchemy
167+
```
168+
169+
### d.) Build and run the [API app](src/api) <a name="build-run-api"></a>
170+
171+
Once you've pulled down the code and have verified that all of the required packages are installed you're ready to run the application!
172+
173+
From [/src/api](src/api) execute the following CLI command to start the the Python project:
174+
175+
```bash
176+
$ python3 api.py
177+
```
178+
179+
**Note:** You will need to use seperate terminals for the `client` and `api` apps.
180+
181+
### e.) Build and run the [UI (Client) app](src/client) <a name="build-run-client"></a>
182+
183+
Once the API project is running you can now communicate with the exposed endpoints directly (via HTTP requests) or with the application UI, which is contained with the [client](src/client) folder of this repo.
184+
185+
To start the [client](src/client) application follow the instructions [here](https://.com/mariadb-developers/todo-app-client).
186+
187+
## Support and Contribution <a name="support-contribution"></a>
188+
189+
Please feel free to submit PR's, issues or requests to this project project directly.
190+
191+
If you have any other questions, comments, or looking for more information on MariaDB please check out:
192+
193+
* [MariaDB Developer Hub](https://mariadb.com/developers)
194+
* [MariaDB Community Slack](https://r.mariadb.com/join-community-slack)
195+
196+
Or reach out to us diretly via:
197+
198+
* [[email protected]](mailto:[email protected])
199+
* [MariaDB Twitter](https://twitter.com/mariadb)
200+
201+
## License <a name="license"></a>
202+
[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=plastic)](https://opensource.org/licenses/MIT)
Loading
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
share/python-wheels/
24+
*.egg-info/
25+
.installed.cfg
26+
*.egg
27+
MANIFEST
28+
29+
# PyInstaller
30+
# Usually these files are written by a python script from a template
31+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
32+
*.manifest
33+
*.spec
34+
35+
# Installer logs
36+
pip-log.txt
37+
pip-delete-this-directory.txt
38+
39+
# Unit test / coverage reports
40+
htmlcov/
41+
.tox/
42+
.nox/
43+
.coverage
44+
.coverage.*
45+
.cache
46+
nosetests.xml
47+
coverage.xml
48+
*.cover
49+
*.py,cover
50+
.hypothesis/
51+
.pytest_cache/
52+
cover/
53+
54+
# Translations
55+
*.mo
56+
*.pot
57+
58+
# Django stuff:
59+
*.log
60+
local_settings.py
61+
db.sqlite3
62+
db.sqlite3-journal
63+
64+
# Flask stuff:
65+
instance/
66+
.webassets-cache
67+
68+
# Scrapy stuff:
69+
.scrapy
70+
71+
# Sphinx documentation
72+
docs/_build/
73+
74+
# PyBuilder
75+
.pybuilder/
76+
target/
77+
78+
# Jupyter Notebook
79+
.ipynb_checkpoints
80+
81+
# IPython
82+
profile_default/
83+
ipython_config.py
84+
85+
# pyenv
86+
# For a library or package, you might want to ignore these files since the code is
87+
# intended to run in multiple environments; otherwise, check them in:
88+
# .python-version
89+
90+
# pipenv
91+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
93+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
94+
# install all needed dependencies.
95+
#Pipfile.lock
96+
97+
# PEP 582; used by e.g. .com/David-OConnor/pyflow
98+
__pypackages__/
99+
100+
# Celery stuff
101+
celerybeat-schedule
102+
celerybeat.pid
103+
104+
# SageMath parsed files
105+
*.sage.py
106+
107+
# Environments
108+
.env
109+
.venv
110+
env/
111+
venv/
112+
ENV/
113+
env.bak/
114+
venv.bak/
115+
116+
# Spyder project settings
117+
.spyderproject
118+
.spyproject
119+
120+
# Rope project settings
121+
.ropeproject
122+
123+
# mkdocs documentation
124+
/site
125+
126+
# mypy
127+
.mypy_cache/
128+
.dmypy.json
129+
dmypy.json
130+
131+
# Pyre type checker
132+
.pyre/
133+
134+
# pytype static type analyzer
135+
.pytype/
136+
137+
# Cython debug symbols
138+
cython_debug/

0 commit comments

Comments
 (0)