PyBoilerplate

Database

The boilerplate is pre-configured with two database options: SQLite3 and PostgreSQL. While SQLite3 is set up for rapid local development and PostgreSQL for production environments (both controlled through environment variables), you can easily configure any other database system that Django supports.

SQLite3

SQLite3 is ideal for development and testing environments due to its simplicity and zero-configuration nature.

 

To use SQLite3, set the following in your .env file:

# .env
DATABASE_TYPE=sqlite3

Note: To streamline development process, we've included a ready-to-use SQLite database (db.sqlite3) with pre-populated FAQs and Subscription Plans.

PostgreSQL

PostgreSQL is recommended for production environments and complex applications. The boilerplate is pre-configured to support both development and production PostgreSQL setups.

 

To use PostgreSQL, first enable it in your .env file:

# .env
DATABASE_TYPE=postgresql

 

Development Setup

Before you begin working on your project, follow these steps to set up your local development environment with PostgreSQL and the necessary configurations.

1. Install PostgreSQL and pgAdmin on your local machine

2. Create a new development database using pgAdmin

3. Configure the following environment variables in your .env file:

# .env
DATABASE_NAME_DEV=your_database_name
DATABASE_USER_DEV=postgres          # Default PostgreSQL user
DATABASE_PASSWORD_DEV=your_password # Set during PostgreSQL installation
DATABASE_HOST_DEV=localhost         # Default for local development

 

Production Setup

When deploying to Heroku, you can use their PostgreSQL add-on which provides a production-ready database instance.

1. Enable Heroku PostgreSQL

  • In your Heroku dashboard, go to your app's "Resources" tab
  • Search for "Heroku Postgres" in the Add-ons section
  • Select a plan that matches your needs

2. Get database credentials

  • In Resources tab, click on Heroku Postgres
  • In settings, you can "View Credentials ..."

3. Set up your database credentials both in your local .env file (for local testing with production data) and in your Heroku dashboard (Settings → Config Vars):

# .env
DATABASE_NAME=your_heroku_database_name
DATABASE_USER=your_heroku_database_user
DATABASE_PASSWORD=your_heroku_database_password
DATABASE_HOST=your_heroku_database_host

Note: For visual database management, we recommend Postico2 - a modern PostgreSQL client that offers an intuitive interface for handling your database data. It's particularly useful for viewing, editing, and managing your PostgreSQL databases.

Database Migrations

Database migrations are essential for managing your database structure over time. You'll need to run migrations when:

  • Switching between different databases
  • Making changes to your models (adding fields, changing relationships, etc.)
  • Setting up a new development environment
  • Deploying to production

 

Creating Migrations

When you make changes to your models, generate new migration files:

# Terminal
python manage.py makemigrations

This command:

  • Detect changes in your models.py files
  • Create new migration files in each app's migrations/ directory
  • Should be run after any model changes

 

Applying Migrations

To implement these changes in your database:

# Terminal
python manage.py migrate

This command:

  • Applies all pending migrations to your database
  • Creates tables and relationships based on your models
  • Updates existing tables if schema changes are detected
  • Should be run after creating new migrations

 

Resetting Database

When you need a fresh database setup, you only need to:

1. Drop your existing database (or delete db.sqlite3 file for SQLite) 

2. Create a new empty database 

3. Run existing migrations with python manage.py migrate

Note: Making new migrations (makemigrations) is not necessary when resetting a database since the migration files already exist and define your database structure.

Best Practices

  • Use SQLite for development if you don't need PostgreSQL-specific features
  • Always backup your database before switching database types
  • Keep sensitive database credentials in .env (never commit to version control)
  • Use different databases for development and production environments