> ## 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` e aborta se o manifesto nomear uma versão diferente: ```text theme={null} ERROR 3219 (HY000): Version mismatch in '': filename says 'X' but manifest says 'Y' ``` Quando não existe um arquivo versionado, ele abre `{name}.veb` em vez disso e aborta com: ```text theme={null} ERROR 3219 (HY000): Cannot install extension '': manifest version is 'X' but VERSION 'Y' was specified ``` 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). > [!NOTE] > > 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` quando ele existe, caso contrário `vsql_uuid.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. > [!WARNING] > > 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 # After you build the extension, its .veb file uses underscores # vsql_uuid.veb # Then install it from a mysql session, with underscores and no quotes: # INSTALL EXTENSION vsql_uuid; ``` ## Privilégio Necessário `INSTALL EXTENSION`, `UNINSTALL EXTENSION` e `ALTER EXTENSION` são protegidos pelo privilégio dinâmico `EXTENSION_ADMIN`. Essas instruções carregam código nativo de extensão no servidor em execução, portanto exigem um privilégio administrativo e não estão disponíveis para contas sem privilégios. `EXTENSION_ADMIN` é um privilégio dinâmico concedido no escopo global (`ON *.*`): ```sql theme={null} GRANT EXTENSION_ADMIN ON *.* TO user@host; ``` `SUPER` é aceito como alternativa para compatibilidade retroativa, então uma conta que já possui `SUPER` pode executar essas instruções sem uma concessão separada. Um diretório de dados criado por `--initialize` ou `--initialize-insecure` concede `EXTENSION_ADMIN` diretamente a `root@localhost`, portanto um servidor novo não precisa de concessão manual. Quando um diretório de dados existente é atualizado no lugar, toda conta de usuário que possui `SUPER` recebe `EXTENSION_ADMIN` — mas somente se nenhuma conta já o possuir, de modo que um servidor atualizado uma vez não é preenchido novamente em atualizações posteriores. As contas de sistema reservadas `mysql.*` são excluídas. Uma conta sem nenhum dos privilégios é rejeitada antes que qualquer trabalho de extensão comece: ```text theme={null} ERROR 1227 (42000): Access denied; you need (at least one of) the EXTENSION_ADMIN or SUPER privilege(s) for this operation ``` Revogue o privilégio da mesma forma: ```sql theme={null} REVOKE EXTENSION_ADMIN ON *.* FROM user@host; ``` Uma revogação tem efeito imediato, não na próxima conexão. O servidor verifica `EXTENSION_ADMIN`/`SUPER` contra as concessões atuais da conta em cada instrução DDL de extensão, portanto uma sessão existente não mantém o privilégio após uma revogação — sua próxima instrução falha com o mesmo `ERROR 1227 (42000)` mostrado acima. ## 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} 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 | PENDING_VERSION | PENDING_REQUESTED_AT | PENDING_LAST_ERROR | PENDING_LAST_ERROR_AT | +----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+ | vsql_complex | 0.0.1 | NULL | NULL | NULL | NULL | +----------------+-------------------+-----------------+----------------------+--------------------+-----------------------+ ``` ### 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 -- Clean up DROP TABLE test; DROP DATABASE test_db; -- deletes the database created above; do this only if test_db was created by this example ``` ## Instalando Extensões Externas Para extensões baixadas ou compiladas separadamente: > [!NOTE] > > Todo servidor tem um `veb_dir` padrão. Para usar um diretório diferente, consulte [Configurando o veb\_dir](https://villagesql.com/docs/pt-BR/extensions/managing.md#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): Cannot install extension 'my_extension': manifest version is '0.0.1' but VERSION '1.2.0' was specified ``` Este é o caminho do arquivo alternativo (nenhum `{name}-{version}.veb` existe) — um caminho de código diferente do erro `Version mismatch in ''` mostrado anteriormente, que ocorre quando o próprio arquivo versionado existe. Um `VERSION ''` vazio não é uma incompatibilidade — o servidor o trata como nenhuma restrição, então a instalação tem sucesso com qualquer versão que esteja disponível. Um script que interpola uma variável não definida na cláusula `VERSION` não vai falhar; ele vai simplesmente deixar de fixar a versão. ### 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 | | - | - | | `VEB file not found: .veb` | Verifique se o arquivo `.veb` está em `veb_dir`: `SHOW VARIABLES LIKE 'veb_dir'` | | `Cannot open VEB file '.veb': Failed to open ''` | Verifique as permissões do arquivo: `chmod 644 extension.veb` | | `Manifest name '' does not match VEB basename ''` | O nome no `manifest.json` 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. | | `Cannot install extension 'name': manifest version is 'X' but VERSION 'Y' was specified` | Não existe `{name}-{version}.veb`, então o servidor usou `{name}.veb`, cujo manifesto reporta uma versão diferente. Execute novamente com a versão do manifesto. | | `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](https://villagesql.com/docs/pt-BR/extensions/managing.md). ## Próximos Passos > [card] [Gerenciando Extensões](https://villagesql.com/docs/pt-BR/extensions/managing.md) > > Monitore e solucione problemas de extensões instaladas > [card] [Extensões Disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) > > Navegue pelas extensões que você pode instalar > [card] [Criando Extensões](https://villagesql.com/docs/pt-BR/extensions/build/create.md) > > Compile suas próprias extensões This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.