Instalando Extensões - VillageSQL Server for MySQL - Documentation

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

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 |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
+------------------+-------------------+

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

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

Extensões Disponíveis

Desinstalando Extensões

⌘I