Como integrar o Supabase com o Laravel para banco de dados e armazenamento

Informatec Digital » Recursos » Como integrar o Supabase com o Laravel para bancos de dados e armazenamento

Se você trabalha com Laravel e se dedica à programação backend , e está pensando em migrar para um banco de dados PostgreSQL moderno e gerenciado como o Supabase , provavelmente já percebeu que simplesmente alterar algumas variáveis ​​no arquivo .env não é suficiente. Há detalhes de conexão, esquemas, autenticação e armazenamento de arquivos que, se negligenciados, podem levar a erros bastante complexos.

Além disso, se você quiser ir um passo além e usar o Supabase como armazenamento de arquivos integrado ao sistema de disco do Laravel (Storage), as coisas ficam um pouco mais complicadas: chaves de serviço, buckets, endpoints, drivers Flysystem personalizados, etc. A boa notícia é que tudo pode ser perfeitamente integrado — o banco de dados, o armazenamento e o gerenciamento de UUIDs — de uma maneira bastante simples.

Conectando o Laravel ao banco de dados Supabase

O primeiro passo é ter um projeto Laravel funcionando e conectá-lo ao banco de dados Postgres fornecido pela Supabase. Para isso, você precisa de um ambiente com PHP e Composer atualizados , podendo criar um novo projeto ou usar um já existente. No console, basta gerar o projeto usando o comando padrão do Laravel e, em seguida, começar a configurar a conexão.

Após configurar a estrutura do projeto, a prática comum é instalar um sistema de autenticação simples. O Laravel Breeze se encaixa perfeitamente, pois inclui templates Blade e um fluxo básico de login e cadastro , permitindo validar rapidamente se a conexão com o banco de dados está configurada corretamente e se é possível criar usuários sem problemas.

Para obter os detalhes de conexão, faça login no seu painel do Supabase e crie um novo projeto de banco de dados (você pode fazer isso diretamente em `database.new` , que o redirecionará para o assistente). Se você ainda não tem uma conta, verá primeiro a tela de cadastro; se já tiver uma, você irá diretamente para as configurações do projeto e para a seção onde encontrará a string de conexão.

Na página do projeto, na seção de conexão, você encontrará um botão "Conectar" ou similar. Ao clicar nele, serão exibidos vários formatos de string de conexão (URI, parâmetros individuais, etc.). Copie a URI completa, mas lembre-se de substituir a senha pela senha que você realmente usa para o banco de dados, pois uma senha padrão ou um valor de exemplo costuma ser exibido.

Com essas informações, você precisa acessar o arquivo .env do seu projeto Laravel e atualizar as variáveis ​​DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME e DB_PASSWORD, ou configurar a variável DATABASE_URL se preferir usar o formato de string completo. O objetivo é garantir que tudo aponte para o cluster Postgres da Supabase e não para o seu localhost.

Configure o driver Postgres e o esquema Supabase no Laravel.

No Laravel, o arquivo principal para configuração do banco de dados é o `config/database.php` . Embora seja possível usar diretamente o driver pgsql que acompanha o framework, ao trabalhar com o Supabase é comum aplicar algumas configurações adicionais, principalmente relacionadas a esquemas e opções específicas do PostgreSQL.

Uma configuração típica do Postgres no Laravel pode ser semelhante a esta, dentro do array de conexões, sob a chave 'pgsql' :

'pgsql' => ,

A chave aqui reside no parâmetro `search_path` . Por padrão, o Supabase utiliza o esquema `public`, que é o exposto por meio de suas APIs. Se você deseja manter sua aplicação Laravel separada desse esquema e evitar conflitos de tabelas ou políticas, é altamente recomendável alterar o `search_path` para o seu próprio esquema, por exemplo, `laravel` , como visto no exemplo anterior.

Dessa forma, as migrações e tabelas geradas pelo seu projeto serão criadas nesse esquema alternativo e não no esquema público. Essa separação simplifica bastante o gerenciamento de regras de segurança, RLS e acesso pelo painel do Supabase, sem sobrescrever nada que não seja necessário, mantendo a estrutura do banco de dados organizada.

