Use o Laravel com o ClickHouse Managed Postgres

O Laravel é um framework web em PHP com um ORM integrado (Eloquent), um sistema de migrações e a ferramenta de linha de comando artisan. Neste guia, você vai apontar um novo aplicativo Laravel para o ClickHouse Managed Postgres, criar uma tabela tasks com uma migração e servir as linhas dela a partir de uma rota. Todas as conexões usam TLS com verificação completa de certificados.

Pré-requisitos

PHP 8.3 ou superior, conforme exigido pelo Laravel 13, com a extensão pdo_pgsql. Execute php -m e verifique se pdo_pgsql aparece na lista.
Composer
Uma conta do ClickHouse Cloud
psql, para criar o banco de dados. Você também pode executar a instrução CREATE DATABASE no SQL Console.

Criar um serviço ClickHouse Managed Postgres

No console do ClickHouse Cloud, clique em New service e selecione Postgres. A instância fica pronta em poucos minutos. Para um passo a passo, consulte o guia de início rápido.

Obtenha os detalhes de conexão

Clique em Connect na barra lateral esquerda do seu serviço. O modal exibe o nome de usuário, a senha, o servidor e a porta, além de uma chave Directly / via PgBouncer. Uma aplicação PHP não mantém um pool de conexões entre requisições. Por padrão, cada requisição abre uma nova conexão com o Postgres e a encerra ao final da requisição. Neste guia, a aplicação se conecta pelo PgBouncer incluído no serviço, na porta 6432, para que essas conexões de curta duração compartilhem um pequeno conjunto de backends do Postgres. As migrações se conectam diretamente ao Postgres na porta 5432, pois executam DDL e podem manter transações longas. Selecione via PgBouncer para ver os detalhes da conexão com pooling. A porta muda para 6432, e as strings de conexão passam a incluir sslmode=verify-full. No mesmo modal, clique em Download CA certificate. Você também pode baixá-lo em Settings → CA Certificate. O certificado é exclusivo da sua instância, o que permite ao driver usá-lo para verificar se está se comunicando com o seu servidor.

Configure o projeto

Crie um projeto Laravel:

composer create-project laravel/laravel laravel-managed-postgres
cd laravel-managed-postgres

Vai adicionar a um app existente?Pule o composer create-project. No seu projeto, verifique se php -m lista pdo_pgsql, depois siga o restante desta seção e continue em Configurar a conexão, que muda o app de SQLite para Postgres. Em seguida, php artisan migrate cria suas tabelas existentes no Postgres, mas não copia os dados do SQLite.

Mova o certificado de CA que você baixou para o diretório do projeto e renomeie-o para ca-certificate.pem. Crie um banco de dados para o app. Substitua <PASSWORD> e o host pelos valores do modal Connect:

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_laravel;"

CREATE DATABASE

Configure a conexão

Por padrão, o Laravel usa SQLite. Abra o arquivo .env e substitua a linha DB_CONNECTION=sqlite e as linhas DB_ comentadas logo abaixo dela por:

.env

DB_CONNECTION=pgsql
DB_HOST=your-instance.pg.clickhouse.cloud
DB_PORT=6432
DB_DATABASE=guide_laravel
DB_USERNAME=postgres
DB_PASSWORD=<PASSWORD>
DB_SSLMODE=verify-full
DB_SSLROOTCERT=/absolute/path/to/your-project/ca-certificate.pem

Use o caminho absoluto para ca-certificate.pem. O libpq resolve caminhos relativos com base no diretório de trabalho do processo PHP, que varia conforme a forma como o PHP executa sua aplicação. Se a sua senha contiver espaços ou #, coloque-a entre aspas duplas. Mantenha o .env fora do controle de versão. A conexão pgsql padrão em config/database.php lê DB_SSLMODE, mas não o caminho do certificado da CA. Abra config/database.php e adicione as entradas sslrootcert e options à conexão pgsql:

config/database.php

        'pgsql' => [
            'driver' => 'pgsql',
            'url' => env('DB_URL'),
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '5432'),
            'database' => env('DB_DATABASE', 'laravel'),
            'username' => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
            'charset' => env('DB_CHARSET', 'utf8'),
            'prefix' => '',
            'prefix_indexes' => true,
            'search_path' => 'public',
            'sslmode' => env('DB_SSLMODE', 'prefer'),
            'sslrootcert' => env('DB_SSLROOTCERT'),
            'options' => [
                PDO::ATTR_EMULATE_PREPARES => true,
            ],
        ],

O Laravel adiciona sslmode e sslrootcert ao DSN do PDO, e a extensão pdo_pgsql os repassa à libpq, que verifica a cadeia de certificados e o hostname. PDO::ATTR_EMULATE_PREPARES faz com que o PDO envie cada consulta com os valores já vinculados, em vez de criar um prepared statement no lado do servidor. Ative essa opção ao se conectar pelo PgBouncer. Quando o pdo_pgsql é compilado com a libpq 16 ou anterior, como no Debian 12, o PHP libera cada prepared statement com uma instrução SQL DEALLOCATE. Como o PgBouncer renomeia os prepared statements no servidor, o DEALLOCATE falha. Dentro de uma transação, isso aborta a transação, e a consulta seguinte falha com current transaction is aborted. Com a libpq 17 ou posterior, as configurações padrão também funcionam. Execute php -i | grep libpq para ver a sua versão. Verifique a conexão:

php artisan db:show

  PostgreSQL ................................ 18.6 (Ubuntu 18.6-1.pgdg22.04+2)  
  Connection ........................................................... pgsql  
  Database ..................................................... guide_laravel  
  Host ..................................... your-instance.pg.clickhouse.cloud  
  Port .................................................................. 6432  
  Username .......................................................... postgres  
  URL ........................................................................  
  Open Connections ........................................................ 44  
  Tables ................................................................... 0  

Sem a linha sslrootcert, o verify-full falha com root certificate file ".../.postgresql/root.crt" does not exist, porque o libpq recorre ao seu local padrão de CA. Com a CA errada, a conexão falha com SSL error: certificate verify failed.

Crie um model e uma migração

Gere um model Eloquent e uma migração para uma tabela tasks:

php artisan make:model Task -m

Abra a nova migração em database/migrations/ (o nome do arquivo termina em _create_tasks_table.php) e adicione as colunas title e done ao método up:

database/migrations/xxxx_xx_xx_xxxxxx_create_tasks_table.php

    public function up(): void
    {
        Schema::create('tasks', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->boolean('done')->default(false);
            $table->timestamps();
        });
    }

Substitua o conteúdo de app/Models/Task.php para que as colunas possam ser atribuídas em massa e done seja retornado como booleano:

app/Models/Task.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Model;

#[Fillable(['title', 'done'])]
class Task extends Model
{
    protected function casts(): array
    {
        return [
            'done' => 'boolean',
        ];
    }
}

Execute as migrações pela conexão direta. Uma variável de ambiente tem precedência sobre o valor definido em .env, então basta alterar a porta:

DB_PORT=5432 php artisan migrate

   INFO  Preparing database.  

  Creating migration table ..................................... 289.95ms DONE

   INFO  Running migrations.  

  0001_01_01_000000_create_users_table ............................... 1s DONE
  0001_01_01_000001_create_cache_table ......................... 949.69ms DONE
  0001_01_01_000002_create_jobs_table ................................ 1s DONE
  2026_09_30_165735_create_tasks_table ......................... 240.59ms DONE

Além de tasks, esse comando cria as tabelas users, sessions, cache e jobs que uma nova aplicação Laravel usa por padrão. O Laravel registra as migrações já aplicadas na tabela migrations e, nas execuções seguintes, executa apenas as novas.

