Pular para o conteúdo principal
Quando o servidor chama uma função em uma extensão, ele passa os argumentos e lê o resultado de volta por meio de um conjunto fixo de estruturas C. Os tipos personalizados funcionam da mesma forma: a extensão descreve cada tipo em uma estrutura que o servidor lê quando você instala a extensão e cada vez que o servidor inicia. Um protocolo é uma versão numerada dessas estruturas e das regras para preenchê-las. Cada novo protocolo acrescenta campos às estruturas sem mover os campos que uma extensão mais antiga lê, e o servidor mantém o código que lê cada protocolo estável mais antigo. É por isso que o servidor ainda consegue carregar uma extensão que foi compilada para um protocolo mais antigo. Você não define o número do protocolo por conta própria. O SDK com o qual você compila a extensão é que o define: cada versão do SDK compila extensões para um protocolo estável, e seus cabeçalhos de desenvolvimento (-DVSQL_USE_DEV_ABI=ON) compilam para o protocolo de desenvolvimento. Para mover uma extensão para um protocolo mais novo, recompile-a com um SDK mais novo.

Como o servidor escolhe um protocolo

Quando você instala uma extensão, o servidor oferece seu protocolo mais novo e a extensão declara o protocolo para o qual foi compilada. O servidor e a extensão passam então a usar o menor dos dois números. Por exemplo, um servidor que oferece o Protocol 4 conversa com uma extensão compilada para o Protocol 3 usando o Protocol 3, e não dá a essa extensão nenhum recurso que o Protocol 4 acrescenta. Para ver o protocolo de cada extensão instalada, consulte INFORMATION_SCHEMA.EXTENSION_REGISTRATION:
A coluna NEGOTIATED_PROTOCOL contém o protocolo acordado entre o servidor e a extensão.

Protocolos estáveis e de desenvolvimento

Os protocolos de número ímpar são estáveis. Hoje o servidor aceita todos os protocolos estáveis, desde o Protocol 1, de modo que uma extensão que você compilou para um protocolo estável continua podendo ser instalada em servidores mais novos sem recompilação. Os protocolos de número par são versões de desenvolvimento. O servidor aceita apenas seu próprio protocolo de desenvolvimento, e as estruturas desse protocolo podem mudar entre dois builds do servidor. Uma extensão compilada com os cabeçalhos de desenvolvimento (-DVSQL_USE_DEV_ABI=ON) pode parar de funcionar depois que você atualiza o servidor. Se isso acontecer, recompile-a contra o novo servidor. Quando uma versão promove o protocolo de desenvolvimento ao próximo número estável, o servidor deixa de aceitar o número de desenvolvimento antigo. INSTALL EXTENSION então falha com extension uses obsolete unstable protocol version, seguido dos números antigo e atual. A mesma verificação é executada quando o servidor inicia, de modo que um servidor não inicia enquanto tiver uma extensão desse tipo instalada. Antes de atualizar o servidor, recompile contra a nova versão cada extensão que você compilou com os cabeçalhos de desenvolvimento.
Alterado na versão 0.0.8-dev. O Protocol 4 torna-se o Protocol 5 estável, para o qual o SDK 0.0.8 compila. Os cabeçalhos de desenvolvimento do 0.0.8 compilam para o Protocol 6. O servidor rejeita o Protocol 4, que fica sem suporte. O Protocol 1 e o Protocol 3 ficam descontinuados: o servidor ainda os aceita, mas novas extensões devem usar o Protocol 5.

Protocolo 3

Os SDKs 0.0.4 a 0.0.7 compilam extensões do Protocol 3.
Alterado na versão 0.0.8-dev. Uma extensão que você compilou com um desses SDKs continua funcionando em servidores mais novos, com o mesmo comportamento, e você não precisa recompilá-la.Se você a recompilar com o SDK 0.0.8, ela passa para o Protocol 5 e pode usar estes recursos:
  • .max_result_length(), que dimensiona a coluna de resultado de uma função STRING ou BINARY para que um resultado materializado não seja cortado na largura do argumento.
  • Ganchos de carregamento e descarregamento, .on_init() e .on_deinit().
  • Tipos personalizados de comprimento variável, .variable_length_type().
  • O tipo de parâmetro e de resultado BINARY, para bytes brutos.
  • A forma binária de um tipo personalizado, .from_binary() e .to_binary(), que o SQL chama como TYPE::from_binary e TYPE::to_binary.
  • Um prerun que vê os valores dos argumentos constantes.
  • Verificações de tipo no momento da resolução, .bind_and_check_types().
  • Um out.set() que retorna por inteiro um valor STRING maior que o buffer, enquanto o Protocol 3 corta o valor.
  • Uma exceção que escapa de uma função faz a instrução falhar com um erro.
