Migração de Banco de Dados

Se você planeja estender o NexoPOS com módulos, talvez queira considerar a interação com o banco de dados. Mas, a menos que você planeje usar o banco de dados existente, será necessário criar suas tabelas ou talvez adicionar novas colunas às tabelas existentes. Este guia descreverá como você pode criar migrações para seu módulo.

O que é uma migração

Uma migração representa um arquivo que é executado durante um processo de atualização com o objetivo de modificar o esquema do banco de dados. Mas ela não se limita a isso, pois pode ser usada para:

• Criar novas permissões e funções
• Efetuar uma modificação em massa nas entradas atuais
• Etc.

Observe que, depois que uma migração foi executada, ela não pode ser executada novamente, a menos que o NexoPOS perca o controle dessa migração. Isso pode ser feito usando o comando de migração forget.

Melhores Práticas de Migração

As migrações são armazenadas na pasta “Migrations” do seu módulo. Diferentemente das migrações do Laravel, o PSR-4 se aplica a esses arquivos e, em seguida, o nome da classe precisa corresponder muito ao nome do arquivo. Você não é obrigado a criar a migração manualmente, pois pode usar o comando que será compartilhado abaixo.

A melhor técnica é fornecer um nome exclusivo para cada uma de suas migrações, mesmo que a tarefa seja executada na mesma tabela.

Normalmente, migrações que atualizam tabelas existentes devem começar com “Update”, ou seja: “UpdateBookingTableMarch10” ou “UpdateBookingTablePriceColumn”. De qualquer forma, você precisa garantir que o nome seja único, pois pode ser necessário criar outra migração para essa tabela no futuro.

Se você quiser criar novas tabelas no seu arquivo de migração, o nome do arquivo pode começar com “Create”; por exemplo, “CreateBookingTable”.

Criando uma migração com um comando

O NexoPOS vem com um comando que ajuda você a criar uma migração para o seu módulo. Aqui está a assinatura desse comando:

php artisan modules:migration {moduleNamespace}

Onde {moduleNamespace} deve ser substituído pelo seu identificador de módulo real. Logo após enviar este comando, você será solicitado a fornecer o nome da sua migração.

O prompt permanecerá aberto para migrações subsequentes; digite "Q" para sair.

No seu diretório de Migrations, você poderá ver seu arquivo de migração.

Como criar uma tabela

Como o NexoPOS é construído sobre o Laravel, você precisará seguir as instruções na documentação do Laravel para migrations. No entanto, como o arquivo de migração pode ser executado mais de uma vez, convidaremos você a realizar a verificação e verificar se:

• A tabela que você deseja criar existe
• A coluna que você gostaria de adicionar/remover existe

Estes são descritos na mesma documentação aqui.

Atualização em Massa para Registros Existentes

Se você tiver algumas entradas no seu sistema, após ter executado uma migração que altera uma estrutura, você pode buscar essas entradas usando seu modelo para realizar uma atualização em massa. Para entradas grandes demais para atualizar, você pode considerar o envio de um job assíncrono.

Criando Funções e Permissões

As migrações são o local perfeito para criar Funções e Permissões para o seu módulo. Você pode seguir as instruções que estão disponibilizadas para criar uma Função e Permissão.

Quais são os métodos “up” e “down”?

O NexoPOS usa estes métodos para fazer (up) e desfazer (down) uma modificação no banco de dados. Isso significa que, se você quiser que o NexoPOS execute uma modificação no banco de dados, você escreverá seu código no método “up”. Quando seu módulo for desinstalado, o NexoPOS executará o método “down” para todas as suas migrações.

Normalmente, não desfazemos colunas adicionadas a tabelas criadas pelo módulo. Mas, para desfazer alterações adicionadas a tabelas externas, será necessário verificar novamente se essa coluna existe.

Dependências de Migração

Às vezes, você pode querer que uma migração seja executada se outro módulo no seu sistema estiver instalado e habilitado. Isso garantirá, caso você queira alterar o esquema desse módulo, que as tabelas do módulo sejam criadas.

Você só precisa fornecer uma constante DEPENDENCIES ao seu módulo, que é um array com módulos "namespace".

<?php
namespace Modules\YourModule\Migrations;

use App\Classes\Schema;
use Illuminate\Database\Schema\Blueprint;

class UpdateGastroModifiersGroup
{
    const DEPENDENCIES  =   [ 'NsGastro' ];
    
    public function up()
    {
        if ( ! Schema::hasTable('nexopos_gastro_modifiers_group') ) {
            Schema::table('nexopos_gastro_modifiers_group', function (Blueprint $table) {
                if (! Schema::hasColumn('nexopos_gastro_modifiers_group', 'wc_product_id')) {
                    $table->integer('wc_product_id')->nullable();
                }
            });
        }
    }
}

Neste exemplo, o método “up()” só será executado se o módulo “NsGastro” (que é o namespace do módulo Gastro) estiver instalado e habilitado. Observe que a migração pode depender de vários módulos ao mesmo tempo.

Isso significa que o módulo “YourModule” pode funcionar normalmente e atualizará automaticamente o esquema sempre que o Gastro for instalado e ativado. Isso garantirá que o módulo funcione com e sem as dependências.

# Como executar migrações

Você não precisa executar uma migração; o NexoPOS executará a migração automaticamente. Sempre que uma migração for realizada para o módulo, um registro é salvo na tabela “modules_migrations”. Excluir esse registro fará com que o NexoPOS execute essa migração novamente. Para manter o NexoPOS rápido, todas as migrações executadas são armazenadas em cache para evitar chamadas desnecessárias ao banco de dados. Em seguida, você precisará limpar o cache usando o seguinte comando:

php artisan cache:clear

Reverter migração do módulo

Durante o desenvolvimento do seu módulo, talvez você precise redefinir a migração criada até agora. Para isso, você usará o seguinte comando:

php artisan modules:migration --forget {moduleNamespace}

Certifique-se de substituir {moduleNamespace} pelo namespace do módulo para o qual deseja redefinir as migrações.