> ## 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.

# Instalar

> Coloque o VillageSQL Server em funcionamento.

Coloque uma instância do VillageSQL Server em execução, conecte-se a ela e experimente o sistema de extensões.

## Passo 1: Instale o VillageSQL

### Opção A: Docker (Recomendado)

Execute o VillageSQL em um contêiner, sem nenhuma instalação no host:

```bash theme={null}
docker run -d --name vsql -e MYSQL_ROOT_PASSWORD=<your-password> -p 3306:3306 villagesql/server:latest
```

### Opção B: Script de Shell

Instale o VillageSQL diretamente na sua máquina usando o script de instalação oficial. Ele baixa e configura o binário do servidor para a sua plataforma.

```bash theme={null}
curl -fsSL https://install.villagesql.com | bash
```

O script pergunta qual base de código instalar e como instalá-la. Uma compilação a partir do código-fonte também pergunta qual versão. Escolha **MySQL 8.4** na primeira pergunta para obter o servidor que estas páginas descrevem.

Quando não há terminal para responder às perguntas — um job de CI, um Dockerfile, um agente de IA — passe as respostas em variáveis de ambiente. Defina-as no lado `bash` do pipe:

```bash theme={null}
curl -fsSL https://install.villagesql.com | \
  VSQL_CODEBASE=mysql-8.4 INSTALL_METHOD=prebuilt bash
```

`VSQL_CODEBASE` aceita `mysql-8.4`, `percona-8.4` ou `mysql-9.7`. `INSTALL_METHOD` aceita `docker`, `prebuilt` ou `source`. Uma compilação a partir do código-fonte também precisa de `VSQL_VERSION=stable|nightly|latest`; instalações via Docker e binário pré-compilado usam sempre a versão estável.

Para inspecionar o script antes de executá-lo: `curl -fsSL https://install.villagesql.com | less`

### Opção C: Compilar a Partir do Código-Fonte

