Curso de MariaDB / Criar um ambiente de estudos com Docker Compose

Docker Compose permite definir um contêiner MariaDB, sua porta de conexão e seu armazenamento persistente em um arquivo. Ele oferece um ambiente de estudos separado sem instalar um serviço de banco de dados no computador, mas remover o contêiner e remover seu volume de dados têm consequências diferentes.

Definir o ambiente e conferir os requisitos

Docker executa aplicações em contêineres, e Compose descreve sua configuração em YAML, um formato de texto estruturado. O exemplo inicia um banco e publica 127.0.0.1:3307 no computador. Uma porta diferente permite coexistir com um servidor que já use 3306. A prática de conexões locais e remotas ajuda a distinguir os caminhos, e a prática de backup explica o que preservar separadamente do volume.

Instale Docker Engine com o plugin Compose ou Docker Desktop conforme as instruções oficiais de instalação do Compose. No Windows, use contêineres Linux. Inicie o mecanismo Docker e confirme no terminal que os dois comandos funcionam antes de preparar o banco:

docker version
docker compose version

A configuração usa explicitamente a família de imagem mariadb:11.8. Essa tag pode passar a apontar para uma revisão de manutenção mais recente; se precisar de reprodução exata, registre uma tag de revisão ou um digest aprovado, identificador do conteúdo da imagem. Conferir a estrutura YAML e o SQL não substitui testar inicialização, saúde e persistência do volume no ambiente Docker.

Criar o projeto e os arquivos de senhas

  1. Crie uma pasta nova mariadb-appops e abra o terminal nela. Não execute estes comandos a partir de outro projeto Compose.
  2. Crie a subpasta secrets com os arquivos UTF-8 root-password.txt e app-password.txt. Guarde uma senha diferente em cada arquivo, sem deixá-los vazios nem acrescentar explicações.
  3. Salve a configuração completa da seção seguinte como compose.yaml. Crie também um arquivo .gitignore com as duas linhas abaixo e restrinja o acesso às senhas.
secrets/
.env

Os secrets do Compose disponibilizam arquivos aos serviços selecionados; não transformam os arquivos locais originais em um cofre criptografado. Proteja os arquivos e o acesso ao Docker. A documentação oficial de secrets do Compose explica as montagens e o requisito de contêineres Linux.

Entender a configuração completa do Compose

name: mariadb-appops
services:
  db:
    image: mariadb:11.8
    ports:
      - "127.0.0.1:3307:3306"
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/root_password
      MARIADB_DATABASE: appops_lab
      MARIADB_USER: app_user
      MARIADB_PASSWORD_FILE: /run/secrets/app_password
    secrets:
      - root_password
      - app_password
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 30s
secrets:
  root_password:
    file: ./secrets/root-password.txt
  app_password:
    file: ./secrets/app-password.txt
volumes:
  db_data:

O computador publica a porta 3307, enquanto MariaDB usa 3306 dentro do contêiner. Um cliente no computador conecta a 127.0.0.1:3307; outro serviço na mesma rede Compose usa db:3306. Publicar no endereço de loopback, que aponta para o próprio computador, limita esse ponto de acesso do exemplo ao ambiente local.

O volume nomeado db_data armazena o diretório de dados. As variáveis terminadas em _FILE indicam arquivos de senhas. A referência oficial de variáveis da imagem MariaDB explica a inicialização do banco, do usuário e das senhas quando o diretório de dados é novo. Editar o arquivo de senha não altera por si só uma conta já armazenada em um volume inicializado.

O script oficial healthcheck.sh verifica a conexão e a inicialização do InnoDB. Um contêiner em execução não demonstra sozinho que MariaDB esteja pronto para as consultas do exercício.

Iniciar o serviço e conferir uma linha armazenada

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=80 db

O primeiro comando valida a configuração com Compose. Confirme que o serviço alcance o estado healthy e examine o registro de inicialização se isso não acontecer. Corrija caminhos de secrets inexistentes ou uma porta ocupada antes de tentar novamente. Antes de compartilhar registros, confira se contêm informações sensíveis.

docker compose exec db mariadb --default-character-set=utf8mb4 -u app_user -p appops_lab

Informe a senha de app-password.txt quando solicitada. Dentro do cliente SQL, execute o bloco completo abaixo; ele retorna uma linha. A criação é para a primeira execução: se a tabela existir, examine os exercícios anteriores em vez de repetir a preparação sem verificar.

USE appops_lab;
CREATE TABLE docker_notes (
  note_id INT NOT NULL PRIMARY KEY,
  note_text VARCHAR(80) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
INSERT INTO docker_notes VALUES (1, 'volume survives container replacement');
SELECT note_id, note_text FROM docker_notes;

O texto em inglês armazenado na linha significa “o volume sobrevive à substituição do contêiner” e foi mantido como valor literal do exercício. Sua presença depois de recriar o contêiner será a verificação de persistência.

Se o computador tiver um cliente mariadb instalado, o comando abaixo chega ao mesmo servidor pela porta publicada. Usar 3306 aqui pode direcionar a conexão a outro banco local:

mariadb --protocol=tcp --host=127.0.0.1 --port=3307 --default-character-set=utf8mb4 -u app_user -p appops_lab

Substituir o contêiner preservando o volume

docker compose down
docker compose up -d

Nesta configuração, down sem opções remove os contêineres e a rede do projeto e mantém o volume de dados nomeado. Quando o serviço novo estiver healthy, conecte novamente e execute SELECT * FROM docker_notes;. A linha inserida deve continuar presente: lê-la verifica a persistência em vez de presumir seu funcionamento.

docker compose down --volumes também remove volumes e pode descartar o banco. Não é um comando comum de reinicialização. Use somente depois de confirmar que os dados de estudo do projeto são descartáveis. Um volume não é um backup; siga o procedimento de cópia do banco para dados que precisa conservar. A referência oficial de Compose down detalha o que é removido.

Diagnosticar antes de reinicializar os dados

Sintoma O que conferir
Não é possível contatar o mecanismo Docker Docker Desktop ou Engine em execução e contexto Docker selecionado
Porta publicada ocupada Porta 3307 do computador; se mudar, ajuste também a porta do cliente
Access denied Conta e senha usadas na inicialização e existência anterior do volume
Contêiner em execução sem SQL disponível Saúde, registro de inicialização e diferença entre db na rede e 127.0.0.1 no computador
Dados inesperados após recriar Projeto mariadb-appops, pasta de trabalho, porta e volume montado

Não remova o volume como primeira medida de diagnóstico. Identifique o servidor e o diretório de dados utilizados e decida se precisa corrigir a configuração ou realizar deliberadamente uma inicialização nova.