Um comportamento muda quando você recompila: o Protocol 3 e o Protocol 5 passam um argumento STRING de formas diferentes. Uma função do Protocol 3 recebe os bytes do argumento sem alteração, no conjunto de caracteres do próprio argumento. Uma função do Protocol 5 recebe o argumento como texto utf8mb4, que o servidor converte a partir do conjunto de caracteres do chamador. Por exemplo, a string latin1 _latin1 X'E9' (é) chega a uma função do Protocol 3 como o único byte E9, e chega a uma função do Protocol 5 como os dois bytes C3 A9. Se o argumento for uma string binária que não é utf8mb4 válido, a instrução falha:
Antes de recompilar, encontre cada função que lê bytes brutos de um argumento STRING, como uma função de hash ou de criptografia, e declare esse parâmetro como BINARY. O mesmo vale para uma extensão escrita no estilo do Protocol 1.

Protocolo 1

O Protocol 1 é estável desde a versão 0.0.1. O servidor ainda o aceita, mas ele provavelmente será descontinuado em uma versão futura. Escreva novas extensões com a API tipada dos guias Criando Extensões em C++ e Desenvolvimento em C++. Esta seção é uma referência para extensões existentes escritas no estilo do Protocol 1. Um SDK mais novo ainda compila esse estilo, e compila a extensão para seu próprio protocolo estável.
Alterado na versão 0.0.8-dev. O Protocol 1 fica descontinuado. O servidor ainda o aceita, mas novas extensões devem usar o Protocol 5.

API de Tipos Baseada em Pointers de Função

Os tipos personalizados do Protocol 1 são registrados usando pointers de função explícitos em vez do template vsql::make_type<>. As assinaturas das funções diferem das equivalentes tipadas. Elas recebem pointers brutos e comprimentos, e não recebem objetos Arg e Result.

Assinaturas de Funções

Registro

Esta forma exige #include <villagesql/extension.h> (não <villagesql/vsql.h>) e using namespace villagesql;.
vsql::make_type<kMyTypeName>() (com um NTTP de string em tempo de compilação) é a forma preferida. make_type(MYTYPE) (sem parâmetro de template) é a forma do Protocol 1 — ela continua com suporte, mas provavelmente será descontinuada em uma versão futura.

Estilo de ABI Bruta (Funções)

As implementações de VDF do Protocol 1 podem passar as structs C brutas diretamente em vez de usar wrappers tipados. Este estilo continua com suporte, mas provavelmente será descontinuado em uma versão futura — use a API tipada de argumento/resultado para todo código novo.
Esta assinatura bruta por argumento — void(vef_context_t*, vef_invalue_t* arg0, ..., vef_vdf_result_t*) — é detectada apenas pelo make_func<>() de <villagesql/extension.h>. O make_func<>() de <villagesql/vsql.h> rejeita em tempo de compilação qualquer assinatura bruta vef_context_t*/vef_invalue_t*/vef_vdf_result_t*.

Constantes de Resultado

A ABI bruta comunica o estado do resultado por meio de vef_return_value_type_t definido em result->type: Com a API tipada, out.set(), out.set_null(), out.warning() e out.error() tratam disso automaticamente.

Registro de Agregados no Protocol 1

O construtor make_func<>() de <villagesql/extension.h> não possui os membros .clear<>() ou .accumulate<>(). Esses métodos existem apenas no construtor separado make_aggregate_func<State, &result_fn>() de <villagesql/vsql.h>, que usa assinaturas tipadas baseadas em State& em vez de pointers brutos vef_context_t*/vef_vdf_args_t*. Use a abordagem tipada de agregados para todo código novo. Um registro bruto em VEF_PROTOCOL_3 ou superior também pode definir manualmente os callbacks clear e accumulate em vef_func_desc_t.