joojano/flyway-jpa

Exemplo simples de JPA com a ferramenta de migração Flyway

Flyway + JPA

Tópicos

• Descrição do projeto
• O que foi usado?
• Como rodar a aplicação?
  • Itens necessários para rodar a aplicação
  • Executando a aplicação
  • Executando as migrações
• Endpoints da aplicação
• Comandos do Flyway

Descrição do projeto

API REST básica para inserir e consultar usuários em um sistema, com ferramenta de migração de dados Flyway imbutida para versionamento de schema (migração de dados).

O que foi usado?

• Java 8, com as seguintes dependências:
  • Spring Boot 2.4.2
  • Spring Data
  • Lombok para redução de códigos comuns como getters/setters;
  • Driver PostgreSQL;
  • Flyway com Maven Wrapper para migração de dados;
• PostgreSQL 13.4;
• Docker v20.10.8

Como rodar a aplicação?

Itens necessários

• Docker;
• Docker Compose

Executando a aplicação

A API foi pré-construída para ser consumida imediatamente, e empacotada em uma imagem Docker. Adicionalmente, a dependência da aplicação, PostgreSQL, está incluída no arquivo docker-compose.yml.

Para executar toda a aplicação, clone este repositório, abra seu terminal e vá até a pasta onde o repositório está. Em seguida, execute o seguinte comando:

docker-compose up -d

Após a execução bem sucedida, você poderá acessar a API no endereço http://localhost:10000 e o banco de dados no endereço localhost:5432.

Executando as migrações

Para criação do banco de dados e dados de exemplo, são usados os arquivos .sql contidos na pasta src/main/resources/db/migration. Para implantar as migrações, vá até a pasta raiz e execute o seguinte comando:

./mvnw flyway:migrate

A aplicação irá implementar os SQLs no banco de dados.

Vale ressaltar que o mvnw pode não ter permissão para rodar no seu sistema. Caso esteja no Linux, execute o comando chmod +x mvnw para dar permissão de execução.

Endpoints da aplicação

Considerando a simplicidade da aplicação, foi optado pela não criação da especificação OpenAPI/Swagger. Portanto, segue abaixo os métodos da API.

Método	Caminho	Função	Body	Retorno
POST	/user	Insere um novo usuário no banco de dados	{ "username": "string", "password": "string" }	{ "id": uuid, "username": string, "password": string }
GET	/users	Lista todos os usuários	Não aplicável	[ { "id": uuid, "username": string, "password": string } ]

Comandos do Flyway

Comando	Comando via mvnw	Função
migrate	./mvnw flyway:migrate	Parte principal do Flyway, migra o schema para a última versão especificada. Caso a base de dados não esteja versionada, o comando irá criar uma tabela chamada “flyway_schema_history” e irá realizar as operações que estão contidas nos arquivos .sql em ordem de número de versão, do menor para o maior número de versão. Todas as migrations executadas são salvas na tabela supracitada, incluindo o checksum em CRC32.
clean	./mvnw flyway:clean	Limpa tudo dentro do schema, incluindo tabelas, views, procedures, etc.
info	./mvnw flyway:info	Imprime detalhes e informação de status sobre todas as migrations, incluindo as que ainda não foram executadas.
validate	./mvnw flyway:validate	Valida as migrações já aplicadas são as mesmas que estão localmente.
baseline	./mvnw flyway:baseline	Cria uma linha de base para uma base de dados já existente. Útil para bancos de dados que já existem. Depois do baseline, é possível realizar migrações normalmente.
repair	./mvnw flyway:repair	Repara a tabela de histórico de schema. Corrige falhas que aconteceram durante uma migração, podendo remover entradas de migração que falharam e “realinhar” checksums, descrições e tipos de migrações já aplicadas em relação às migrações locais.