https://github.com/codestorm-official/flask-postgres-starter
Flask Starter Project with PostgreSQL
https://github.com/codestorm-official/flask-postgres-starter
flask flask-api flask-starter
Last synced: 14 days ago
JSON representation
Flask Starter Project with PostgreSQL
- Host: GitHub
- URL: https://github.com/codestorm-official/flask-postgres-starter
- Owner: codestorm-official
- Created: 2025-07-12T05:41:42.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-02-20T22:17:50.000Z (5 months ago)
- Last Synced: 2026-02-23T22:49:19.146Z (4 months ago)
- Topics: flask, flask-api, flask-starter
- Language: Python
- Homepage:
- Size: 9.77 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Flask Starter Pack (w/ Postgres) 🚀
A robust starter pack or boilerplate for building production-ready APIs using Flask and PostgreSQL. This project is designed with **Clean Architecture** and **SOLID** principles in mind to ensure scalability and maintainability.
The main goal of this starter pack is to accelerate the development process by providing a well-structured foundation, allowing you to focus directly on business logic.
## ✨ Core Features & Tech Stack
* **Framework**: [Flask](https://flask.palletsprojects.com/)
* **Database**: [PostgreSQL](https://www.postgresql.org/)
* **Production Server**: [Gunicorn](https://gunicorn.org/)
* **Architecture**: **Layered Architecture** (API, Services, Models) that separates concerns.
* **ORM**: [Flask-SQLAlchemy](https://flask-sqlalchemy.palletsprojects.com/) for elegant database interaction.
* **Database Migrations**: [Flask-Migrate](https://flask-migrate.readthedocs.io/) (using Alembic) to safely manage schema changes.
* **Validation & Serialization**: [Flask-Marshmallow](https://flask-marshmallow.readthedocs.io/) for clean request validation and response serialization.
* **API Documentation**: [Flasgger](https://github.com/flasgger/flasgger) automatically generates **OpenAPI 3.0 (Swagger UI)** documentation.
* **Configuration**: Uses a `.env` file for secure management of environment variables.
---
## 🏛️ Project Structure
The directory structure is designed for scalability and code readability.
```sh
flask-postgres-starter/
├── app/
│ ├── __init__.py
│ ├── api/
│ ├── core/
│ ├── models/
│ ├── schemas/
│ ├── services/
│ └── utils/
├── migrations/
├── .env.example
├── .gitignore
├── .railway.json
├── run.py
└── requirements.txt
```
---
## ⚙️ Getting Started
Follow these steps to get the project running in your local environment.
### 1. Prerequisites
* Python 3.9+
* PostgreSQL installed and running.
* Create a new database in PostgreSQL for this project (e.g., `starter_db`).
### 2. Installation
1. **Clone this repository:**
```bash
git clone https://github.com/asepscareer/flask-postgres-starter.git
cd flask-postgres-starter
```
2. **Create and activate a virtual environment:**
```bash
python -m venv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
```
3. **Install all dependencies:**
```bash
pip install -r requirements.txt
```
4. **Configure Environment Variables:**
* Copy the `.env.example` file to `.env`.
```bash
cp .env.example .env
```
* Open the `.env` file and adjust the values, especially `DATABASE_URL` and `SECRET_KEY`.
```env
# Format: postgresql://:@:/
DATABASE_URL="postgresql://postgres:password@localhost:5432/starter_db"
SECRET_KEY="change-me-to-a-very-secret-key"
```
5. **Run Database Migrations:**
This command will create all the necessary tables in your database.
```bash
# Set FLASK_APP environment variable
export FLASK_APP=run.py # (use 'set' on Windows CMD)
# Initialize migrations (only once at the start of the project)
flask db init
# Create a migration file
flask db migrate -m "Initial migration."
# Apply the migration to the database
flask db upgrade
```
6. **Run the Development Server:**
```bash
flask run
```
The application is now running at `http://127.0.0.1:5000`.
---
## 📚 API Usage
The primary guide for using the API is the interactive Swagger UI documentation.
* **API Documentation (Swagger)**: Open your browser and navigate to `http://127.0.0.1:5000/apidocs`
You can see all available endpoints, data models, and even try the API directly from your browser.
### cURL Example: Creating a New User
```bash
curl -X POST [http://127.0.0.1:5000/api/v1/users/](http://127.0.0.1:5000/api/v1/users/) \
-H "Content-Type: application/json" \
-H "X-Request-ID: 12345" \
-d '{
"username": "cool_boss",
"email": "boss@cool.com"
}'
```
---
## 🚀 Running in Production
For a production environment, use Gunicorn as the WSGI server.
```bash
gunicorn --bind 0.0.0.0:8000 run:app
```
---
## 📄 License
This project is licensed under the MIT License.