> ## 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 9.7.
</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`       | longtext | Versão para a qual a extensão mudará na próxima reinicialização, ou `NULL` |
| `PENDING_REQUESTED_AT`  | longtext | Quando uma mudança de versão pendente foi solicitada, ou `NULL`            |
| `PENDING_LAST_ERROR`    | longtext | Mensagem de uma mudança de versão que falhou, ou `NULL`                    |
| `PENDING_LAST_ERROR_AT` | longtext | 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-9.7/stable/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`   | `VARCHAR(65535)`  | 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-9.7/stable/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-9.7`). 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-9.7_0.0.6

-- All VillageSQL system variables at once. Not every one of them starts with
-- villagesql_, so a LIKE 'villagesql_%' pattern on its own misses some.
SHOW VARIABLES WHERE Variable_name LIKE 'villagesql\_%'
  OR Variable_name IN ('veb_dir', 'vsql_allow_preview_extensions');
```

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

***

### villagesql\_schema\_version

Variável global somente leitura. Retorna a versão gravada no catálogo de metadados
interno, no mesmo formato `{codebase}_{version}` que `villagesql_server_version`.
Uma string vazia significa que o schema do VillageSQL ainda não foi inicializado
neste diretório de dados.

```sql theme={null}
SELECT @@villagesql_schema_version;
-- Example output: mysql-9.7_0.0.6
```

**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. Ao instalar uma extensão, o servidor e a extensão
usam a maior versão do protocol que ambos suportam. Uma extensão compilada com
uma versão de protocol instável obsoleta não pode ser instalada — o
`INSTALL EXTENSION` falha com `Failed to load VEF extension`.

```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 Protocol V4 adiciona suporte a tipos personalizados de comprimento variável e
permite que uma função declare o comprimento máximo de seus resultados de
string. Ele está em desenvolvimento ativo sob a ABI de desenvolvimento
(opt-in) e pode mudar antes de estabilizar. Se você desenvolve extensões,
consulte [Operações de Tipo](/docs/pt-BR/mysql-9.7/stable/type-operations) e
[Criando Extensões em C++](/docs/pt-BR/mysql-9.7/stable/create) para saber o que
cada versão do protocol habilita.

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"`; vazio em um build de release |
| `build_host`      | string  | Nome do host da máquina de compilação; vazio em um build de release                        |
| `build_os`        | string  | Sistema operacional do host: `"Linux-6.18.15"` ou `"Darwin-24.3.0"`                        |
| `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 a partir de uma work-tree modificada mostra contagens diferentes de zero em
`files_added`, `files_deleted` ou `files_modified`, e nesse caso `is_dirty` é `true`. Um
build de release — cuja versão não carrega sufixo de pré-lançamento — força essas três
contagens a zero e deixa `build_timestamp` e `build_host` vazios, para que fontes
idênticas produzam um binário idêntico, e é por isso que `is_dirty` é sempre `false`
em um release.

***

### vsql\_allow\_preview\_extensions

Controla se o servidor aceita extensões que exigem uma capability em preview.
Enquanto estiver `OFF`, instalar uma delas falha:

```text theme={null}
ERROR 3219 (HY000): Failed to load VEF extension 'vsql_keyring_reader': extension requires preview capabilities but vsql_allow_preview_extensions is OFF
```

Ative com `SET PERSIST`:

```sql theme={null}
SET PERSIST vsql_allow_preview_extensions = ON;
```

| Property   | Value                               |
| ---------- | ----------------------------------- |
| **Escopo** | Global                              |
| **Acesso** | Legível; definida com `SET PERSIST` |
| **Tipo**   | Booleano                            |
| **Padrão** | `OFF`                               |

Use `SET PERSIST`, não `SET GLOBAL`. Extensões em preview são carregadas na
inicialização do servidor, então o valor precisa sobreviver a um restart, e
somente `SET PERSIST` grava em `mysqld-auto.cnf`; por isso `SET GLOBAL` é
rejeitado. Antes de `mysqld-auto.cnf` existir — em um servidor sendo iniciado
pela primeira vez — passe `--vsql_allow_preview_extensions=ON` na linha de
comando do `mysqld`.

Desativar novamente é rejeitado enquanto qualquer extensão que use uma
capability em preview ainda estiver instalada, porque essas extensões exigem
que o valor esteja ON quando o servidor inicia. Desinstale-as primeiro.

Veja [Capabilities Preview](/docs/pt-BR/mysql-9.7/stable/preview-capabilities) para
a lista de capabilities em preview e o que uma extensão faz com elas.

***

## Próximos Passos

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

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

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

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