1. Introdução ao Atlas
O Atlas é uma ferramenta independente de linguagem projetada especificamente para gerenciar e migrar esquemas de banco de dados usando princípios modernos de DevOps. Ele oferece duas opções de fluxo de trabalho:
- Declarativo: Semelhante ao Terraform, o Atlas compara o estado atual do banco de dados com o estado desejado definido usando HCL, SQL ou ORM schema. Com base nessa comparação, ele gera e executa um plano de migração para transicionar o banco de dados para o estado desejado.
- Versão: Ao contrário de outras ferramentas, o Atlas planeja automaticamente migrações de esquema para você. Os usuários podem descrever o esquema de banco de dados desejado usando HCL, SQL ou seu ORM escolhido e, com o Atlas, planejar, revisar e aplicar as migrações necessárias ao banco de dados.
Uma grande vantagem do Atlas é a simplificação da complexidade do gerenciamento de bancos de dados, tornando mais fácil o controle de versão, colaboração e implementação.
2. Instalando o Atlas
Antes de usar o Atlas para gerenciar as versões do banco de dados, é necessário instalá-lo. Abaixo estão os passos de instalação para diferentes plataformas.
2.1 Instalação no macOS + Linux
Em sistemas macOS ou Linux, você pode baixar e instalar a última versão do Atlas usando o seguinte comando de linha de comando:
curl -sSf https://atlasgo.sh | sh
Este comando detectará automaticamente a versão do sistema operacional, baixará a versão apropriada e colocará o arquivo binário do Atlas no caminho executável.
2.2 Instalando via Homebrew
Se você estiver usando macOS e já tiver instalado o gerenciador de pacotes Homebrew, instalar o Atlas é tão simples quanto executar o comando:
brew install ariga/tap/atlas
Isso buscará a última versão do Atlas no repositório do Homebrew e o instalará.
2.3 Instalação com Docker
Instalar e executar o Atlas através do Docker é um método rápido e conveniente, especialmente para testes temporários ou para usuários que preferem não instalar software adicional em seu sistema hospedeiro.
Primeiro, baixe a imagem Docker do Atlas:
docker pull arigaio/atlas
Em seguida, você pode executar um comando de ajuda para confirmar uma instalação bem-sucedida:
docker run --rm arigaio/atlas --help
Se o contêiner precisar acessar a rede do host ou diretórios locais, use a sinalização --net=host e monte os diretórios necessários:
docker run --rm --net=host \
-v $(pwd)/migrations:/migrations \
arigaio/atlas migrate apply \
--url "mysql://root:pass@:3306/test"
2.4 Instalação no Windows
Baixe o arquivo binário, https://release.ariga.io/atlas/atlas-windows-amd64-latest.exe, e adicione o caminho de instalação à variável de ambiente PATH do sistema.
3. Exportar a Estrutura da Tabela do Banco de Dados Existente Usando o Atlas
O Atlas fornece o comando atlas schema inspect, que pode ser usado para exportar a estrutura de um banco de dados existente. Este comando suporta a leitura de descrições de banco de dados a partir do URL do banco de dados e as exibe em três formatos diferentes: o formato padrão do Atlas HCL, o formato SQL e o formato JSON. Neste guia, mostraremos como usar os formatos Atlas HCL e SQL, pois o formato JSON é típicamente utilizado para processar a saída com o jq.
Para inspecionar uma instância local do MySQL e escrever a saída em um arquivo chamado schema.hcl, utilize o seguinte comando:
atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.hcl
Abra o arquivo schema.hcl para visualizar a definição da estrutura da tabela do Atlas que descreve o banco de dados (HCL é um formato de configuração de estrutura de tabela independente do banco de dados definido pelo Atlas). Por exemplo, este arquivo conterá o seguinte conteúdo:
table "users" {
schema = schema.example
column "id" {
null = false
type = int
}
column "name" {
null = true
type = varchar(100)
}
primary_key {
columns = [column.id]
}
}
Este bloco de código representa uma estrutura de tabela com as colunas id e name. O campo schema referencia a definição do modelo example definido em outro lugar neste documento. Além disso, o sub-bloco primary_key especifica a coluna id como a chave primária da tabela. O Atlas se esforça para imitar a sintaxe do banco de dados em operação. Neste exemplo, a coluna id tem um tipo int e a coluna name tem um tipo varchar(100).
Da mesma forma, para exportar uma definição do modelo SQL do banco de dados, você pode usar o seguinte comando:
atlas schema inspect -u "mysql://root:pass@localhost:3306/example" --format '{{ sql . }}' > schema.sql
Abra o arquivo schema.sql para visualizar a descrição SQL do banco de dados, normalmente contendo algumas declarações CREATE TABLE.
Esta abordagem torna conveniente entender os detalhes da estrutura da tabela do banco de dados existente e fornece uma referência precisa para migrações versionadas subsequentes.
4.1 Fluxo de Trabalho Declarativo
O Fluxo de Trabalho Declarativo do Atlas permite aos usuários definir de forma declarativa o estado final desejado do banco de dados. Os usuários só precisam descrever qual será o estado final da estrutura do esquema do banco de dados, e a ferramenta Atlas gerará e executará automaticamente planos de migração para transitar com segurança o esquema do banco de dados do estado atual para este estado esperado.
Abaixo está como usar o Fluxo de Trabalho Declarativo para definir e alcançar o estado desejado do banco de dados:
4.1.1 Definindo a Estrutura da Tabela Alvo
Primeiro, você precisa criar um arquivo definindo a estrutura esperada do banco de dados, que pode estar em formato HCL, SQL ou ORM (Mapeamento Objeto-Relacional).
Tomando o formato HCL como exemplo, defina uma nova tabela blog_posts:
table "blog_posts" {
schema = schema.example
column "id" {
null = false
type = int
}
column "title" {
null = true
type = varchar(100)
}
column "body" {
null = true
type = text
}
column "author_id" {
null = true
type = int
}
primary_key {
columns = [column.id]
}
foreign_key "author_fk" {
columns = [column.author_id]
ref_columns = [table.users.column.id]
}
}
Dica: A sintaxe do formato HCL será abordada em uma seção posterior.
4.1.2 Realizar Migração Usando a Ferramenta Atlas
Uma vez concluída a definição da estrutura da tabela do banco de dados, você pode usar o comando schema apply do Atlas para realizar a migração.
atlas schema apply \
-u "mysql://root:pass@localhost:3306/example" \
--to file://schema.hcl
Após executar o comando acima, o Atlas comparará o esquema do banco de dados existente com o esquema definido no arquivo, gerará um plano de migração e solicitará a confirmação do usuário para executar. Depois que o usuário confirmar o plano de execução, o Atlas realizará a migração no banco de dados e o atualizará para o estado desejado.
4.2 Fluxo de Trabalho Versionado
O fluxo de trabalho versionado é outro modo de uso suportado pelo Atlas, às vezes referido como "migração baseada em alterações". É adequado para cenários em que as mudanças no esquema do banco de dados precisam ser controladas por versão e revisadas no processo de revisão de código.
Os passos do fluxo de trabalho versionado incluem:
4.2.1 Calcular Diferenças
Antes de iniciar a migração, é necessário comparar a estrutura atual do banco de dados com o estado desejado e determinar as diferenças entre os dois. Isso pode ser feito executando o comando atlas migrate diff.
atlas migrate diff create_blog_posts \
--dir "file://migrations" \
--to "file://schema.hcl" \
--dev-url "docker://mysql/8/example"
O --dir especifica a URL da pasta de migração, com o padrão file://migrations. O --to especifica a URL do estado desejado (por exemplo, o banco de dados do seu ambiente de desenvolvimento) e --dev-url fornece uma URL para um banco de dados de desenvolvimento usado para calcular as diferenças (observe que esta --dev-url precisa especificar um banco de dados vazio que o Atlas usa para calcular as diferenças).
Dica: Se desejar gerar arquivos SQL, consulte a seção anterior para configurar o formato usando o parâmetro
--format.
4.2.2 Aplicar Alterações de Migração
Após o cálculo das diferenças, o Atlas gerará dois arquivos de migração salvos na pasta migrations. Por exemplo, se o formato selecionado for SQL, os arquivos gerados pelo comando diff, como o exemplo abaixo, conterão comandos de migração para criar uma nova tabela:
-- criar tabela "blog_posts"
CREATE TABLE `blog_posts` (
`id` int NOT NULL,
`title` varchar(100) DEFAULT NULL,
`body` text DEFAULT NULL,
`author_id` int NULL REFERENCES `users`(id),
PRIMARY KEY (`id`)
);
Uma vez que os arquivos de migração são gerados, é possível usar ferramentas de controle de versão (por exemplo, Git) para gerenciar essas alterações. Esse método permite fazer inúmeras modificações na estrutura da tabela do banco de dados no ambiente de desenvolvimento e, quando chegar a hora do lançamento, comparar o ambiente de desenvolvimento e o ambiente de testes, usando comandos do Atlas para gerar arquivos de migração da estrutura da tabela do banco de dados. Esses arquivos de migração podem então ser aplicados nos ambientes de teste e produção para atualizar o banco de dados.
Esses dois fluxos de trabalho, Declarativo e Versionado, oferecem flexibilidade para diferentes modos de desenvolvimento e implantação, permitindo que as equipes escolham o método que melhor se adapte às necessidades do projeto no gerenciamento de alterações no esquema do banco de dados.
5. Descrição do Formato HCL
5.1 Introdução
HCL é uma linguagem declarativa usada para descrever definições de estrutura de tabelas de banco de dados. O Atlas usa o formato HCL para escrever esquemas de banco de dados, proporcionando uma estrutura rica para descrever diferentes aspectos do banco de dados. A vantagem do HCL está em sua legibilidade, facilidade de manutenção e suporte a recursos como injeção de variáveis e anotações adicionais.
Dica: Se o projeto precisar se adaptar a vários bancos de dados, descrever as estruturas de tabelas de forma independente do banco de dados usando HCL pode ser muito conveniente.
5.2 Objeto schema
O objeto schema é usado para descrever um esquema de banco de dados. No MySQL e SQLite, representa o BANCO DE DADOS, enquanto no PostgreSQL, representa o ESQUEMA. Um arquivo HCL pode conter um ou mais objetos schema.
schema "public" {
comment = "Um comentário de esquema"
}
schema "private" {}
5.3 Objeto table
O objeto table é usado para descrever uma tabela em um banco de dados SQL, incluindo colunas, índices, restrições e várias propriedades adicionais suportadas por diferentes drivers de banco de dados.
table "users" {
schema = schema.public
column "id" {
type = int
}
column "name" {
type = varchar(255)
}
column "manager_id" {
type = int
}
primary_key {
columns = [
column.id
]
}
index "idx_name" {
columns = [
column.name
]
unique = true
}
foreign_key "manager_fk" {
columns = [column.manager_id]
ref_columns = [table.users.column.id]
on_delete = CASCADE
on_update = NO_ACTION
}
}
5.4 Objeto column
O column é um sub-recurso de table usado para definir as colunas na tabela.
column "name" {
type = text
null = false
}
column "age" {
type = integer
default = 42
}
column "active" {
type = tinyint(1)
default = true
}
5.5 Objeto primary_key
O primary_key é um sub-recurso da tabela que define a chave primária da tabela.
primary_key {
columns = [coluna.id]
}
5.6 Objeto foreign_key
O foreign_key é um sub-recurso da tabela que define colunas que fazem referência a colunas em outras tabelas.
tabela "pedidos" {
esquema = esquema.mercado
// ...
coluna "id_dono" {
tipo = inteiro
}
foreign_key "id_dono" {
colunas = [coluna.id_dono]
ref_colunas = [tabela.usuarios.coluna.id]
on_update = NO_ACTION
on_delete = NO_ACTION
}
}
5.7 Objeto index
O objeto index representa um índice na tabela.
index "idx_nome" {
colunas = [
coluna.nome
]
unico = true
}