Usar Laravel con ClickHouse Managed Postgres

Laravel es un framework web de PHP que incluye un ORM integrado (Eloquent), un sistema de migraciones y la herramienta de línea de comandos artisan. En esta guía, configurará una nueva aplicación de Laravel para conectarse a ClickHouse Managed Postgres, creará una tabla tasks mediante una migración y devolverá sus filas desde una ruta. Todas las conexiones usan TLS con verificación completa de certificados.

Requisitos previos

PHP 8.3 o posterior, tal como exige Laravel 13, con la extensión pdo_pgsql. Ejecute php -m y compruebe que pdo_pgsql aparece en la lista.
Composer
Una cuenta de ClickHouse Cloud
psql, para crear la base de datos. También puede ejecutar la sentencia CREATE DATABASE en la consola SQL.

Crear un servicio de ClickHouse Managed Postgres

En la consola de ClickHouse Cloud, haga clic en New service y seleccione Postgres. La instancia estará lista en unos minutos. Consulte la guía de inicio rápido para ver el proceso paso a paso.

Obtén los detalles de conexión

Haz clic en Conectar en la barra lateral izquierda de tu servicio. El cuadro modal muestra tu nombre de usuario, contraseña, servidor y puerto, e incluye un toggle Directly / via PgBouncer. Una aplicación PHP no mantiene un grupo de conexiones entre solicitudes. De forma predeterminada, cada solicitud abre una nueva conexión a Postgres y la cierra al finalizar. En esta guía, la aplicación se conecta a través del PgBouncer integrado en el puerto 6432, de modo que esas conexiones de corta duración compartan un pequeño conjunto de procesos backend de Postgres. Las migraciones se conectan directamente a Postgres en el puerto 5432, ya que ejecutan DDL y pueden mantener transacciones largas. Selecciona via PgBouncer para ver los detalles de la conexión agrupada. El puerto cambia a 6432 y las cadenas de conexión incluyen sslmode=verify-full. En el mismo cuadro modal, haz clic en Download CA certificate. También puedes descargarlo desde Settings → CA Certificate. El certificado es exclusivo de tu instancia, lo que permite al controlador verificar que se está comunicando con tu servidor.

Configurar el proyecto

Cree un proyecto de Laravel:

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

¿Va a añadirlo a una aplicación existente?Omita composer create-project. En su proyecto, compruebe que php -m incluye pdo_pgsql; después, siga el resto de esta sección y continúe con Configurar la conexión, donde la aplicación pasa de SQLite a Postgres. Luego, php artisan migrate crea sus tablas existentes en Postgres, pero no copia los datos de SQLite.

Mueva el certificado de CA que descargó al directorio del proyecto y cámbiele el nombre a ca-certificate.pem. Cree una base de datos para la aplicación. Sustituya <PASSWORD> y el host por los valores del modal Conectar:

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

Configurar la conexión

Laravel usa SQLite de forma predeterminada. Abra .env y sustituya la línea DB_CONNECTION=sqlite y las líneas DB_ comentadas que aparecen debajo por lo siguiente:

.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 la ruta absoluta a ca-certificate.pem. libpq resuelve las rutas relativas respecto al directorio de trabajo del proceso PHP, que depende de cómo PHP ejecute su aplicación. Si su contraseña contiene espacios o #, escríbala entre comillas dobles. No incluya .env en el control de versiones. La conexión pgsql predeterminada de config/database.php lee DB_SSLMODE, pero no la ruta del certificado de la CA. Abra config/database.php y agregue las entradas sslrootcert y options a la conexión 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,
            ],
        ],

Laravel añade sslmode y sslrootcert al DSN de PDO, y la extensión pdo_pgsql los pasa a libpq, que verifica la cadena de certificados y el nombre del host. PDO::ATTR_EMULATE_PREPARES hace que PDO envíe cada consulta con sus valores ya vinculados, en lugar de crear una sentencia preparada del lado del servidor. Actívelo cuando se conecte a través de PgBouncer. Si pdo_pgsql está compilado con libpq 16 o anterior, como ocurre en Debian 12, PHP libera cada sentencia preparada mediante una sentencia SQL DEALLOCATE. PgBouncer cambia el nombre de las sentencias preparadas en el servidor, por lo que DEALLOCATE falla. Si esto ocurre dentro de una transacción, la transacción se aborta y la siguiente consulta falla con current transaction is aborted. Con libpq 17 o posterior, la configuración predeterminada también funciona. Ejecute php -i | grep libpq para comprobar su versión. Compruebe la conexión:

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  

