Changing and Managing Your Database

Introduction

While the setup script will install configure a database for you, it will not install the actual database for you. You must already have your database of choice installed on your machine, or remotely. If you chose a certain database at the setup, then it will have attempted to set that up with Donation Store. You my want to change to a different database, configure your existing database or you might want to just know how your database works with Donation Store.

This doc will explain how Donation Store works with your database, how to change your db and how to configure and manage the database.

The Database Driver

The database driver is the Python library that must be installed in your virtual environment so that Donation Store can connect to your database. Your virtual environment is just the container where all of the Python libraries Donation Store needs live, including things like Django and Celery. Depending on your database, you will have to install the appropriate database driver.

Below is a list of all of the databases that Donation Store officially supports. Note that while these are the official databases, if there are third party drivers built for Django, they will more than likely work. If you are installing a particular driver, please read the documentation provided with it as it will explains dependencies that each driver may have.

Changing the Database Settings

Once you have installed the relevant driver, you must now tell Donation Store to point at the database by changing the configuration in the settings.py file, located at /home/donationstore/env/DonationStoreV2/settings.py

In the file you will see a variable named DATABASES, simply replace it with one of the following configurations, depending on your database:

DATABASES = {    
'default': {        
    'ENGINE': 'django.db.backends.mysql',        
    'NAME': 'database_name',        
    'USER': 'database_user',        
    'PASSWORD': 'database_password',
    'HOST': '127.0.0.1',
    'PORT': '3306'   
  }
}

DATABASES = {    
'default': {        
    'ENGINE': 'django.db.backends.postgresql',        
    'NAME': 'database_name',        
    'USER': 'database_user',        
    'PASSWORD': 'database_password',
    'HOST': '127.0.0.1',
    'PORT': '5432'   
  }
}

DATABASES = {    
'default': {        
    'ENGINE': 'django.db.backends.oracle',        
    'NAME': 'database_name',        
    'USER': 'database_user',        
    'PASSWORD': 'database_password',
    'HOST': '127.0.0.1',
    'PORT': '1521'   
  }
}

DATABASES = {    
'default': {        
    'ENGINE': 'django.db.backends.sqlite3',        
    'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
  }
}

Applying Migrations

Once you have set the configuration of the database, you need to Apply Migrations. Migrations are Python files that are found in /home/donationstore/env/controlpanel/migrations. They basically describe what has changed in the structure of the Donation Store database. The changes involve new tables being added, column values being changed etc. By applying the migrations, you are basically telling Donation Store to connect to your database and create any of the tables it needs to operate.

This action is required when setting Donation Store up for the first time, or also when an update is released that modifies the database and you need to get the new structure.

To apply migrations, simply activate you environment and run the migration script

source /home/donationstore/env/bin/activate
python3 /home/donationstore/env/manage.py migrate