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

# Referência do Sistema

> Views de sistema e variáveis do VillageSQL para consultar metadados de extensões e o estado do servidor

Consulte metadados de extensões e o estado do servidor usando as interfaces SQL padrão abaixo.

***

## Views de Sistema

### INFORMATION\_SCHEMA.EXTENSIONS

Lista todas as extensões do VillageSQL atualmente instaladas.

<Note>
  `INSTALL EXTENSION` e `UNINSTALL EXTENSION` são extensões SQL do VillageSQL.
  Elas não fazem parte da sintaxe padrão do MySQL 8.4.
</Note>

**Colunas conhecidas:**

| Coluna                  | Tipo    | Descrição                                                                  |
| ----------------------- | ------- | -------------------------------------------------------------------------- |
| `EXTENSION_NAME`        | varchar | Nome da extensão instalada                                                 |
| `EXTENSION_VERSION`     | varchar | String de versão informada pela extensão                                   |
| `PENDING_VERSION`       | text    | Versão para a qual a extensão mudará na próxima reinicialização, ou `NULL` |
| `PENDING_REQUESTED_AT`  | text    | Quando uma mudança de versão pendente foi solicitada, ou `NULL`            |
| `PENDING_LAST_ERROR`    | text    | Mensagem de uma mudança de versão que falhou, ou `NULL`                    |
| `PENDING_LAST_ERROR_AT` | text    | Quando essa falha foi registrada, ou `NULL`                                |

**Exemplo:**

```sql theme={null}
-- Install an extension (VillageSQL-specific syntax)
INSTALL EXTENSION vsql_complex;

-- List all installed extensions
SELECT * FROM INFORMATION_SCHEMA.EXTENSIONS;

-- Check a specific extension's version
SELECT EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_complex';
```

**Saída ilustrativa** (as strings de versão reais dependem das extensões instaladas):

```
+------------------+-------------------+
| EXTENSION_NAME   | EXTENSION_VERSION |
+------------------+-------------------+
| vsql_complex     | 0.0.1             |
| vsql_uuid        | 0.2.1             |
+------------------+-------------------+
```

Os valores de `EXTENSION_NAME` são em minúsculas, correspondendo ao nome passado para `make_extension()`.

A view reflete o estado atual da instalação.

As quatro colunas `PENDING_*` rastreiam uma mudança de versão agendada com `ALTER EXTENSION ... AT RESTART`.
Consulte [Gerenciando Extensões](/docs/pt-BR/mysql-8.4/0.0.5/managing) para conhecer o fluxo de trabalho.

***

### INFORMATION\_SCHEMA.COLUMNS (Tipos Personalizados)

Colunas que usam tipos personalizados de extensões são visíveis por meio da
view padrão `INFORMATION_SCHEMA.COLUMNS`. Os tipos personalizados aparecem como
`extension_name.type_name` nas colunas `DATA_TYPE` e `COLUMN_TYPE`
(por exemplo, `vsql_complex.COMPLEX`).

**Exemplo:**

```sql theme={null}
-- Find all columns using custom extension types
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE '%.%'
ORDER BY TABLE_SCHEMA, TABLE_NAME;

-- Find columns using a specific extension's types
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';
```

**Saída de exemplo:**

```
+--------------+------------+-------------+---------------------+
| TABLE_SCHEMA | TABLE_NAME | COLUMN_NAME | DATA_TYPE           |
+--------------+------------+-------------+---------------------+
| mydb         | signals    | impedance   | vsql_complex.COMPLEX|
| mydb         | signals    | frequency   | vsql_complex.COMPLEX|
+--------------+------------+-------------+---------------------+
```

***

### INFORMATION\_SCHEMA.EXTENSION\_REGISTRATION

Expõe a struct de registro VEF em memória de cada extensão carregada como um documento JSON. Use-a para verificar se o servidor analisou corretamente as funções, os tipos e as variáveis de sistema da sua extensão após o `INSTALL EXTENSION`.