Sin la línea sslrootcert, verify-full falla con el error root certificate file ".../.postgresql/root.crt" does not exist, porque libpq recurre a la ubicación predeterminada de su CA. Si la CA es incorrecta, la conexión falla con SSL error: certificate verify failed.

Crear un modelo y una migración

Genere un modelo de Eloquent y una migración para una tabla tasks:

php artisan make:model Task -m

Abra la nueva migración en database/migrations/ (su nombre termina en _create_tasks_table.php) y añada las columnas title y done al 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();
        });
    }

Reemplace app/Models/Task.php para que las columnas admitan asignación masiva y done se devuelva como boolean:

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',
        ];
    }
}

Ejecute las migraciones a través de la conexión directa. Las variables de entorno sobrescriben los valores de .env, así que solo necesita cambiar el puerto:

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

Además de tasks, esto crea las tablas users, sessions, cache y jobs que una aplicación nueva de Laravel utiliza de forma predeterminada. Laravel registra las migraciones aplicadas en la tabla migrations y, en ejecuciones posteriores, solo aplica las nuevas.

Consultar la base de datos

Agregue algunas filas con Eloquent desde 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();"

Añada al final de routes/web.php una ruta que devuelva todas las tareas en formato JSON:

routes/web.php

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

Laravel aplica las opciones de conexión search_path, timezone e isolation_level mediante sentencias SET a nivel de sesión al conectarse, y estas no se conservan entre transacciones cuando se pasa por PgBouncer. Deje estas opciones con sus valores predeterminados o, si las necesita, conéctese directamente al puerto 5432. Las funcionalidades a nivel de sesión, como LISTEN y los bloqueos consultivos de sesión, tampoco funcionan a través de PgBouncer. Consulte las preguntas frecuentes.

Ejecutar y verificar

Inicie el servidor de desarrollo:

php artisan serve --port=3104

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

  Press Ctrl+C to stop the server

Abre http://localhost:3104/tasks en tu navegador. La respuesta será similar a la siguiente:

[
  {
    "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 los datos en la consola, abra consola SQL en la barra lateral izquierda de su servicio, expanda guide_laravel y, a continuación, public, y haga clic en la tabla tasks. El esquema public también incluye las tablas predeterminadas de Laravel, como users, sessions y 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 pasos

Conexión: cadenas de conexión, PgBouncer y TLS
Configuración: parámetros de Postgres y PgBouncer, como max_connections
Réplicas de lectura: dirija las lecturas a una réplica mediante las conexiones de lectura y escritura de Laravel
Seguridad: listas de acceso por IP y redes privadas

Primeros pasos

Funcionalidades

Guías

Precios

Integración con ClickHouse

Migraciones

Monitorización

Preguntas frecuentes

Usar Laravel con ClickHouse Managed Postgres

Requisitos previos

Crear un servicio de ClickHouse Managed Postgres

Obtén los detalles de conexión

Configurar el proyecto

Configurar la conexión

Crear un modelo y una migración

Consultar la base de datos

Ejecutar y verificar

Próximos pasos

​Requisitos previos

​Crear un servicio de ClickHouse Managed Postgres

​Obtén los detalles de conexión

​Configurar el proyecto

​Configurar la conexión

​Crear un modelo y una migración

​Consultar la base de datos

​Ejecutar y verificar

​Próximos pasos

Requisitos previos

Crear un servicio de ClickHouse Managed Postgres

Obtén los detalles de conexión

Configurar el proyecto

Configurar la conexión

Crear un modelo y una migración

Consultar la base de datos

Ejecutar y verificar

Próximos pasos