Improved db feature and adding documentation
This commit is contained in:
59
docs/README.md
Normal file
59
docs/README.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# General introduction
|
||||
|
||||
## What is MycroForge?
|
||||
|
||||
MycroForge is an opinionated CLI tool that is meant to facilitate the development of FastAPI & SQLAlchemy based backends.
|
||||
It provides a command line interface that allows users to generate a skeleton project and other common items like
|
||||
database entities, migrations, routers and even basic CRUD functionality. The main purpose of this tool is to generate
|
||||
boilerplate code and to provide a unified interface for performing recurrent development activities.
|
||||
|
||||
|
||||
## Generating a project
|
||||
|
||||
To generate a project you can run the following command.
|
||||
|
||||
`m4g init <name>`
|
||||
|
||||
```
|
||||
Description:
|
||||
Initialize a new project
|
||||
|
||||
Usage:
|
||||
m4g init <name> [options]
|
||||
|
||||
Arguments:
|
||||
<name> The name of your project
|
||||
|
||||
Options:
|
||||
--without <api|db|git> Features to exclude
|
||||
-?, -h, --help Show help and usage information
|
||||
|
||||
```
|
||||
|
||||
Running this command will generate
|
||||
|
||||
```
|
||||
📦<project_name>
|
||||
┣ 📂.git
|
||||
┣ 📂.venv
|
||||
┣ 📂api
|
||||
┃ ┗ 📂routers
|
||||
┃ ┃ ┗ 📜hello.py
|
||||
┣ 📂db
|
||||
┃ ┣ 📂engine
|
||||
┃ ┃ ┗ 📜async_session.py
|
||||
┃ ┣ 📂entities
|
||||
┃ ┃ ┗ 📜entity_base.py
|
||||
┃ ┣ 📂versions
|
||||
┃ ┣ 📜README
|
||||
┃ ┣ 📜env.py
|
||||
┃ ┣ 📜script.py.mako
|
||||
┃ ┗ 📜settings.py
|
||||
┣ 📜.gitignore
|
||||
┣ 📜alembic.ini
|
||||
┣ 📜db.docker-compose.yml
|
||||
┣ 📜m4g.json
|
||||
┣ 📜main.py
|
||||
┗ 📜requirements.txt
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Quick tutorial
|
||||
|
||||
Summary: We're gonna build a todo app to demonstrate how the `m4g` command works.<br/>
|
||||
Summary: We're gonna build a todo app to demonstrate how the `m4g` command line tool works.<br/>
|
||||
TODO: Supplement this section.
|
||||
|
||||
## Initialize the project
|
||||
@@ -12,71 +12,9 @@ this command. If you prefer using another editor, then manually open the generat
|
||||
|
||||
## Setup the database
|
||||
|
||||
Summary: This section explains how to interact with the database.
|
||||
TODO: Supplement this section.
|
||||
### Start the database
|
||||
|
||||
### Create a docker compose file for the database
|
||||
|
||||
Create a file called `docker-compose.yml` in the root of your project with the following content.
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
# MariaDB for the database
|
||||
todo_db:
|
||||
image: 'mariadb:10.4'
|
||||
container_name: 'todo_db'
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- default
|
||||
ports:
|
||||
- '3306:3306'
|
||||
environment:
|
||||
MYSQL_ROOT_PASSWORD: 'root'
|
||||
MYSQL_USER: 'root'
|
||||
MYSQL_PASSWORD: 'root'
|
||||
MYSQL_DATABASE: 'todo'
|
||||
volumes:
|
||||
- 'todo_db:/var/lib/mysql'
|
||||
|
||||
# PhpMyAdmin for the database UI
|
||||
phpmyadmin:
|
||||
image: phpmyadmin/phpmyadmin
|
||||
container_name: phpmyadmin
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- 8888:80
|
||||
networks:
|
||||
- default
|
||||
environment:
|
||||
PMA_HOST: todo_db
|
||||
PMA_PORT: 3306
|
||||
PMA_ARBITRARY: 1
|
||||
links:
|
||||
- todo_db
|
||||
|
||||
volumes:
|
||||
todo_db:
|
||||
```
|
||||
|
||||
Run `docker compose up -d` to start the database containers.<br/>
|
||||
You should now be able to log into the database server at http://localhost:8888, with the following credentials.<br/>
|
||||
**username**: root, **password**: root
|
||||
|
||||
### Update the database connectionstring
|
||||
|
||||
Replace the contents of `db/settings.py` with the following.
|
||||
|
||||
```python
|
||||
class DbSettings:
|
||||
def get_connectionstring() -> str:
|
||||
connectionstring = "mysql+asyncmy://root:root@localhost:3306/todo"
|
||||
return connectionstring
|
||||
```
|
||||
|
||||
The connectionstring has been hardcoded for demo purposes.
|
||||
In a production app, you would use some kind of secret manager to retrieve it.
|
||||
`m4g db run`
|
||||
|
||||
### Create the entities
|
||||
|
||||
@@ -96,7 +34,9 @@ In a production app, you would use some kind of secret manager to retrieve it.
|
||||
|
||||
`m4g db migrate`
|
||||
|
||||
If you inspect the database in [PhpMyAdmin](http://localhost:8888), you should now see a populated schema.
|
||||
If you inspect the database in [PhpMyAdmin](http://localhost:5051), you should now see a populated schema.
|
||||
|
||||
To stop the database, you can run `m4g db stop`
|
||||
|
||||
## Setup the API
|
||||
|
||||
@@ -106,126 +46,160 @@ If you inspect the database in [PhpMyAdmin](http://localhost:8888), you should n
|
||||
|
||||
`m4g api generate crud Todo`
|
||||
|
||||
### Modify the generated Todo request classes
|
||||
|
||||
Modify `CreateTodoRequest` in `api/requests/create_todo_request.py`, you might need to import `List` from `typing`
|
||||
|
||||
```python
|
||||
# Before
|
||||
class CreateTodoRequest(BaseModel):
|
||||
description: str = None
|
||||
is_done: bool = None
|
||||
|
||||
# After
|
||||
class CreateTodoRequest(BaseModel):
|
||||
description: str = None
|
||||
is_done: bool = None
|
||||
tag_ids: Optional[List[int]] = []
|
||||
```
|
||||
|
||||
Modify `UpdateTodoRequest` in `api/requests/update_todo_request.py`, you might need to import `List` from `typing`
|
||||
|
||||
```python
|
||||
# Before
|
||||
class UpdateTodoRequest(BaseModel):
|
||||
description: Optional[str] = None
|
||||
is_done: Optional[bool] = None
|
||||
tag_ids: Optional[List[int]] = []
|
||||
|
||||
# After
|
||||
class UpdateTodoRequest(BaseModel):
|
||||
description: Optional[str] = None
|
||||
is_done: Optional[bool] = None
|
||||
tag_ids: Optional[List[int]] = []
|
||||
```
|
||||
|
||||
### Modify generated TodoService
|
||||
|
||||
Add the following import in `api/services/todo_service.py`.
|
||||
Add the following imports in `api/services/todo_service.py`.
|
||||
|
||||
`from sqlalchemy.orm import selectinload`
|
||||
```python
|
||||
from sqlalchemy.orm import selectinload
|
||||
from db.entities.tag import Tag
|
||||
```
|
||||
|
||||
Modify `TodoService.list`
|
||||
|
||||
```python
|
||||
# Before
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo)
|
||||
results = (await session.scalars(stmt)).all()
|
||||
return results
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo)
|
||||
results = (await session.scalars(stmt)).all()
|
||||
return results
|
||||
|
||||
# After
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).options(selectinload(Todo.tags))
|
||||
results = (await session.scalars(stmt)).all()
|
||||
return results
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).options(selectinload(Todo.tags))
|
||||
results = (await session.scalars(stmt)).all()
|
||||
return results
|
||||
```
|
||||
|
||||
Modify `TodoService.get_by_id`
|
||||
|
||||
```python
|
||||
# Before
|
||||
async def get_by_id(self, id: int) -> Optional[Todo]:
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id)
|
||||
result = (await session.scalars(stmt)).first()
|
||||
return result
|
||||
async def get_by_id(self, id: int) -> Optional[Todo]:
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id)
|
||||
result = (await session.scalars(stmt)).first()
|
||||
return result
|
||||
|
||||
# After
|
||||
async def get_by_id(self, id: int) -> Optional[Todo]:
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id).options(selectinload(Todo.tags))
|
||||
result = (await session.scalars(stmt)).first()
|
||||
return result
|
||||
async def get_by_id(self, id: int) -> Optional[Todo]:
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id).options(selectinload(Todo.tags))
|
||||
result = (await session.scalars(stmt)).first()
|
||||
return result
|
||||
```
|
||||
|
||||
Modify `TodoService.create`
|
||||
|
||||
```python
|
||||
# Before
|
||||
async def create(self, data: Dict[str, Any]) -> None:
|
||||
async with async_session() as session:
|
||||
entity = Todo(**data)
|
||||
session.add(entity)
|
||||
await session.commit()
|
||||
|
||||
async def create(self, data: Dict[str, Any]) -> None:
|
||||
async with async_session() as session:
|
||||
entity = Todo(**data)
|
||||
session.add(entity)
|
||||
await session.commit()
|
||||
|
||||
# After
|
||||
async def create(self, data: Dict[str, Any]) -> None:
|
||||
tag_ids = []
|
||||
|
||||
if "tag_ids" in data.keys():
|
||||
tag_ids = data["tag_ids"]
|
||||
del data["tag_ids"]
|
||||
|
||||
async with async_session() as session:
|
||||
entity = Todo(**data)
|
||||
|
||||
if len(tag_ids) > 0:
|
||||
stmt = select(Tag).where(Tag.id.in_(tag_ids))
|
||||
result = (await session.scalars(stmt)).all()
|
||||
entity.tags = list(result)
|
||||
|
||||
session.add(entity)
|
||||
await session.commit()
|
||||
async def create(self, data: Dict[str, Any]) -> None:
|
||||
tag_ids = []
|
||||
|
||||
if "tag_ids" in data.keys():
|
||||
tag_ids = data["tag_ids"]
|
||||
del data["tag_ids"]
|
||||
|
||||
async with async_session() as session:
|
||||
entity = Todo(**data)
|
||||
|
||||
if len(tag_ids) > 0:
|
||||
stmt = select(Tag).where(Tag.id.in_(tag_ids))
|
||||
result = (await session.scalars(stmt)).all()
|
||||
entity.tags = list(result)
|
||||
|
||||
session.add(entity)
|
||||
await session.commit()
|
||||
```
|
||||
|
||||
Modify `TodoService.update`
|
||||
|
||||
```python
|
||||
# Before
|
||||
async def update(self, id: int, data: Dict[str, Any]) -> bool:
|
||||
tag_ids = []
|
||||
|
||||
if "tag_ids" in data.keys():
|
||||
tag_ids = data["tag_ids"]
|
||||
del data["tag_ids"]
|
||||
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id)
|
||||
entity = (await session.scalars(stmt)).first()
|
||||
|
||||
if entity is None:
|
||||
return False
|
||||
else:
|
||||
for key, value in data.items():
|
||||
setattr(entity, key, value)
|
||||
await session.commit()
|
||||
return True
|
||||
|
||||
async def update(self, id: int, data: Dict[str, Any]) -> bool:
|
||||
tag_ids = []
|
||||
|
||||
if "tag_ids" in data.keys():
|
||||
tag_ids = data["tag_ids"]
|
||||
del data["tag_ids"]
|
||||
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id)
|
||||
entity = (await session.scalars(stmt)).first()
|
||||
|
||||
if entity is None:
|
||||
return False
|
||||
else:
|
||||
for key, value in data.items():
|
||||
setattr(entity, key, value)
|
||||
await session.commit()
|
||||
return True
|
||||
|
||||
# After
|
||||
async def update(self, id: int, data: Dict[str, Any]) -> bool:
|
||||
tag_ids = []
|
||||
|
||||
if "tag_ids" in data.keys():
|
||||
tag_ids = data["tag_ids"]
|
||||
del data["tag_ids"]
|
||||
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id).options(selectinload(Todo.tags))
|
||||
entity = (await session.scalars(stmt)).first()
|
||||
|
||||
if entity is None:
|
||||
return False
|
||||
else:
|
||||
for key, value in data.items():
|
||||
setattr(entity, key, value)
|
||||
|
||||
if len(tag_ids) > 0:
|
||||
stmt = select(Tag).where(Tag.id.in_(tag_ids))
|
||||
result = (await session.scalars(stmt)).all()
|
||||
entity.tags = list(result)
|
||||
async def update(self, id: int, data: Dict[str, Any]) -> bool:
|
||||
tag_ids = []
|
||||
|
||||
if "tag_ids" in data.keys():
|
||||
tag_ids = data["tag_ids"]
|
||||
del data["tag_ids"]
|
||||
|
||||
async with async_session() as session:
|
||||
stmt = select(Todo).where(Todo.id == id).options(selectinload(Todo.tags))
|
||||
entity = (await session.scalars(stmt)).first()
|
||||
|
||||
if entity is None:
|
||||
return False
|
||||
else:
|
||||
entity.tags = []
|
||||
|
||||
await session.commit()
|
||||
return True
|
||||
for key, value in data.items():
|
||||
setattr(entity, key, value)
|
||||
|
||||
if len(tag_ids) > 0:
|
||||
stmt = select(Tag).where(Tag.id.in_(tag_ids))
|
||||
result = (await session.scalars(stmt)).all()
|
||||
entity.tags = list(result)
|
||||
else:
|
||||
entity.tags = []
|
||||
|
||||
await session.commit()
|
||||
return True
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user