```sql theme={null}
SELECT EXTENSION_NAME, NEGOTIATED_PROTOCOL, REGISTRATION_JSON
FROM INFORMATION_SCHEMA.EXTENSION_REGISTRATION
WHERE EXTENSION_NAME = 'vsql_complex';
```

| Coluna                | Tipo              | Descrição                                                                                |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
| `EXTENSION_NAME`      | `VARCHAR(64)`     | Nome da extensão instalada.                                                              |
| `NEGOTIATED_PROTOCOL` | `BIGINT UNSIGNED` | Versão do protocol VEF negociada entre a extensão e o servidor.                          |
| `REGISTRATION_JSON`   | `longtext`        | Serialização JSON da struct `vef_registration_t`, incluindo os arrays `funcs` e `types`. |

***

## Consultas Comuns

### Encontrar Dependências de Extensões

Encontre quais colunas usam os tipos de uma extensão específica antes de desinstalá-la:

```sql theme={null}
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%';
```

### Listar Todas as Extensões e Suas Colunas de Tipos Personalizados

```sql theme={null}
-- All installed extensions
SELECT EXTENSION_NAME, EXTENSION_VERSION
FROM INFORMATION_SCHEMA.EXTENSIONS
ORDER BY EXTENSION_NAME;

-- All columns using custom types across all extensions
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE '%.%'
ORDER BY DATA_TYPE, TABLE_SCHEMA, TABLE_NAME;
```

### Encontrar Tabelas que Usam Tipos de Extensões

```sql theme={null}
SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE DATA_TYPE LIKE 'vsql_complex.%'
ORDER BY TABLE_SCHEMA, TABLE_NAME;
```

***

## Variáveis de Sistema

### veb\_dir

Somente leitura em tempo de execução. Caminho para o diretório onde o servidor procura arquivos de bundle de extensão `.veb`. Definida em `my.cnf` sob `[mysqld]`; não pode ser alterada sem reiniciar o servidor.

```sql theme={null}
SHOW VARIABLES LIKE 'veb_dir';
```

**Escopo:** Global, somente leitura em tempo de execução. Configure em `my.cnf`:

```ini theme={null}
[mysqld]
veb_dir=/path/to/extensions/
```

Apenas um único diretório é compatível. Consulte [Gerenciando Extensões](/docs/pt-BR/mysql-8.4/0.0.5/managing) para posicionamento e solução de problemas.

***

### villagesql\_server\_version

Variável global somente leitura. Retorna a string de versão do VillageSQL compilada
no binário do servidor. O formato é
`{codebase}_{major}.{minor}.{patch}[-prerelease]`, onde `codebase` nomeia o
fork de origem do qual este build deriva (aqui, `mysql-8.4`). Isso é diferente
de `villagesql_schema_version`, que informa a versão gravada no
catálogo de metadados interno no mesmo formato `{codebase}_{version}`.

```sql theme={null}
SELECT @@villagesql_server_version;
-- Example output: mysql-8.4_0.0.5

-- Show all VillageSQL system variables at once
SHOW VARIABLES LIKE 'villagesql_%';
```

**Escopo:** Global, somente leitura. Não pode ser definida em tempo de execução.

***

### villagesql\_vef\_server\_protocol

Variável global somente leitura. Retorna a maior versão do protocol VEF compatível
com este build do servidor. Os autores de extensões podem comparar esse valor com as
constantes de protocol em `types.h` para determinar quais recursos da ABI estão disponíveis
durante o registro.

```sql theme={null}
SELECT @@villagesql_vef_server_protocol;
```

| Propriedade     | Valor                         |
| --------------- | ----------------------------- |
| **Escopo**      | Global                        |
| **Acesso**      | Somente leitura               |
| **Tipo**        | Inteiro sem sinal (`0`–`255`) |
| **Valor atual** | `4` (`VEF_PROTOCOL_4`)        |

**O que o Protocol V4 adiciona**

