Início Rápido

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:

docker run -d --name vsql -e MYSQL_ALLOW_EMPTY_PASSWORD=yes -p 3306:3306 villagesql/server:mysql-9.7_0.0.6-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

A tag da imagem indica a base de código, a versão do VillageSQL e a arquitetura, e o comando acima lê a arquitetura do uname. No PowerShell, escreva o sufixo você mesmo: -amd64 em Intel e AMD, -arm64 em ARM.

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.

curl -fsSL https://install.villagesql.com | bash

O script faz três perguntas: qual base de código instalar, como instalar e qual versão. Escolha MySQL 9.7 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:

curl -fsSL https://install.villagesql.com | \
  VSQL_CODEBASE=mysql-9.7 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 aceita 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 Compilar a Partir do Código-Fonte para compilar a partir do código mais recente.

O que o script de shell configura

O script de shell (Opção B) instala tudo em ~/.villagesql/ e inicia o servidor na porta 3306. 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 estiver no seu PATH, 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 dentro do contêiner.

Passo 2: Conecte-se ao Servidor

Conecte-se usando qualquer cliente MySQL padrão. 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, então conecte-se por TCP.

mysql -h 127.0.0.1 -P 3306 -u root -p

Docker (Opção A): o contêiner inicia com uma senha de root vazia — pressione Enter no prompt de senha.
Script de shell (Opção B): sua senha de root gerada é salva em ~/.villagesql/credentials.txt.

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.
vsql_complex e vsql_simple, extensões de referência usadas em outras partes desta documentação (veja Exemplos de Extensões em C++) 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 antes de continuar, ou siga em frente usando a vsql_complex no lugar dela — veja Instalando Extensões. Instale a extensão vsql_uuid para adicionar geração nativa de UUID e um tipo de coluna UUID:

INSTALL EXTENSION vsql_uuid;

Verifique a instalação:

SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

Você deverá ver vsql_uuid listada. Para mais detalhes, consulte Instalando Extensões.

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

-- 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
INSERT INTO events VALUES
    (UUID_V7(), 'signup'),
    (UUID_V7(), 'login'),
    (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:

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.

Próximos Passos

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

Gerenciando Extensões

Aprenda a instalar e gerenciar outras extensões.

Criando Extensões em C++

Aprenda a criar suas próprias extensões para o VillageSQL.

Guia de Atualização

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: configure seu servidor para usar uma porta diferente
Permissões: certifique-se de que os arquivos podem ser lidos/executados

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

Passo 1: Instale o VillageSQL

Opção A: Docker (Recomendado)

Opção B: Script de Shell

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

O que o script de shell configura

Passo 2: Conecte-se ao Servidor

Passo 3: Instale Sua Primeira Extensão

Passo 4: Use Tipos de Dados Estendidos

Parando e Reiniciando o Servidor

Próximos Passos

Gerenciando Extensões

Criando Extensões em C++

Guia de Atualização

Solução de Problemas

O Servidor Não Inicia

​Passo 1: Instale o VillageSQL

​Opção A: Docker (Recomendado)

​Opção B: Script de Shell

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

​O que o script de shell configura

​Passo 2: Conecte-se ao Servidor

​Passo 3: Instale Sua Primeira Extensão

​Passo 4: Use Tipos de Dados Estendidos

​Parando e Reiniciando o Servidor

​Próximos Passos

Gerenciando Extensões

Criando Extensões em C++

Guia de Atualização

​Solução de Problemas

​O Servidor Não Inicia

Passo 1: Instale o VillageSQL

Opção A: Docker (Recomendado)

Opção B: Script de Shell

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

O que o script de shell configura

Passo 2: Conecte-se ao Servidor

Passo 3: Instale Sua Primeira Extensão

Passo 4: Use Tipos de Dados Estendidos

Parando e Reiniciando o Servidor

Próximos Passos

Solução de Problemas

O Servidor Não Inicia