Database Migration

If you plan to extend NexoPOS with modules, then you might consider interacting with the database. But unless you plan to use the existing database, you'll need to create your tables or maybe add 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 NexoPOS loses track of that migration. This can be made using the migration forget command.

# 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 migrations 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 update a table. Create separate migrations for both to avoid any confusion.

# Creating A Migration With A Command

NexoPOS 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 identifier. 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 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. For too large entries to update, you might consider dispatching an asynchronous job.

# Creating Role And Permissions

The migrations are the perfect place to create Roles and Permissions 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 to do (up) and undo (down) a modification on the database. This means if you would like NexoPOS to perform a modification on the database, you'll write your code on the "up" method. When your module is uninstalled, NexoPOS will execute the "down" method for all of your migrations.

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.

# Migration Dependencies

You might sometimes want a migration to execute if another module on your system is installed and enabled. This will ensure, in case you want to change the schema of that module, that the module tables beforehand are created.

You'll just need to provide a DEPENDENCIES constant to your module, which is an array with modules "namespace".

In this example, the "up()" method will only execute if the module "NsGastro" (which is the Gastro module namespace) is installed and enabled. Note that the migration might depend on multiple modules at the time.

This means the module "YourModule" can behave normally and will automatically update the schema anytime Gastro gets installed and enabled. This will ensure the module works with and without the dependencies.

# How To Execute Migrations

You don't need to execute a migration, NexoPOS 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 to execute that migration again. In order to keep NexoPOS 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