Migrações

O que é o SQL-Migrate?

SQL-Migrate é uma CLI escrita em Golang utilizada para fazer migrações de banco.

Um migração de banco pode ser tanto uma migração de dados, quando é necessário a transformação de um dado de um tipo para outro, ou quando é necessária a transformação da estrutura de uma tabela, alterando ela.

SQL-Migrate tem suporte a bancos SQLite, PostgreSQL, MySQL, MSSQL e Oracal. Podendo ser utilizado como uma biblioteca caso sua aplicação seja desenvolvida em Go. Outras features do SQL-Migrate são:

Todas as migrações são escritas em SQL;
Foco em migrações atomicas;
Permite migrações up/down, ou seja, permite migrações de rollback;
Permite suporte a multiplos bancos de dado em um unico projeto;

Como utilizar o SQL-Migrate

Nesta seção você irá encontrar informações sobre:

Instalando Golang

Para utilizar a ferramenta, é necessário ter instalado em sua máquina Golang, caso já tenha, você pode ir para a instalação da ferramenta.

Para instalar o Golang, acesse seu site e realiza o donwload do binário seguindo as instruções de instalação do site.

Instalando a ferramenta

Com o Golang em mãos, através do terminal insira este comando:

go get -v github.com/rubenv/sql-migrate/...

Neste comando, utilizamos o Golang para fazer o download do pacote binário do SQL-Migrate, semelhante ao fazer o donwload de algo utilizando o wget, o parametro -v serve para tornar a saída do comando verbosa.

Conhecendo a ferramenta

Por se tratar de uma CLI, para executar o SQL-Migrate, ver suas opções e informações sobre, devemos utilizar o terminal. Vá até seu terminal e escreva:

sql-migrate --help

Com isso você verá todas as opções gerais dos comandos da ferramenta, caso você deseja saber mais sobre algum comando em específico e seus parametros, você pode executar sql-migrate {comando} --help.

Antes de executar algum comando você deve saber o que é necessário para que suas migrações funcionem. Cada comando necessita de um arquivo de configuração (que é o mesmo arquivo para todos os comandos), por padrão utilizamos o nome dbconfig.yml que é o nome padrão que a ferramenta utiliza, mas você pode especificar um arquivo com a flag -config em todos os comandos.

A respeito deste arquivo de configuração, você pode ver diversos exemplos do que pode ser escrito em seu conteúdo clicando aqui, falaremos brevemente dele.

Neste arquivo de configuração, devemos informar:

O dialeto do nosso banco, ou seja, qual o banco que estamos utilizando;
As configurações para ambientes específicos, ou seja, uma configuraão para o ambiente de desenvolvimento e/ou outra para o ambiente de produção;
O diretório onde se encontram as nossas migrações;
A URL do nosso banco;
O nome da nossa tabela que irá armazenar o histórico de migrações;

Clique aqui para visualizar um exemplo do nosso produto.

Criando o arquivo de migração

Para criar um novo arquivo de migração, se dirija até o diretório onde se encontra seu arquivo de configuração, ou o informe atraǘes da flag -config no comando new, como mostrado a baixo:

sql-migrate new create_table_rules -config ./migrations/webfilter/dbconfig.yml

Para saber a respeito dos padrões de nomenclatura das tabelas, campos e nomes de chaves, leia a respeito da documenação sobre como criar migrações de banco

Ao executar o comando, você verá que foi criado um novo arquivo de migração, com o nome iniciado por um numeral que representa a data do momento de criação do arquivo, é através disso que a ferramenta consegue se orientar e saber quais migrações devem ser excecutadas primeiro, na devida ordem.

Para executar as migrações você pode executar o comando sql-migrate up sempre lembrando de informar seu arquivo de configuração caso ele não se encontre no diretório que você está; O mesmo serve para desfazer uma migraação, sql-migrate down.

Como construir as migrações

Para manter as migrações de banco funcionado, deve ser pensado no nome para os índices e chave estrangeira. Se não definido o nome, o banco gera nome aleatório. E quando for altera o indice ou remover, não sera possível fazer pelo alembic. Pois é necessário saber o nome para executa a operação. Desta forma foi definido um padrão de nome, facilitando a identificação e manutenção dos índices e chave estrangeiras.

Todas as migrações são scripts SQL seguindo os padrões do MariaDB.

Sufixos (Suffixes)

Temos um padrão dos sufixos utilizados em nossos scripts SQL:

idx: índice
un: índice único
fk: chave estrangeira
ck: check (limite de valores na coluna)

Índice

FIELD_NAME: no caso de índice composto deve ser campo principal

{{ TABLE_NAME }}-{{ FIELD_NAME }}-{{ SUFFIX }}

Exemplo: auth_users-name-idx

Índice único

FIELD_NAME: no caso de índice composto deve ser campo principal

{{ TABLE_NAME }}-{{ FIELD_NAME }}-{{ SUFFIX }}

Exemplo: auth_users-name-un

Chave estrangeira

TABLE_REFERENCE_NAME: tabela associada na chave estrangeira
FIELD_NAME: campo da tabela associada na chave estrangeira

{{ TABLE_NAME }}-{{ TABLE_REFERENCE_NAME }}_{{ FIELD_NAME }}-{{ SUFFIX }}

Exemplo: auth_users_roles-roles_id-fk

Check

{{ TABLE_NAME }}-{{ FIELD_NAME }}-{{ SUFFIX }}

Exemplo: auth_users-superuser-ck

Rodar migrações

Para executar as migrações, você deve estar com elas na sua máquina virtual, nunca execute elas em sua máquina local.

Após criar sua migração, copie ela para a máquina virtual com este comando e mova para a pasta de migrações:

scp -r backend/migrations/[pasta com as migrações] root@[IP da VM]:/tmp
ssh [usuário]@[IP da VM]
sudo cp -rf /tmp/[pasta com as migrações] /usr/share/itflex/migrations/

Agora precisamos configurar algumas variaveis de ambiente para poder executar o script de migrações:

export MYSQL_HOST=”${MYSQL_HOST:=127.0.0.1}”
export MYSQL_PORT=”${MYSQL_PORT:=3306}”
export MYSQL_DATABASE=”${MYSQL_DATABASE:=itflex}”
export MYSQL_USER=”${MYSQL_USER:=itflex}”
export MYSQL_PASSWORD=”${MYSQL_PASSWORD:=itflex-pass}”

Com isso podemos executar o nosso script:

cd /usr/share/itflex
./run_migrations.sh