Pular para o conteúdo principal
As capabilities desta página estão em Preview: suas APIs não são estáveis, e uma extensão que declara uma delas requer vsql_allow_preview_extensions = ON para instalar. Consulte Capabilities Preview para saber como habilitar o nível Preview e registrar uma capability. O column storage permite que uma extensão registre um layout binário personalizado em disco diretamente com o InnoDB para um de seus tipos personalizados, em vez de rotear os bytes do tipo através do payload VARBINARY da linha. Use-o quando o seu tipo precisa de um formato em disco que o VARBINARY não consegue expressar — por exemplo, um array compactado de floats que precisa residir em páginas dedicadas. Este é um recurso de capability: ele habilita novos layouts de armazenamento, não é um botão de ajuste para os existentes.
O column storage é uma ABI Preview — em desenvolvimento ativo e pode mudar entre versões. Atualmente cobre apenas a persistência em nível de linha; uma coluna com armazenamento personalizado aceita apenas um índice personalizado, e um índice comum é recusado com ERROR 3219 (HY000): InnoDB: Indexing for types with column storage is supported only with custom index.

Declarando as Capabilities

Duas capabilities Preview trabalham juntas:
  • vsql::preview::storage — abre acesso à infraestrutura de armazenamento do InnoDB (mini-transações, segmentos, páginas). Declare uma StorageCapability no escopo do arquivo.
  • vsql::preview::column_store — vincula uma implementação de armazenamento por tipo a um dos tipos personalizados da extensão. Declare uma ColumnStoreCapability no escopo do arquivo usando make_column_store<Ctx>(TYPE).…build().
Ambas devem ser passadas para .with() em make_extension():
make_column_store<MyCtx>(MY_TYPE) liga a implementação a um tipo personalizado registrado na mesma extensão. Todos os sete slots são obrigatórios no momento do build(), porque cada um mapeia para um ponto distinto no ciclo de vida da coluna que o InnoDB alcançará durante a operação normal.

As Sete Funções de Armazenamento

Toda função recebe storage::Column::StorageCtx<MyCtx>*, cujo acessador user() retorna o estado por coluna da extensão e cujo arena() fornece alocação gerenciada pelo servidor para objetos auxiliares. Toda função retorna false em caso de sucesso e true em caso de erro, escrevendo uma mensagem em error_msg (capacidade error_msg_len). O servidor escreve essa mensagem no seu log de erros; um create ou insert que falha faz a instrução falhar com ERROR 3219 (HY000): InnoDB: Custom type operation failed. See server error log for details.
mark_delete e purge são distintos porque o MVCC do InnoDB requer que as linhas excluídas permaneçam legíveis por snapshots mais antigos até que o purge seja executado.

Contexto por Coluna e a Arena

O SDK C++ constrói MyCtx por padrão antes de chamar create ou load — ctx->user() já está populado quando a sua função é acionada. MyCtx deve ser construível por padrão; o SDK C++ chama T() sem argumentos. Use ctx->user() diretamente para inicializar o estado. Não chame ctx->arena().construct<MyCtx>() — isso aloca uma segunda instância não utilizada e ctx->user() não aponta para ela.
load segue o mesmo padrão — ctx->user() é pré-populado e storage_ref carrega o valor compactado armazenado por ctx->set_ref() em create:
Use ctx->arena() apenas para alocar objetos auxiliares que são grandes demais ou dinâmicos demais para embutir diretamente em MyCtx. O SDK C++ destrói a arena (e chama ~MyCtx()) automaticamente após o retorno de drop, independentemente de drop ter sucesso.

Utilitários de Acesso ao InnoDB

Inclua <villagesql/preview/storage_api.h> para os primitivos do InnoDB. Todas as leituras e escritas de página devem ocorrer dentro de uma mini-transação:
Confirmar a mini-transação libera os latches de página e escreve os registros do redo log que tornam as mudanças duráveis. Segmentos são reservados no momento do create — veja os exemplos de create e load em Contexto por Coluna acima para o padrão completo de configuração. Durante as operações DML, obtenha uma referência de segmento a partir da página raiz para alocar novas páginas:
Páginas são lidas com um latch compartilhado e escritas com um exclusivo. Passe mtr_ref para as chamadas de escrita para que o InnoDB registre a mudança:
Constantes de layout de página: Os acessadores de página rejeitam um offset dentro da região de cabeçalho ou de trailer: um build de release pula a leitura ou a escrita, e um build sem NDEBUG falha em um assert. O InnoDB usa esses intervalos de bytes para sua própria contabilidade e checksum.