Consultar o banco de dados

Adicione algumas linhas usando o Eloquent no artisan tinker:

php artisan tinker --execute="App\Models\Task::create(['title' => 'Create a Managed Postgres service', 'done' => true]); App\Models\Task::create(['title' => 'Connect Laravel with verify-full TLS', 'done' => true]); App\Models\Task::create(['title' => 'Ship the app']); echo App\Models\Task::count();"

Adicione ao final de routes/web.php uma rota que retorne todas as tarefas em JSON:

routes/web.php

Route::get('/tasks', function () {
    return App\Models\Task::orderBy('id')->get();
});

O Laravel aplica as opções de conexão search_path, timezone e isolation_level por meio de instruções SET em nível de sessão ao se conectar, e essas configurações não são preservadas entre transações quando se usa o PgBouncer. Mantenha essas opções com os valores padrão ou, se precisar delas, conecte-se diretamente pela porta 5432. Recursos em nível de sessão, como LISTEN e advisory locks de sessão, também não funcionam através do PgBouncer. Consulte o FAQ.

Executar e verificar

Inicie o servidor de desenvolvimento:

php artisan serve --port=3104

   INFO  Server running on [http://127.0.0.1:3104].  

  Press Ctrl+C to stop the server

Abra http://localhost:3104/tasks no navegador. A resposta será semelhante a esta:

[
  {
    "id": 1,
    "title": "Create a Managed Postgres service",
    "done": true,
    "created_at": "2026-09-30T17:10:28.000000Z",
    "updated_at": "2026-09-30T17:10:28.000000Z"
  },
  {
    "id": 2,
    "title": "Connect Laravel with verify-full TLS",
    "done": true,
    "created_at": "2026-09-30T17:10:29.000000Z",
    "updated_at": "2026-09-30T17:10:29.000000Z"
  },
  {
    "id": 3,
    "title": "Ship the app",
    "done": false,
    "created_at": "2026-09-30T17:10:29.000000Z",
    "updated_at": "2026-09-30T17:10:29.000000Z"
  }
]

Para ver os dados no console, abra o SQL Console na barra lateral esquerda do seu serviço, expanda guide_laravel e depois public e clique na tabela tasks. O schema public também lista as tabelas padrão do Laravel, como users, sessions e migrations:

id	title	done	created_at	updated_at
1	Create a Managed Postgres service	true	2026-09-30 17:10:28	2026-09-30 17:10:28
2	Connect Laravel with verify-full TLS	true	2026-09-30 17:10:29	2026-09-30 17:10:29
3	Ship the app	false	2026-09-30 17:10:29	2026-09-30 17:10:29

Próximos passos

Conexão: strings de conexão, PgBouncer e TLS
Configurações: parâmetros do Postgres e do PgBouncer, como max_connections
Réplicas de leitura: direcione leituras para uma réplica com as conexões de leitura e escrita do Laravel
Segurança: listas de acesso por IP e rede privada

Primeiros passos

Recursos

Guias

Preços

Integração com ClickHouse

Migrações

Monitoramento

Perguntas frequentes

Use o Laravel com o ClickHouse Managed Postgres

Pré-requisitos

Criar um serviço ClickHouse Managed Postgres

Obtenha os detalhes de conexão

Configure o projeto

Configure a conexão

Crie um model e uma migração

Consultar o banco de dados

Executar e verificar

Próximos passos

​Pré-requisitos

​Criar um serviço ClickHouse Managed Postgres

​Obtenha os detalhes de conexão

​Configure o projeto

​Configure a conexão

​Crie um model e uma migração

​Consultar o banco de dados

​Executar e verificar

​Próximos passos

Pré-requisitos

Criar um serviço ClickHouse Managed Postgres

Obtenha os detalhes de conexão

Configure o projeto

Configure a conexão

Crie um model e uma migração

Consultar o banco de dados

Executar e verificar

Próximos passos