Database Migration

If you plan to extend NexoPOS 4.x with modules, then you consider interacting with the database. But unless you plan to use the existing database, you'll need to create your tables or maybe adding new columns to existing tables. This guide will describe how you can create migrations for your module.

# What is a migration

A migration stands for a file that executes during an upgrade process that aims to mutate the database schema. But it's not limited to that as it can be used to :

• Create new permissions & roles
• Perform a bulk modification on current entries
• Etc.

Note that once a migration has been executed, it cannot be executed again unless the record for that migration is deleted from the database.

# Migrations Best Practices

Migrations are stored within the folder "Migrations" of your module. Unlike Laravel migrations, PSR-4 applies to these files, and then, the class name much matches the file name. You're not forced to create migration manually as you can use the command that will be shared below.

The best technique is to provide a unique name for each of your migration even if the task is performed on the same table.

Usually, migrations that update existing tables should start with "Update", ie: "UpdateBookingTableMarch10" or "UpdateBookingTablePriceColumn", either way, you need to make sure the name is unique as you might need to create another migration for that table in the future.

In case you want to create new tables on your migration file, your file name might start with "Create", for example, "CreateBookingTable".

A migration file that creates a table should not edit a table. Create separate migration for both to avoid any confusion.

# Creating A Migration With A Command

NexoPOS 4.x comes with a command that helps you to create a migration for your module. Here is the signature of that command :

php artisan modules:migration {moduleNamespace}

Where {moduleNamespace} must be replaced by your actual module namespace. Right after having submitted this command, you'll be asked to provide the name of your migration.

The prompt will remain open for subsequent migrations, use Q to quit.

On your Migrations directory, you'll be able to see your migration file.

# How To Create A Table

As NexoPOS 4.x is based on Laravel, you'll need to follow the instructions shared on the Laravel documentation regarding migrations. However, as the migration file might be executed more than once, we'll invite you to perform verification and check if :

• The table you would like to create exists
• The column you would like to add/remove exists

These are described in the same documentation here.

# Mass Update For Existing Records

If you have some entries on your system, after having performed a migration that changes a structure, you can pull these entries using their model to perform a bulk update.

# Creating Role And Permissions

The migrations are the perfect place to create Roles and Permission for your module. You can follow the instructions that are shared on creating a Role and Permission.

# What Are The "up" and "down" methods

These methods are used by NexoPOS 4.x to do (up) and undo (down) a modification on the database. This means if you would like NexoPOS 4.x to perform a modification on the database, you'll write your code on the "up" method. When your module will be uninstalled, NexoPOS 4.x will execute the "down" method for all of your migration.

Usually, we don't undo columns added on tables that are created by the module. But to undo changes added on external tables, you'll need once again to check if that column exists.

# How To Execute Migrations

You don't need to execute a migration, NexoPOS 4.x will perform the migration automatically. Every time a migration is performed for the module, a record is saved on the "modules_migrations" table. Deleting that record will force NexoPOS 4.x to execute that migration again. In order to keep NexoPOS 4.x fast, all migrations executed are cached to avoid unnecessary calls to the database. You'll then need to clear the chase using the following command :

php artisan cache:clear