Após ajustar o arquivo de configuração, você pode executar as migrações usando os comandos padrão do Laravel. Isso criará as tabelas de autenticação e quaisquer outras tabelas que você tenha definido. Se tudo estiver configurado corretamente, os comandos serão executados automaticamente no servidor Supabase Postgres.

Com as migrações concluídas, inicie o servidor de desenvolvimento com `artisan serve` e tente registrar e autenticar usuários. Se não houver erros de conexão ou migração, significa que o Laravel está se comunicando corretamente com o Supabase e você pode continuar desenvolvendo sua lógica de negócios normalmente.

Utilizando um driver Supabase específico no Laravel

Embora o driver padrão do PostgreSQL funcione, existe um pacote que adiciona um driver de banco de dados Supabase para Laravel , estendendo o comportamento do PostgreSQL com melhorias muito úteis, especialmente em relação ao tratamento de colunas UUID e à forma como as consultas são construídas.

Este pacote, distribuído como prahsys/laravel-supabase, é instalado via Composer e registra um driver adicional chamado supabase que você pode usar no seu arquivo config/database.php. Internamente, ele é baseado no driver Postgres do Laravel, mas incorpora configurações e gramáticas de consulta otimizadas para o ambiente específico do Supabase.

Após a instalação, você poderá declarar algo como o seguinte na seção de conexões :

'connections' => ,
    // otras conexiones...
],

A vantagem de usar esse driver é que você ainda obtém todo o poder do mecanismo do Postgres, mas ele também lida automaticamente com certos detalhes delicados do Supabase, especialmente ao trabalhar com UUIDs como chaves primárias ou campos de relacionamento . Isso evita ter que escrever conversões manuais em todas as consultas complexas.

O pacote também foi projetado para se integrar bem com as versões modernas do framework e do PHP, oferecendo compatibilidade oficial com Laravel 10.x, 11.x e 12.x e com PHP a partir da versão 8.1, bem como com qualquer banco de dados PostgreSQL padrão, incluindo, é claro, o Supabase.

Para garantir que tudo funcione corretamente, o pacote inclui um conjunto de testes automatizados. Você pode executar os testes com o comando `composer test`, que usará um banco de dados SQLite em memória para maior velocidade, ou preparar um arquivo `.env.testing` apontando para o seu Supabase e executar `composer test-supabase` para verificar o comportamento em um ambiente real com Postgres remoto.

Gerenciamento de UUIDs no Supabase e Laravel

O Supabase apresenta uma peculiaridade com colunas UUID: se você tentar comparar um UUID diretamente com uma string de texto sem conversão explícita, a consulta pode falhar ou retornar resultados inesperados . Em um ambiente Postgres padrão, você poderia resolver isso com conversões explícitas globais ou operadores personalizados, mas o Supabase não permite tais personalizações globais.

Isso implica que uma consulta direta ao estilo:

SELECT *
FROM users
WHERE id = '123e4567-e89b-12d3-a456-426614174000';

Não funcionará como você espera. No entanto, se você fizer a conversão explícita:

SELECT *
FROM users
WHERE CAST(id AS TEXT) = '123e4567-e89b-12d3-a456-426614174000';

A consulta foi bem-sucedida. O problema é que, no Laravel, ao escrever consultas com Eloquent ou o construtor de consultas, você não quer adicionar conversões de tipo (CASTs) a todas as cláusulas WHERE . É aí que entra o driver Supabase do pacote mencionado anteriormente, que adiciona essas conversões automaticamente.

Com esse driver ativo, você pode executar consultas comuns , como:

$user = User::find($uuidString);
$user = User::where('id', $uuidString)->first();
$users = User::whereIn('id', )->get();

E não apenas em consultas diretas, mas também em junções . Por exemplo, se você quiser recuperar postagens e juntá-las à tabela de usuários usando um campo UUID, você poderia fazer algo assim:

$posts = Post::join('users', 'posts.user_id', '=', 'users.id')
    ->where('users.email', '[email protected]')
    ->get();

O driver lida com a aplicação das conversões de texto necessárias às colunas UUID relevantes de forma transparente. Dessa forma, seu código permanece idiomático para Laravel e você não precisa escrever SQL puro ou usar truques estranhos em cada consulta complexa.

