https://github.com/datumbrain/alembic-starter
Alembic starter project with PostgreSQL.
https://github.com/datumbrain/alembic-starter
Last synced: 9 months ago
JSON representation
Alembic starter project with PostgreSQL.
- Host: GitHub
- URL: https://github.com/datumbrain/alembic-starter
- Owner: datumbrain
- Created: 2025-06-04T08:49:59.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-04T08:56:23.000Z (12 months ago)
- Last Synced: 2025-08-31T16:04:11.138Z (9 months ago)
- Language: Python
- Size: 14.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Alembic SQLAlchemy PostgreSQL Starter
A complete starter project for Python applications using Alembic for database migrations, SQLAlchemy for ORM, and PostgreSQL as the database.
## Project Structure
```raw
alembic-starter/
├── main.py
├── requirements.txt
├── .env.example
├── .gitignore
├── alembic.ini
├── alembic/
│ ├── __init__.py
│ ├── env.py
│ ├── script.py.mako
│ └── versions/
│ └── __init__.py
├── models/
│ ├── __init__.py
│ ├── base.py
│ └── user.py
├── database/
│ ├── __init__.py
│ └── connection.py
└── README.md
```
- `main.py` - Main application entry point
- `database/connection.py` - Database configuration and session management
- `models/` - SQLAlchemy models
- `alembic/` - Migration files and configuration
- `requirements.txt` - Python dependencies
- `.env` - Environment variables (create from .env.example)
## Features
- ✅ Alembic for database migrations
- ✅ SQLAlchemy 2.0 with modern syntax
- ✅ PostgreSQL integration
- ✅ Environment-based configuration
- ✅ Base model with common fields
- ✅ Sample User model
- ✅ Proper project structure
## Quick Start
### 1. Setup Environment
```bash
# Clone or create project directory
cd alembic-starter
# Create virtual environment
pipenv shell
pipenv install
```
### 2. Configure Database
```bash
# Copy environment template
cp .env.example .env
```
### 3. Initialize Alembic (if starting fresh)
This creates the alembic folder structure
```bash
alembic init alembic
```
### 4. Create Initial Migration
```bash
# Generate initial migration from models
alembic revision --autogenerate -m "Initial migration"
# Apply migrations
alembic upgrade head
```
### 5. Test the Setup
```bash
# Run the main script to test everything
python main.py
```
## Common Commands
```bash
# Create new migration
alembic revision --autogenerate -m "Description of changes"
# Apply migrations
alembic upgrade head
# Rollback migration
alembic downgrade -1
# Show migration history
alembic history
# Show current revision
alembic current
```
## Adding New Models
1. Create model file in `models/` directory
2. Import the model in `alembic/env.py`
3. Generate migration: `alembic revision --autogenerate -m "Add new model"`
4. Apply migration: `alembic upgrade head`
## Environment Variables
- `DATABASE_URL` - Complete PostgreSQL connection string
- `POSTGRES_USER` - Database username
- `POSTGRES_PASSWORD` - Database password
- `POSTGRES_HOST` - Database host (default: localhost)
- `POSTGRES_PORT` - Database port (default: 5432)
- `POSTGRES_DB` - Database name
## Tips
- Always review generated migrations before applying them
- Use descriptive names for your migrations
- Test migrations on a copy of production data
- Keep your models in sync with your database schema
- Use `alembic history` to track migration changes
## Setup Instructions
1. **Create the project directory and files** using the structure above
2. **Set up virtual environment:**
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
# or
venv\Scripts\activate # Windows
```
3. **Install dependencies:**
```bash
pip install -r requirements.txt
```
4. **Configure environment:**
```bash
cp .env.example .env
# Edit .env with your PostgreSQL credentials
```
5. **Create initial migration:**
```bash
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head
```
6. **Test the setup:**
```bash
python main.py
```
This starter provides a solid foundation with proper separation of concerns,
environment configuration, and follows SQLAlchemy 2.0 best practices.