Database Connection

db_plugins is an ORM style library created to interact with different databases. The main feature of these plugins is to provide an interface for database querying, reducing the amount of code and helping to decouple components.

1. Plugins

ALeRCE integrates with databases through plugins. Each plugin is supposed to provide functionality for a specific database engine.

The design concept is that there are multiple database connections but all of them share the same interface so that connecting to any provided engine is done in a similar way.

This provides a way to connect and query different database engines using the same methods and classes, for example a database connection db has a query method that returns a BaseQuery object that has methods for inserting, updating or getting paginated results from a SQL database, but it also works the same way for a Mongodb database.

This also provides the option to change database engines without having to change the application structure too much.

2. Database Initialization

Database plugins will read the configuration you define in a settings.py file. This file should have a DB_CONFIG dictionary with the database connection parameters.

Here is and example on the params used with the SQL plugin:

DB_CONFIG: {
    "SQL": {
      "ENGINE": "postgresql",
      "HOST": "host",
      "USER": "username",
      "PASSWORD": "pwd",
      "PORT": 5432, # postgresql tipically runs on port 5432. Notice that we use an int here.
      "DB_NAME": "database",
    }
}

After defining DB_CONFIG you can now initiaize your database. To do so, run the initdb command as follows

dbp initdb

3. Migrations

When changes to models are made you would want to update the database without creating it all again, or maybe you want to undo some changes and return to a previous state.

The solution is to create migrations. Migrations keep track of your database changes and let you detect differences between your database and models and update the database accordingly.

Migrations will be created by running dbp make_migrations. This command will read your database credentials from DB_CONFIG inside settings.py.

Then, to update your database to latest changes execute dbp migrate.