Skip to main content
O VillageSQL Extension Framework (VEF) chama o código da extensão em locais predefinidos do código do servidor MySQL. Tudo o que acontece com a saída da extensão (recuperação de falhas, replicação, operações de esquema, backups) é tratado pelo servidor da mesma forma que ele trata qualquer tipo de coluna nativo. Este documento descreve essa fronteira: o que o VEF faz, o que as extensões fazem e como o sistema resultante se comporta em operação. Os exemplos ao longo desta página usam a extensão vsql-uuid para ilustrar como os dados fluem.

​
A fronteira da ABI

As extensões do VillageSQL interagem com o servidor por meio de uma interface binária (ABI) com uma separação clara de responsabilidades entre a extensão e o servidor. O servidor controla:
  • Armazenamento: o InnoDB lê e grava bytes; ele não os interpreta
  • Esquema: os metadados do tipo de coluna e qual extensão registrou cada tipo são armazenados nas tabelas de sistema do VillageSQL e persistem entre reinicializações
  • Recuperação, replicação e backups: essas operações atuam sobre bytes brutos, da mesma forma que com qualquer tipo de coluna nativo
  • Registro de extensões: nomes, versões e registros de funções/tipos são recarregados das tabelas de sistema do VillageSQL na inicialização
A extensão controla:
  • Formato binário: a função de codificação from_string define o que é gravado em disco; to_string faz a leitura de volta durante a saída
  • Regras de negócio: validação, comparação, hashing e tratamento de erros
  • Estado: as extensões não persistem nada além dos bytes que o servidor armazena para elas
Para a interface binária completa (structs, typedefs de pointers de função e versionamento de protocol), consulte villagesql/sdk/include/villagesql/abi/types.h no repositório do servidor.

​
Como os tipos personalizados são armazenados

Quando você declara uma coluna como UUID (como exemplo do vsql-uuid), o servidor armazena um bloco de bytes brutos de tamanho fixo por linha. A forma legível por humanos, como d7d665f3-bb13-4c2f-b10f-d2126eb40cba, existe apenas nas fronteiras: from_string a codifica em binário na gravação e to_string a decodifica de volta na leitura. Tudo o que está no meio (armazenamento, redo log, recuperação de falhas, binary log) atua sobre esses bytes sem interpretá-los.

​
Recuperação de falhas

As extensões são recarregadas automaticamente ao reiniciar o servidor — nenhuma intervenção manual é necessária. Você pode verificar isso por meio de INFORMATION_SCHEMA.EXTENSION_REGISTRATION, que mostra a mesma entrada de registro após a reinicialização que antes dela. Os dados das linhas sobrevivem à recuperação de falhas normal do InnoDB. O formato binário da extensão nunca recebe tratamento especial — o InnoDB lida com uma coluna UUID exatamente como faz com uma coluna VARBINARY.

​
Formato do binary log

Na replicação em formato de linha (o padrão), os valores de tipos personalizados trafegam como binário bruto no binary log. Não há etapa de recodificação: o from_string da extensão não é chamado ao gravar o binlog, e o to_string é chamado apenas quando um cliente lê o valor de volta. Uma entrada de binary log em nível de linha para uma coluna UUID tem esta aparência:
Esses 16 bytes brutos fluem pelo binary log sem alterações. Um consumidor com a extensão instalada pode decodificá-los para o valor legível por meio de to_string; um sem ela (um pipeline de CDC externo ou um leitor de binlog) vê apenas os bytes brutos.

​
Restauração

Restaurar um servidor VillageSQL funciona da mesma forma que a recuperação de falhas: o servidor inicializa, lê seus registros de extensões e carrega cada extensão automaticamente. Nenhum tratamento especial é necessário para colunas com tipo de extensão — os bytes brutos estão no backup, e as extensões os decodificam sob demanda. As extensões não são armazenadas dentro do banco de dados — elas residem como arquivos .veb em veb_dir no disco. Se o arquivo VEB estiver ausente quando o servidor inicializar na instância restaurada, a inicialização é abortada com VEB file not found. O .veb_expansion_cache não substitui o próprio .veb. Ao distribuir sua extensão, certifique-se de que seus usuários saibam que devem incluir o veb_dir em qualquer backup ou migração de servidor, junto com o diretório de dados.

​
Operações de esquema

ALTER TABLE em tabelas com colunas de tipo de extensão se comporta exatamente como para tipos nativos. O servidor rastreia a vinculação da coluna à extensão em seus metadados de esquema, e essa vinculação sobrevive à reconstrução da tabela. Adicionar ou modificar outras colunas em uma tabela com uma coluna id do vsql-uuid deixa os dados UUID intactos.