> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizando a partir do MySQL

> Guia passo a passo para atualizar do MySQL upstream para o VillageSQL.

> [card] [VillageSQL is a drop-in replacement for MySQL with extensions.](https://villagesql.com/docs/en/8.4/stable/install-server.md)
>
> All examples on this page work on VillageSQL. Install Now →

O VillageSQL Server é um substituto direto para o MySQL. Para uma instalação simples do MySQL 8.4 com uma única instância e sem plugins de terceiros, migrar para o VillageSQL é funcionalmente idêntico a uma atualização de versão menor (por exemplo, de 8.4.5 para 8.4.6), preservando os seus dados existentes. Qualquer coisa que dependa de plugins não padrão deve ser testada primeiro em uma cópia.

## Pré-requisitos

* **Binários do VillageSQL**: Garanta que você tenha os binários do VillageSQL prontos (compilados a partir do código-fonte ou baixados).
* **Versão do MySQL**: O VillageSQL é baseado no MySQL 8.4 LTS. Atualizar a partir do MySQL 8.4 é o caminho suportado.

> [!WARNING]
>
> **Sempre faça backup dos seus dados antes de realizar uma atualização.**
> Embora o processo tenha sido projetado para ser seguro, atualizações de banco de dados sempre envolvem um risco.

## Etapa 1: Faça Backup dos Seus Dados

Antes de tocar em qualquer arquivo de sistema ou serviço, crie um backup completo do seu banco de dados.

### Opção A: Backup Lógico (mysqldump)

Crie um dump SQL de todos os bancos de dados. Este é o método mais seguro e mais portátil.

```bash theme={null}
mysqldump -u root -p --all-databases --events --routines --triggers > full_backup.sql
```

### Opção B: Backup Físico (Diretório de Dados)

Se o seu conjunto de dados for grande, pare o servidor e copie o diretório de dados.

```bash theme={null}
# Stop the server first (see Step 2)
cp -r /var/lib/mysql /var/lib/mysql-backup
```

## Etapa 2: Pare o Servidor MySQL

Pare a instância do servidor MySQL em execução para liberar os bloqueios sobre os arquivos de dados.

**Usando Systemd (Linux):**

```bash theme={null}
sudo systemctl stop mysql
# OR
sudo systemctl stop mysqld
```

**Usando SysV Init:**

```bash theme={null}
sudo service mysql stop
```

**Instalação Manual:**

```bash theme={null}
mysqladmin -u root -p shutdown
```

## Etapa 3: Substitua os Binários

O núcleo da atualização consiste em trocar os arquivos executáveis (`mysqld`, `mysql`, etc.) das versões do MySQL upstream pelas versões do VillageSQL.

### Método A: Trocando os Diretórios de Instalação (Recomendado)

Se você instalou o MySQL via tarball (por exemplo, em `/usr/local/mysql`), o método mais limpo é instalar o VillageSQL ao lado dele e trocar o link simbólico.

1. **Extraia/Instale o VillageSQL** em um novo diretório, por exemplo, `/usr/local/villagesql-8.4`.
2. **Atualize o link simbólico**:
   ```bash theme={null}
   # Remove link to old MySQL
   sudo unlink /usr/local/mysql

   # Link to VillageSQL
   sudo ln -s /usr/local/villagesql-8.4 /usr/local/mysql
   ```
3. **Verifique as permissões**: Garanta que o usuário que executa o banco de dados (geralmente `mysql`) tenha permissão de execução sobre os novos binários.

### Método B: Sobrescrevendo os Binários

Se você compilou o VillageSQL a partir do código-fonte e quer sobrescrever a instalação do sistema (por exemplo, `/usr/bin` ou `/usr/local/bin`):

```bash theme={null}
# Assuming you are in the VillageSQL build directory
sudo make install
```

> [!NOTE]
>
> Se você instalou o MySQL por meio de um gerenciador de pacotes (`apt`, `yum`), sobrescrever os binários manualmente é arriscado, pois o gerenciador de pacotes pode sobrescrevê-los de volta durante as atualizações. Recomenda-se desinstalar o pacote `mysql-server` (mantendo os arquivos de dados!) ou usar `update-alternatives`, se disponível.

## Etapa 4: Verificação da Configuração

Garanta que o seu arquivo de configuração (geralmente `/etc/my.cnf` ou `/etc/mysql/my.cnf`) aponte para o seu diretório de dados existente.

```ini theme={null}
[mysqld]
datadir=/var/lib/mysql  # Should point to your EXISTING data
socket=/var/run/mysqld/mysqld.sock
```

O VillageSQL usa as opções de configuração padrão do MySQL, portanto o seu `my.cnf` existente deve funcionar sem modificações.

## Etapa 5: Inicie o VillageSQL

Inicie o servidor usando o seu gerenciador de serviços ou manualmente.

**Usando Systemd:**

```bash theme={null}
sudo systemctl start mysql
```

**Início Manual:**

```bash theme={null}
/usr/local/mysql/bin/mysqld_safe --user=mysql &
```

### Atualização Automática

Na inicialização, o VillageSQL detecta automaticamente se os arquivos de dados são de uma versão mais antiga e realiza as atualizações necessárias nas tabelas de sistema.

Verifique o log de erros (geralmente em `/var/log/mysql/error.log` ou dentro do seu `datadir`) para confirmar que a atualização foi concluída com sucesso. Procure por:
`[System] [MY-013381] [Server] Server upgrade from '...' to '...' completed.`

## Etapa 6: Verifique a Instalação

Conecte-se ao servidor e verifique se você está executando o VillageSQL.

```bash theme={null}
mysql -u root -p
```

Execute a seguinte consulta:

```sql theme={null}
SELECT @@version, @@version_comment;
```

Agora você pode verificar se os seus dados estão intactos e começar a usar os recursos exclusivos do VillageSQL, como `INSTALL EXTENSION`.

## Solução de Problemas

* **"Data Dictionary Upgrade Failed"**: Se o servidor se recusar a iniciar, você pode estar tentando fazer um downgrade (por exemplo, de 8.4 para 8.0) ou os arquivos de dados estão corrompidos. Verifique o log de erros.
* **Erros de Permissão**: Garanta que o usuário `mysql` do sistema operacional seja o dono do `datadir` e do novo diretório de instalação do VillageSQL.
  ```bash theme={null}
  sudo chown -R mysql:mysql /var/lib/mysql
  ```

## Veja também

* [Migrações de Esquema no MySQL](https://villagesql.com/docs/pt-BR/guides/schema-migrations.md) — executando alterações de DDL seguras após a atualização
* [Estratégias de Backup do MySQL](https://villagesql.com/docs/pt-BR/guides/backup-strategies.md) — faça backup antes de atualizar
* [MySQL no Docker](https://villagesql.com/docs/pt-BR/guides/mysql-on-docker.md) — executando o MySQL ou o VillageSQL em um contêiner como alternativa
* [Atualizando do MySQL 8.0 para o 8.4 Após o Fim do Suporte](https://villagesql.com/docs/pt-BR/guides/mysql-80-eol-upgrade.md) — chegando primeiro ao 8.4 se você ainda estiver no 8.0


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.