Banco de Dados no Módulo

Conexão de Banco de Dados Personalizada (Obrigatória)

Para criar projetos na IDE, você deve configurar uma conexão de banco de dados personalizada. Isso garante isolamento total dos seus dados de desenvolvimento.

Por que é obrigatório?

Arquivo connection.php

Quando você cria um módulo na IDE, o arquivo Database/connection.php é gerado automaticamente com o valor 'auto':

<?php
// Gerado automaticamente pela IDE
// Sempre retorna 'auto' para usar sua conexão personalizada
return 'auto';

Migrations

Migrations criam e removem tabelas. Devem ter funções up e down e verificar o driver do banco:

<?php

use PDO;

return [
    'up' => function (PDO $pdo): void {
        $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
        if ($driver === 'pgsql') {
            $pdo->exec("CREATE TABLE IF NOT EXISTS produtos (
                id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
                nome VARCHAR(255) NOT NULL,
                preco DECIMAL(10,2) NOT NULL DEFAULT 0,
                criado_em TIMESTAMPTZ NOT NULL DEFAULT NOW()
            )");
        } else {
            $pdo->exec("CREATE TABLE IF NOT EXISTS produtos (
                id CHAR(36) PRIMARY KEY,
                nome VARCHAR(255) NOT NULL,
                preco DECIMAL(10,2) NOT NULL DEFAULT 0,
                criado_em DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4");
        }
    },
    'down' => function (PDO $pdo): void {
        $pdo->exec("DROP TABLE IF EXISTS produtos");
    },
];

Seeders

Seeders inserem dados iniciais. Devem ser executados manualmente após as migrations:

<?php

use PDO;

return function (PDO $pdo): void {
    $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
    $id = $driver === 'pgsql'
        ? $pdo->query('SELECT gen_random_uuid()')->fetchColumn()
        : bin2hex(random_bytes(16));

    $pdo->prepare("INSERT INTO produtos (id, nome, preco) VALUES (?, ?, ?)")
        ->execute([$id, 'Produto Exemplo', 99.90]);
};

Injeção de PDO no Repository

O container injeta o PDO automaticamente via constructor injection:

final class ProdutoRepository
{
    // PDO é injetado automaticamente pelo container
    public function __construct(private readonly PDO $pdo) {}

    public function findAll(): array
    {
        return $this->pdo
            ->query("SELECT * FROM produtos ORDER BY criado_em DESC")
            ->fetchAll(PDO::FETCH_ASSOC);
    }

    public function findById(string $id): ?array
    {
        // SEMPRE use prepared statements para evitar SQL injection
        $stmt = $this->pdo->prepare("SELECT * FROM produtos WHERE id = ?");
        $stmt->execute([$id]);
        $result = $stmt->fetch(PDO::FETCH_ASSOC);
        return $result ?: null;
    }

    public function create(array $data): array
    {
        $id = bin2hex(random_bytes(16));
        $stmt = $this->pdo->prepare(
            "INSERT INTO produtos (id, nome, preco) VALUES (?, ?, ?)"
        );
        $stmt->execute([$id, $data['nome'], $data['preco']]);
        return $this->findById($id) ?? ['id' => $id];
    }
}

Transações

Use transações para operações que precisam ser atômicas (tudo ou nada):

public function transferir(string $deId, string $paraId, float $valor): void
{
    try {
        $this->pdo->beginTransaction();

        // Debita da conta origem
        $stmt = $this->pdo->prepare("UPDATE contas SET saldo = saldo - ? WHERE id = ?");
        $stmt->execute([$valor, $deId]);

        // Credita na conta destino
        $stmt = $this->pdo->prepare("UPDATE contas SET saldo = saldo + ? WHERE id = ?");
        $stmt->execute([$valor, $paraId]);

        $this->pdo->commit();
    } catch (\Throwable $e) {
        $this->pdo->rollBack();
        throw $e;
    }
}

Executando Migrations Manualmente

Após ativar um módulo, você precisa executar as migrations manualmente:

Via Terminal da IDE

# Executar migrations de um módulo específico
php vupi migrate --modules=NomeDoModulo

# Executar migrations de todos os módulos
php vupi migrate --modules

# Executar seeders após migrations
php vupi seed --modules=NomeDoModulo

Via Interface da IDE

Na página do projeto, clique em:

• "Executar Migrations" — Cria as tabelas no banco de dados
• "Executar Seeders" — Insere dados iniciais

Como Configurar sua Conexão

Existem duas formas de configurar a conexão de banco de dados para seus módulos:

Opção 1: Usando Conexão da Plataforma

Opção 2: Configurando Conexão Própria

Exemplo: PostgreSQL no Aiven

Nome da conexão: Aiven PostgreSQL
Driver: PostgreSQL
Nome do banco: defaultdb
Host: pg-xxx-yyy.aivencloud.com
Porta: 12345
Usuário: avnadmin
Senha: sua_senha_aiven
Modo SSL: Require
Certificado CA: (cole o conteúdo do ca.pem fornecido pelo Aiven)

Comportamento do sistema

Todos os seus módulos criados na IDE usam automaticamente sua conexão personalizada:

Gerenciamento

No card de banco de dados, você pode:

• Ver/Ocultar dados: Clique no ícone de olho para mostrar/ocultar host, porta e nome do banco
• Ver migrations pendentes: Número de migrations que ainda não foram executadas
• Ver tabelas: Lista de todas as tabelas criadas no banco personalizado
• Editar conexão: Modifique as configurações (senha é mantida se deixar vazio)
• Excluir conexão: Remove a configuração (seus módulos voltam a usar o banco core)

Segurança

• Criptografia: Senhas são criptografadas com AES-256-CBC antes de serem armazenadas
• SSL/TLS: Suporte completo a conexões seguras com verificação de certificado
• Isolamento: Cada usuário tem sua própria configuração de conexão

Tipos de Dados por Driver

Validação Prévia de Migrations

Antes de executar migrations, você pode validá-las para detectar problemas sem modificar o banco de dados:

{
  "valid": true,
  "migrations_found": 3,
  "issues": [],
  "message": "Todas as migrations são válidas."
}

O que é validado?

• Sintaxe PHP: Verifica se o código é válido
• Métodos obrigatórios: Confirma presença de up() e down()
• Idempotência: Detecta migrations que não verificam se tabelas já existem
• Compatibilidade de driver: Alerta sobre SQL específico de PostgreSQL/MySQL

Gerenciamento de Tabelas

Deletar Todas as Tabelas (Drop Tables)

Durante o desenvolvimento, você pode precisar resetar completamente o banco de dados. Use esta funcionalidade com extrema cautela:

{
  "dropped": ["produtos", "categorias", "pedidos"],
  "message": "3 tabelas deletadas com sucesso."
}

Quando usar Drop Tables?

• Resetar desenvolvimento: Começar do zero após mudanças estruturais grandes
• Limpar testes: Remover dados de teste antes de nova bateria de testes
• Corrigir migrations: Quando migrations falharam e deixaram o banco em estado inconsistente

Ativar/Desativar Módulo

Você pode ativar ou desativar seu módulo sem deletá-lo. Módulos desativados não respondem a requisições:

{
  "enabled": false
}

{
  "message": "Módulo desativado com sucesso.",
  "module_name": "MeuModulo",
  "enabled": false
}

Casos de Uso

Próximos Passos