Se você deseja um controle mais preciso sobre quais colunas são consideradas UUIDs, o pacote oferece o trait ` CastsUuidColumns` para seus modelos Eloquent. Basta usá-lo em sua classe de modelo e definir um array protegido de colunas adicionais:

use Prahsys\Supabase\Traits\CastsUuidColumns;

class Post extends Model
{
    use CastsUuidColumns;

    protected $uuidColumns = ;
}

Essa característica faz três coisas importantes: inclui a chave primária como o UUID padrão, adiciona quaisquer colunas que você declarar à propriedade `$uuidColumns` e comunica essas informações ao construtor de consultas para que ele saiba onde aplicar as conversões. Isso torna todo o acesso a dados envolvendo UUIDs consistente e automatizado.

Para casos ainda mais avançados , você pode registrar um detector de coluna UUID personalizado. Usando a classe `PostgresGrammar` do pacote, você pode especificar uma função de retorno de chamada que, com base no nome da coluna ou no contexto da consulta, decide se ela deve ser tratada como um UUID. Por exemplo:

use Prahsys\Supabase\Database\Query\Grammars\PostgresGrammar;

PostgresGrammar::detectUuidColumnsWith(function ($columnName, $query) {
    return str_contains($columnName, 'uuid_')
        || in_array($columnName, );
});

Com essa função configurada, o sistema pode considerar como UUID todas as colunas cujo nome segue um determinado padrão ou está dentro de uma lista específica, adaptando-se às convenções de nomenclatura específicas do seu projeto.

Integre o Supabase Storage como um sistema de arquivos no Laravel.

Além do banco de dados, muitos projetos precisam armazenar imagens, documentos ou outros arquivos enviados pelos usuários. O Supabase inclui um serviço de armazenamento baseado em buckets que você pode usar como disco do Laravel através do Flysystem . Um adaptador específico está disponível para tratar o Supabase Storage como um driver adicional dentro do arquivo config/filesystems.php.

O pacote em questão fornece um adaptador Flysystem que se integra perfeitamente ao sistema de armazenamento do framework. Ele atende aos requisitos mínimos de PHP >= 8.1, Laravel 10.x e 11.x , e a extensão PHP fileinfo (ext-fileinfo), que o Laravel normalmente recomenda para manipulação de arquivos. A instalação é feita usando o Composer e, uma vez incluído, basta definir o disco Supabase na configuração.

No arquivo config/filesystems.php , dentro do array de discos, você adicionaria algo semelhante ao seguinte:

'supabase' => ,
    ],
    'signedUrlExpires' => 60 * 60 * 24,
],

O parâmetro `bucket` geralmente é simplesmente o nome do bucket de armazenamento que você criou no painel do Supabase (por exemplo, `myapp-file-uploads`). O `endpoint` é a URL base do serviço de armazenamento do projeto, também visível na seção correspondente do painel, e geralmente é derivado da URL e da região do projeto.

A opção `public` indica se o conteúdo do bucket será tratado como público por padrão. Se `true`, o adaptador gerará URLs acessíveis sem uma assinatura especial; se `false`, a opção `defaultUrlGeneration` entra em ação, podendo forçar a geração de URLs assinadas com um tempo de expiração especificado por `signedUrlExpires`. Essa configuração permite equilibrar segurança e conveniência, dependendo do tipo de arquivos que você manipula.

O URL geral do disco normalmente é deixado como nulo para que o adaptador o derive automaticamente do endpoint. Você só deve modificá-lo se estiver usando um proxy intermediário ou CDN e quiser que as rotas geradas apontem para esse domínio em vez do domínio nativo do Supabase.

Solucione problemas de erros de upload e entenda a chave para o armazenamento Supabase.

Um problema bastante comum ao tentar enviar arquivos para o Supabase Storage a partir do Laravel é receber mensagens como “Não foi possível gravar o arquivo no local: uploads/…” . Isso geralmente indica que, embora o driver esteja configurado, o Supabase está negando a operação de gravação devido a permissões insuficientes ou a uma configuração de chave incorreta.

