Busca Vetorial no Laravel Agora Suporta MariaDB

O Laravel 13 permite que desenvolvedores executem consultas nativas de busca vetorial no MariaDB, adicionando recursos de busca semântica ao ecossistema Laravel sem forçar uma migração para o PostgreSQL.

O novo suporte substitui a implementação anterior do framework, que era exclusiva para PostgreSQL, de modo que o familiar método whereVectorSimilarTo agora funciona diretamente com uma conexão MariaDB. Se você estiver construindo motores de recomendação, ferramentas de similaridade de documentos ou qualquer recurso que dependa da lógica de "vizinho mais próximo" (nearest-neighbor), a mudança remove um grande ponto de fricção.

Por que essa mudança é importante

O query builder do Laravel detectava anteriormente as necessidades de busca vetorial por meio de um teste instanceof que reconhecia apenas conexões PostgreSQL. Essa abordagem vinculava o recurso a um único driver e espalhava condicionais específicos de banco de dados pelo código-fonte.

A versão 13 move a lógica para a camada de gramática (grammar layer) e adiciona dois métodos específicos do driver:

  • supportsVectorDistance() – informa ao Laravel se a conexão atual pode calcular distâncias vetoriais.
  • compileVectorDistanceExpression() – constrói o fragmento SQL que realiza o cálculo.

Ao atribuir essas responsabilidades a cada driver, o framework abandona o "truque" de verificação de tipo (type-checking) e abre caminho para futuras extensões. Adicionar suporte para outro banco de dados agora significa implementar alguns métodos de driver em vez de espalhar blocos condicionais.

O MariaDB recebe as funções nativas, o MySQL não

O MariaDB já vem com funções vetoriais nativas. O MySQL padrão não as possui, a menos que você utilize uma oferta de nuvem especializada que adicione extensões de IA.

O Laravel evita deliberadamente o cálculo de similaridade no lado do PHP. Calcular vetores no PHP quebraria a paginação e tornaria o aplicativo lento sem aviso prévio. Lançar um erro quando o driver não consegue lidar com a operação oferece um modo de falha mais seguro.

O que os usuários de MySQL podem fazer agora

Se sua stack utiliza MySQL puro, você tem três caminhos realistas:

  1. Migrar para o MariaDB – uma substituição direta para a maioria das cargas de trabalho do MySQL, que oferece suporte vetorial nativo mantendo o mesmo ecossistema.
  2. Adicionar um serviço de busca dedicado – execute uma instância leve de PostgreSQL ao lado do MySQL apenas para consultas de similaridade.
  3. Viver sem ele – a busca semântica é opcional para muitas aplicações; se o benefício não superar o custo operacional, permanecer no MySQL pode ser a escolha pragmática.

Cada opção traz compensações em termos de complexidade operacional, latência e sobrecarga de manutenção. A decisão depende de quão central a busca vetorial é para a proposta de valor do seu produto.

Lições para o design de APIs

A mudança no Laravel ilustra um princípio de design mais amplo: evite espalhar verificações específicas de banco de dados por toda a lógica principal. Quando um recurso depende das capacidades de um motor específico, encapsule essa dependência atrás de uma interface de driver. A nova abordagem baseada em gramática faz exatamente isso, preparando o framework para futuras extensões sem precisar revisitar o query builder principal.

Desenvolvedores que criam seus próprios pacotes devem ficar atentos. Se você encontrar verificações instanceof para um tipo de banco de dados dentro da sua camada de serviço, mova essa responsabilidade para o driver ou para um adaptador dedicado. Isso mantém a API pública limpa e torna seu código à prova de futuro.