Quick Start

About 665 wordsAbout 2 min

Caution

fba is aimed at developers with some Python backend experience. If you are just starting with FastAPI, first get comfortable with Python async, FastAPI, SQLAlchemy, and Pydantic basics.

Local Development

Prepare the local environment
- Python 3.10+
- Install uv (current stable version recommended)
- PostgreSQL 16.0+ or MySQL 8.0+ Use Snowflake primary keysUse MySQL
- Redis (latest stable recommended)
Prepare the source code Choose one
Clone the repository
```
git clone https://github.com/fastapi-practices/fastapi-best-architecture.git
```
Create from template
This project supports GitHub template repositories. You can create a non-fork personal repository. On the project GitHub home page, use the use this template button as shown.
After creation, git clone your own repository.
Start PostgreSQL/MySQL and Redis
Initialize
Automatic
Open a terminal in the project root and run:
```
uv run fba init --auto
```
Manual
1. Create the database: fba
  - PostgreSQL users can create it directly
  - MySQL users should choose utf8mb4 encoding
2. env
  Open a terminal in the backend directory and create the env file:
  cp .env.example .env
3. Adjust config as needed: backend/core/conf.py and .env
4. Install dependencies
  uv - sync
  uv sync
  uv - pip
  uv pip install -r requirements.txt
5. Create tables and test data Choose one
  CLI
  Open a terminal in the project root (with the virtualenv activated) and run:
  fba init
  Alembic + Manual
  Open a terminal in the project root (with the virtualenv activated) and run:
  Generate a migration file
  fba alembic revision
  Apply migrations
  fba alembic upgrade
  Initialize test data
  Architecture: run the primary-key mode scripts under backend/sql/{mysql|postgresql}/
  Plugins: run the primary-key mode scripts under backend/plugin/{plugin}/sql/{mysql|postgresql}/
  fba --sql path/to/script
Start
Open a terminal in the project root (with the virtualenv activated) and run:
```
fba run
```
Start Celery worker, beat, and flower Optional — you can skip this
Open a terminal in the project root (with the virtualenv activated) and start Celery services:
Worker
```
fba celery worker
```
Beat
```
fba celery beat
```
Flower
```
fba celery flower
```
Warning
If these commands have never been run, task-result tables will be missing. Any API that depends on task results will fail until worker and beat have been started at least once, after which those APIs recover automatically.
Open the browser: http://127.0.0.1:8000/docs

Development Workflow

Tips

When using AI-assisted development, install fba skills first, then generate or review code in the order of model, schema, router, service, and crud.

Note

For reference only — follow your own development habits in practice.

Define database models (model)
Define validation models (schema)
Define routes (router)
Write business logic (service)
Write database operations (crud)

Unit Tests

Info

Unit tests are run with pytest. The project only provides basic test examples, not a full business suite. Add cases as needed for your domain.

Create the test database fba_test with utf8mb4 encoding (PostgreSQL users can ignore encoding)
Create tables: export DDL for all tables from the fba database, then apply it to fba_test
Initialize test data using scripts under backend/sql/{mysql|postgresql}/ for the matching primary-key mode
Open a terminal in the project root and run:
```
pytest -vs --disable-warnings
```