Skip to content

Latest commit

 

History

History
60 lines (44 loc) · 3.27 KB

DB_MIGRATION.md

File metadata and controls

60 lines (44 loc) · 3.27 KB
Raw

DB Migration 🔀

By using the Java Persistence API (JPA), classed annotated by @Entity (in the model package) get mapped automatically to database tables/columns: src/main/resources/META-INF/jpa-persistence.xml

Important

However, when deleting, modifying or renaming an entity class/attribute, we have to manually update the underlying database structure.

Migration Scripts

Every time the webapp completes initialization, the DbMigrationHelper checks if there are any database migration scripts at src/main/resources/db/migration matching the current webapp version. You can find the version in pom.xml.

How to Add a New Migration Script

Follow these steps:

  1. Lookup the current webapp version in pom.xml
  2. Add a new file to src/main/resources/db/migration. E.g. 2003004.sql for version 2.3.4.
  3. Add the SQL script that will be executed on the TEST/PROD server.

Sample

Let's assume that you want to delete the text property from the Word entity. It would look like this:

ALTER TABLE `Word` DROP COLUMN `text`;

For an example of a previous database migration script, see https://github.com/elimu-ai/webapp/commit/9908537ced3b6d64849f7f9967399921dba3d3fc

Caveats 😅

Warning

Note that DB migration performed automatically by the ORM provider (Hibernate), e.g. when adding a new property to an @Entity, is executed before our custom migration scripts.

Warning

When making a change to an @Entity, keep the number of changes as small as possible. Do not make changes to multiple entities at once. Instead, keep things simple to avoid failures during the execution of the DB migration script.

Warning

Whenever an @Entity is modified, the underlying database schema in jpa-schema-export.sql will also be modified. Note that the database schema will not be automatically re-generated when you compile the source with mvn compile; Instead, you will have to run the webapp locally with mvn jetty:run for this file to be re-generated.

elimu.ai - Free open-source learning software for out-of-school children ✨🚀

Website 🌐  •  Wiki 📃  •  Projects 👩🏽‍💻  •  Milestones 🎯  •  Community 👋🏽  •  Support 💜