> ## 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. # Instalando Extensões > Como adicionar novas capabilities ao VillageSQL usando extensões. Instale extensões do VillageSQL para adicionar tipos personalizados, funções e capabilities ao seu banco de dados. ## Sintaxe do Comando ```sql theme={null} INSTALL EXTENSION extension_name [VERSION 'version']; ``` Quando `VERSION` é fornecido, o servidor abre `{name}-{version}.veb`, compara a versão com o manifesto e aborta se elas diferirem. Omita a cláusula para instalar `{name}.veb`, ou, se apenas VEBs versionados estiverem presentes, o único `{name}-{version}.veb`. Consulte [Selecionando uma Versão](#selecting-a-version). As extensões são distribuídas como arquivos `.veb` (VillageSQL Extension Bundle) que contêm bibliotecas compiladas e metadados.

Selecionando uma Versão

Os arquivos VEB em `veb_dir` podem ser nomeados como `{name}.veb` (sem versão) ou `{name}-{version}.veb` (versionado). Para instalar um VEB versionado específico, adicione uma cláusula `VERSION`: ```sql theme={null} INSTALL EXTENSION vsql_uuid VERSION '0.2.0'; ``` Com `VERSION`, o servidor abre `vsql_uuid-0.2.0.veb` e verifica se a versão em seu `manifest.json` corresponde a `0.2.0`. Sem `VERSION`, o servidor resolve o arquivo da seguinte forma: * Se `{name}.veb` existir, instale-o; a versão é lida de seu `manifest.json`. * Caso contrário, se existir exatamente um `{name}-{version}.veb`, instale-o; a versão no nome do arquivo é verificada contra seu `manifest.json`. * Caso contrário, a instalação falha e você deve especificar uma versão. Se vários VEBs versionados estiverem presentes e nenhum VEB sem versão existir, `INSTALL EXTENSION` falha com `Multiple versions of extension '' found in ''; specify a version with INSTALL EXTENSION VERSION 'x.y.z'`. Execute novamente com uma cláusula `VERSION` explícita.

Convenções de Nomenclatura de Extensões

O VillageSQL usa diferentes convenções de nomenclatura em diferentes contextos: * **Comandos SQL:** Use sublinhados: `INSTALL EXTENSION vsql_uuid` * **Nomes de repositório:** Use hifens: `github.com/villagesql/vsql-uuid` * **Nomes de arquivo:** Use sublinhados: `vsql_uuid.veb` * **manifest.json:** Use sublinhados para corresponder ao SQL: `"name": "vsql_uuid"` **Exemplo:** ```bash theme={null} # Clone from GitHub repo (hyphens in URL) git clone https://github.com/villagesql/vsql-uuid # But .veb file uses underscores ls vsql_uuid.veb # Install with underscores (no quotes) INSTALL EXTENSION vsql_uuid; ``` ## Pré-requisitos * Instância do VillageSQL Server em execução * Acesso administrativo (root ou equivalente) ## Instalando Extensões Internas As extensões internas incluídas com o VillageSQL já estão no veb\_dir. Basta habilitá-las: ```sql theme={null} -- Connect to VillageSQL mysql -u root -p -- Install the extension INSTALL EXTENSION vsql_complex; ``` ### Verifique a Instalação ```sql theme={null} -- List installed extensions SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS; ``` **Saída:** ``` +------------------+-------------------+ | EXTENSION_NAME | EXTENSION_VERSION | +------------------+-------------------+ | vsql_complex | 0.0.1 | +------------------+-------------------+ ``` ### Teste a Funcionalidade ```sql theme={null} -- Create a database first CREATE DATABASE test_db; USE test_db; -- Test extension functions CREATE TABLE test (id INT, value COMPLEX); INSERT INTO test VALUES (1, '(3,4)'); SELECT complex_abs(value) FROM test; -- Returns 5.0 -- Clean up DROP TABLE test; DROP DATABASE test_db; ``` ## Instalando Extensões Externas Para extensões baixadas ou compiladas separadamente: Seu servidor deve ter `veb_dir` configurado antes de você poder instalar extensões externas. Consulte [Configurando o veb\_dir](/docs/pt-BR/mysql-8.4/0.0.5/managing#configuring-veb_dir). ### 1. Copie o Arquivo .veb Localize o diretório de extensões do seu servidor e copie o arquivo `.veb` para ele: ```sql theme={null} -- Find the extension directory SHOW VARIABLES LIKE 'veb_dir'; ``` ```bash theme={null} cp /path/to/my_extension.veb /path/to/veb_dir/ ``` ### 2. Instale a Extensão ```sql theme={null} INSTALL EXTENSION my_extension; ``` Para fixar a versão esperada, útil em CI ou implantações com scripts, inclua a cláusula `VERSION`: ```sql theme={null} INSTALL EXTENSION my_extension VERSION '1.2.0'; ``` Se o manifesto reportar uma versão diferente, a instalação falha e nada é registrado: ``` ERROR 3219 (HY000): Version mismatch in 'my_extension-1.2.0.veb': filename says '1.2.0' but manifest says '0.0.1' ``` ### 3. Verifique a Instalação ```sql theme={null} SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS WHERE EXTENSION_NAME = 'my_extension'; ``` ## Solução de Problemas | Problema | Solução | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Extension not found` | Verifique se o arquivo `.veb` está em `veb_dir`: `SHOW VARIABLES LIKE 'veb_dir'` | | `Permission denied` | Verifique as permissões do arquivo: `chmod 644 extension.veb` | | `extension name mismatch` | O nome interno da extensão não corresponde ao nome do arquivo `.veb`. Recompile a extensão. | | `vef_register not found` | O arquivo `.veb` não exporta um ponto de entrada VEF válido. Recompile com o SDK correto. | | `vef_register returned an error: ...` | O registro da extensão falhou. Leia a mensagem anexada para obter detalhes. | | `Version mismatch in 'name-Y.veb': filename says 'Y' but manifest says 'X'` | A cláusula `VERSION` seleciona `{name}-{version}.veb`, mas o manifesto interno reporta uma versão diferente. Execute novamente com a versão do manifesto ou corrija o nome do arquivo. | | `Multiple versions of extension 'name' found in ''; specify a version with INSTALL EXTENSION name VERSION 'x.y.z'` | Existem vários arquivos `{name}-{version}.veb` sem um `{name}.veb` sem versão. Execute novamente com uma cláusula `VERSION` explícita. | Para mais soluções de problemas, consulte [Gerenciando Extensões](/docs/pt-BR/mysql-8.4/0.0.5/managing). ## Próximos Passos Monitore e solucione problemas de extensões instaladas Navegue pelas extensões que você pode instalar Compile suas próprias extensões