Instalando Extensões

Instale extensões do VillageSQL para adicionar tipos personalizados, funções e capabilities ao seu banco de dados.

Sintaxe do Comando

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:

ERROR 3219 (HY000): Version mismatch in '<file>': filename says 'X' but manifest says 'Y'

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.

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:

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 '<name>' found in '<dir>'; specify a version with INSTALL EXTENSION <name> 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:

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

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

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:

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:

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:

-- Connect to VillageSQL
mysql -u root -p

-- Install the extension
INSTALL EXTENSION vsql_complex;

Verifique a Instalação

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

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

1. Copie o Arquivo .veb

Localize o diretório de extensões do seu servidor e copie o arquivo .veb para ele:

-- Find the extension directory
SHOW VARIABLES LIKE 'veb_dir';

cp /path/to/my_extension.veb /path/to/veb_dir/

2. Instale a Extensão

INSTALL EXTENSION my_extension;

Para fixar a versão esperada, útil em CI ou implantações com scripts, inclua a cláusula VERSION:

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 '<file>' mostrado anteriormente, que ocorre quando o próprio arquivo versionado existe.

3. Verifique a Instalação

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.
`Cannot install extension 'name': manifest version is 'X' but VERSION 'Y' was specified`	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 '<dir>'; 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.

Próximos Passos

Gerenciando Extensões

Monitore e solucione problemas de extensões instaladas

Extensões Disponíveis

Navegue pelas extensões que você pode instalar

Criando Extensões em C++

Compile suas próprias extensões

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

Sintaxe do Comando

Selecionando uma Versão

Convenções de Nomenclatura de Extensões

Privilégio Necessário

Pré-requisitos

Instalando Extensões Internas

Verifique a Instalação

Teste a Funcionalidade

Instalando Extensões Externas

1. Copie o Arquivo .veb

2. Instale a Extensão

3. Verifique a Instalação

Solução de Problemas

Próximos Passos

Gerenciando Extensões

Extensões Disponíveis

Criando Extensões em C++

​Sintaxe do Comando

​Selecionando uma Versão

​Convenções de Nomenclatura de Extensões

​Privilégio Necessário

​Pré-requisitos

​Instalando Extensões Internas

​Verifique a Instalação

​Teste a Funcionalidade

​Instalando Extensões Externas

​1. Copie o Arquivo .veb

​2. Instale a Extensão

​3. Verifique a Instalação

​Solução de Problemas

​Próximos Passos

Gerenciando Extensões

Extensões Disponíveis

Criando Extensões em C++

Sintaxe do Comando

Selecionando uma Versão

Convenções de Nomenclatura de Extensões

Privilégio Necessário

Pré-requisitos

Instalando Extensões Internas

Verifique a Instalação

Teste a Funcionalidade

Instalando Extensões Externas

1. Copie o Arquivo .veb

2. Instale a Extensão

3. Verifique a Instalação

Solução de Problemas

Próximos Passos