No arquivo de configuração de disco do Supabase, `config/filesystems.php`, a configuração especifica o uso de uma "chave privilegiada" no campo `key`, declarando explicitamente que uma chave somente leitura não funcionará. Isso significa que você precisa usar uma chave de serviço com permissões de gravação no bucket, e não simplesmente uma chave de API pública do lado do cliente ou uma chave de compatibilidade com o S3 sem permissões de modificação.

No painel do Supabase, na seção de configuração de API e armazenamento, você encontrará chaves anônimas e chaves de função de serviço (ou seus equivalentes) , que possuem privilégios estendidos. É essa chave de serviço, e não a pública, que você deve colocar na variável SUPABASE_SECRET_ACCESS_KEY, que o driver lerá usando env('SUPABASE_SECRET_ACCESS_KEY').

Se você estiver testando com a chave S3 da configuração de armazenamento ou com as chaves de API genéricas do projeto, é muito provável que essas credenciais não tenham permissões de gravação para o bucket específico, resultando no erro de gravação. Alterar o valor da chave para uma chave de serviço válida com permissões de gravação e confirmar se o bucket existe e está nomeado corretamente geralmente resolve o problema.

Além da senha, é importante verificar se o bucket definido em SUPABASE_STORAGE_BUCKET corresponde exatamente ao criado na interface do Supabase, respeitando letras maiúsculas e minúsculas, e se o endpoint corresponde à URL correta para essa instância de armazenamento. Um detalhe como um caractere extra ou um domínio incorreto pode impedir que o adaptador localize o destino real dos arquivos.

Fluxo de trabalho com Laravel Breeze, Blade e armazenamento Supabase

Após configurar seu banco de dados e armazenamento, o próximo passo lógico é integrar tudo com a interface Laravel Breeze e os templates Blade . Dessa forma, os usuários podem se cadastrar, autenticar e enviar arquivos para o Supabase sem sair do ecossistema Laravel.

Em seus controladores, você usaria o facade Storage apontando para o disco Supabase. Por exemplo, para fazer o upload de um arquivo recebido de um formulário com um campo de entrada de arquivo, você poderia fazer algo como isto:

if ($request->hasFile('file')) {
    $path = $request->file('file')
        ->store('uploads', 'supabase');
}

Este código instrui o Laravel a usar o disco do Supabase e colocar o arquivo dentro da pasta virtual de uploads no bucket configurado. Se a chave e o endpoint estiverem corretos, o arquivo será enviado para o armazenamento do Supabase e você poderá recuperar seu caminho ou gerar URLs públicas ou assinadas usando os métodos de armazenamento padrão.

A vantagem dessa abordagem é que seu aplicativo mantém uma única interface para armazenamento, independentemente de estar usando disco local, Amazon S3, Supabase ou outro serviço compatível. A troca de provedores se resume a ajustar o arquivo config/filesystems.php e as variáveis ​​de ambiente, sem afetar a lógica de negócios.

Ao combinar isso com Blade e Breeze, você pode oferecer formulários de upload, listas de arquivos e links para download totalmente integrados à experiência do usuário do seu aplicativo. Além disso, a abordagem baseada em buckets e políticas do Supabase Storage permite que você aproveite seus controles de acesso e regras de segurança para definir o que cada usuário pode visualizar ou baixar.

Todo esse ecossistema de pacotes, drivers e configurações permite que o Laravel funcione perfeitamente com o Supabase, tanto em termos de dados relacionais com o Postgres quanto de armazenamento de arquivos e gerenciamento de UUIDs . Ao configurar corretamente as chaves, os esquemas e os drivers, você obtém uma integração muito robusta que evita muitos dos erros típicos encontrados ao tentar conectar as duas plataformas manualmente sem essas camadas de suporte.

Conectar o Laravel ao Supabase para banco de dados e armazenamento, aproveitar o driver dedicado do Supabase para gerenciar UUIDs sem complicações e usar o adaptador Flysystem para armazenamento permite criar aplicações modernas onde toda a infraestrutura complexa é encapsulada pela API limpa do Laravel, desde migrações e autenticação até o upload de arquivos para buckets seguros.