Para desenvolvimento ou compilações personalizadas, siga o guia [Compilar a Partir do Código-Fonte](https://villagesql.com/docs/pt-BR/8.4/stable/source.md) para compilar a partir do código mais recente.

O VillageSQL também é compilado sobre o Percona Server como alternativa ao MySQL upstream — consulte a página [Primeiros Passos com o Percona Server](https://villagesql.com/docs/pt-BR/8.4/stable/percona.md) para saber o que isso envolve.

### O que o script de shell configura

O script de shell (Opção B) instala o servidor em `~/.villagesql/` e o inicia na porta 3306; se você escolher o Docker na pergunta do script sobre o método de instalação, ele inicia um contêiner chamado `vsql` em vez disso. Os locais que importam:

| Caminho | O que é |
| - | - |
| `~/.villagesql/credentials.txt` | Sua senha de root gerada, além dos comandos prontos para executar de início, parada e conexão (legível somente por você) |
| `~/.villagesql/data/` | Diretório de dados do banco de dados |
| `~/.villagesql/mysql.sock` | Socket do servidor |
| `~/.villagesql/mysql.log` | Log de erros do servidor |

Se `~/.local/bin` existir e for gravável, o script também adiciona atalhos: `villagesql` (cliente), `villagesql-server` (servidor) e `villagesql-admin` (ferramenta de administração).

O Docker (Opção A) e as compilações manuais a partir do código-fonte não criam `~/.villagesql/` — o Docker mantém seus dados em um volume do Docker montado em `/var/lib/mysql` no contêiner.

## Passo 2: Conecte-se ao Servidor

**Docker (Opção A).** Conecte-se com qualquer cliente MySQL e digite a senha de root que você definiu com `MYSQL_ROOT_PASSWORD`. Use `-h 127.0.0.1` em vez do `localhost` padrão: `localhost` faz o cliente procurar um socket Unix, que não é acessível quando o servidor é executado no Docker.

```bash theme={null}
mysql -h 127.0.0.1 -P 3306 -u root -p
```

Se você não tem um cliente MySQL na sua máquina, use o que está dentro do contêiner:

```bash theme={null}
docker exec -it vsql mysql -u root -p
```

**Script de shell (Opção B).** O script instala o seu próprio cliente MySQL, mas não o coloca no seu `PATH`. Execute o comando `Connect` que o script salvou em `~/.villagesql/credentials.txt`. A senha de root está no mesmo arquivo. Para uma instalação com binário pré-compilado, o comando se parece com este:

```bash theme={null}
~/.villagesql/prebuilt/bin/mysql -u root -p --socket="$HOME/.villagesql/mysql.sock"
```

Para uma compilação a partir do código-fonte, o cliente está em `~/.villagesql/build/bin/`. Se você escolheu o Docker na pergunta do script sobre o método de instalação, o script exibiu a senha na tela e não salvou nenhum `credentials.txt`; conecte-se como na Opção A.

## Passo 3: Instale Sua Primeira Extensão

`INSTALL EXTENSION <name>` procura por `<name>.veb` no diretório VEB do servidor — execute `SHOW VARIABLES LIKE 'veb_dir';` para ver onde ele fica.

Se você instalou com o Docker (Opção A) ou com o script shell (Opção B), um conjunto de arquivos `.veb` já está em `veb_dir` — sem necessidade de baixar ou copiar nada. Dois tipos de extensão vêm nesse diretório:

* Extensões, como a `vsql_uuid` (tipos e geradores de UUID) e as outras extensões da [lista de extensões incluídas](https://github.com/villagesql/villagesql-server/blob/main/villagesql/dev_server/bundled_extensions.txt).
* `vsql_complex` e `vsql_simple`, extensões de referência usadas em outras partes desta documentação (veja [Exemplos de Extensões em C++](https://villagesql.com/docs/pt-BR/sdk/cpp/examples.md)) para mostrar como o framework de extensões funciona.

Se você compilou o VillageSQL a partir do código-fonte (Opção C), a `vsql_complex` e a `vsql_simple` também já estão em `veb_dir` — o `make install` as compila incondicionalmente. Já a `vsql_uuid` e as outras extensões não: elas vivem em repositórios separados e precisam ser compiladas e instaladas por conta própria. Se você usou a Opção C, clone e compile a [vsql-uuid](https://github.com/villagesql/vsql-uuid) antes de continuar, ou siga em frente usando a `vsql_complex` no lugar dela — veja [Instalando Extensões](https://villagesql.com/docs/pt-BR/extensions/install.md).

Instale a extensão `vsql_uuid` para adicionar geração nativa de UUID e um tipo de coluna `UUID`:

```sql theme={null}
INSTALL EXTENSION vsql_uuid;
```

Verifique a instalação:

```sql theme={null}
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;
```

Você deverá ver `vsql_uuid` listada.

Para mais detalhes, consulte [Instalando Extensões](https://villagesql.com/docs/pt-BR/extensions/install.md).

## Passo 4: Use Tipos de Dados Estendidos

Agora que a extensão está ativa, você pode usar o tipo `UUID` em suas tabelas assim como os tipos nativos, com geradores para cada versão padrão — `UUID_V1()`, `UUID_V1MC()`, `UUID_V3()`, `UUID_V4()`, `UUID_V5()`, `UUID_V6()` e `UUID_V7()` (não existe `UUID_V2()`) — além de funções para inspecionar os valores armazenados. O exemplo abaixo usa a v7, cujos valores carregam um timestamp embutido e são ordenados por hora de criação quando gerados com mais de um milissegundo de diferença; valores gerados dentro do mesmo milissegundo são ordenados por bits aleatórios, e não pela ordem das chamadas: uma chave amigável a sequências sem geração manual de `BINARY(16)`.

```sql theme={null}
-- Create a database and use it
CREATE DATABASE demo;
USE demo;

-- Create a table with a UUID primary key
CREATE TABLE events (
    id UUID PRIMARY KEY,
    label VARCHAR(50)
);

-- Insert rows with generated v7 UUIDs. Each UUID_V7() embeds a millisecond
-- timestamp, so rows inserted in the same statement can land in the same
-- millisecond and tie-break on their random bits instead of insertion
-- order — insert separately, with a gap, to see the ordering clearly.
INSERT INTO events VALUES (UUID_V7(), 'signup');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (UUID_V7(), 'login');
SELECT SLEEP(0.01);
INSERT INTO events VALUES (UUID_V7(), 'purchase');

-- v7 keys sort in creation order
SELECT id, label FROM events ORDER BY id;

-- Introspect the stored UUIDs
SELECT
    label,
    UUID_VERSION(id) AS version,
    UUID_TIMESTAMP(id) AS created_at
FROM events
ORDER BY id;
```

Para desinstalar uma extensão, primeiro remova tudo o que usa seus tipos:

```sql theme={null}
DROP DATABASE demo;
UNINSTALL EXTENSION vsql_uuid;
```

## Parando e Reiniciando o Servidor

Você para e inicia o servidor controlando seu contêiner (Docker) ou seu processo em segundo plano (instalação por shell) — o banco de dados sobe e desce junto com ele.

* **Docker (Opção A):** `docker stop vsql` para o servidor; `docker start vsql` o traz de volta.
* **Script de shell (Opção B):** os comandos de início, parada e conexão da sua instalação — com o diretório de dados, o socket e a porta já preenchidos — estão em `~/.villagesql/credentials.txt`. Se você escolheu o Docker na pergunta do script sobre o método de instalação, use os comandos do Docker acima.

## Próximos Passos

Agora que você tem o VillageSQL em execução e verificou o sistema de extensões, explore mais:

> [card] [Gerenciando Extensões](https://villagesql.com/docs/pt-BR/extensions/managing.md)
>
> Aprenda a instalar e gerenciar outras extensões.

> [card] [Criar uma Extensão](https://villagesql.com/docs/pt-BR/extensions/build/create.md)
>
> Aprenda a criar suas próprias extensões para o VillageSQL.

> [card] [Guia de Atualização](https://villagesql.com/docs/en/guides/upgrade.md)
>
> Atualizando de uma versão anterior ou migrando do MySQL.

## Solução de Problemas

### O Servidor Não Inicia

Problemas comuns:

* A porta 3306 já está em uso: pare o outro servidor ou execute o instalador com `PORT=<port>` definido. Com o Docker, altere o lado do host de `-p`.
* Permissões: certifique-se de que os arquivos podem ser lidos/executados


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