As extensões que negociam `VEF_PROTOCOL_4` ou superior ganham acesso ao
campo `variable_length` em `vef_type_desc_t`. Quando definido como `true`, o
tamanho persistido do tipo é determinado por valor, em vez de ser um único
espaço fixo. Os tipos de comprimento variável também devem declarar
`max_persisted_length` como um limite superior. Use o método construtor
`variable_length_type()` em `TypeBuilder` para definir essa flag (não escreva
`variable_length` diretamente). O campo é lido pelo servidor apenas quando o
protocol negociado é `VEF_PROTOCOL_4` ou superior.

O `VEF_PROTOCOL_4` também adiciona o campo `max_result_length` em `vef_func_desc_t`. Uma
função pode declarar o comprimento máximo (em caracteres) do seu resultado `STRING` para que
um resultado materializado (tabelas temporárias de GROUP BY/DISTINCT, `CREATE TABLE ... SELECT`,
UNION) contenha o valor completo em vez de truncá-lo na largura do argumento. `0`
recorre à largura do argumento; aplica-se somente a STRING e é limitado a
`VEF_MAX_RESULT_LENGTH` (16 MiB / 16777216 bytes). Um valor declarado maior é
limitado a esse teto. Defina-o com o método construtor `max_result_length()` em
`FuncBuilder`.

O Protocol V4 está em desenvolvimento ativo. As extensões que optarem por ele devem ser
compiladas com `-DVSQL_USE_DEV_ABI=ON` e devem esperar mudanças na ABI antes que ele
estabilize.

Consulte `abi/types.h` para as definições completas de `vef_type_desc_t` e `vef_func_desc_t`,
`type_builder.h` para `variable_length_type()`, e
`func_builder.h` para `max_result_length()`.

O valor reflete a constante de tempo de compilação `vef_server_protocol_version`
e não pode ser alterado em tempo de execução.

***

### villagesql\_build\_info

Variável global somente leitura. Retorna um objeto JSON com metadados sobre como este
binário do servidor foi compilado: o commit de origem, o estado da work-tree e o ambiente
de compilação.

```sql theme={null}
SELECT @@villagesql_build_info;
```

| Campo             | Tipo    | Descrição                                                                         |
| ----------------- | ------- | --------------------------------------------------------------------------------- |
| `git_sha`         | string  | SHA completo de 40 caracteres do commit de origem, ou `"unknown"` se indisponível |
| `is_dirty`        | bool    | `true` se a work-tree tinha alterações não commitadas no momento da compilação    |
| `files_added`     | integer | Arquivos adicionados ou não rastreados no momento da compilação                   |
| `files_deleted`   | integer | Arquivos removidos no momento da compilação                                       |
| `files_modified`  | integer | Arquivos modificados no momento da compilação                                     |
| `build_timestamp` | string  | Timestamp UTC ISO-8601, por exemplo `"2026-06-17T12:34:56Z"`                      |
| `build_host`      | string  | Nome do host da máquina de compilação                                             |
| `build_os`        | string  | Sistema operacional do host: `"linux"` ou `"macos"`                               |
| `build_arch`      | string  | Arquitetura de CPU do host: `"x86_64"`, `"aarch64"` ou `"arm64"`                  |

**Escopo:** Global, somente leitura. Não pode ser definida em tempo de execução.

Um build de release limpo tem `is_dirty: false` e os três campos de contagem de arquivos em zero.
Um build a partir de uma work-tree modificada mostrará contagens diferentes de zero em `files_added`,
`files_deleted` ou `files_modified`.

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Gerenciando Extensões" icon="sliders" href="/docs/pt-BR/mysql-8.4/0.0.5/managing">
    Monitore e solucione problemas de extensões
  </Card>

  <Card title="Instalando Extensões" icon="download" href="/docs/pt-BR/mysql-8.4/0.0.5/install">
    Adicione novas extensões
  </Card>

  <Card title="Arquitetura de Extensões" icon="sitemap" href="/docs/pt-BR/mysql-8.4/0.0.5/architecture">
    Entenda os detalhes internos
  </Card>

  <Card title="Extensões Disponíveis" icon="list" href="/docs/pt-BR/mysql-8.4/0.0.5/extensions">
    Navegue pelo catálogo de extensões
  </Card>
</CardGroup>