Configurar PostgreSQL en Laravel con Docker (incluyendo pgvector)

Si estás montando un proyecto Laravel y quieres una base de datos PostgreSQL aislada con Docker, esta configuración te deja todo listo en pocos pasos.

¿Qué vas a tener al final?

Laravel conectado a PostgreSQL por DB_CONNECTION=pgsql
Contenedor Docker con la imagen pgvector/pgvector:pg16
Script de inicialización que:
- Habilita la extensión vector
- Crea la base de datos

1. Variables de entorno en Laravel

.env

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=tu_base_de_datos
DB_USERNAME=laravel
DB_PASSWORD=secret

2. Definir el servicio PostgreSQL en Docker Compose

docker-compose.yml

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: ${DB_DATABASE}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    ports:
      - "${DB_PORT}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U ${DB_USERNAME} -d ${DB_DATABASE}" ]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

3. Script de inicialización de PostgreSQL

docker/postgres/init.sql

-- Habilitar extensión pgvector
CREATE EXTENSION IF NOT EXISTS vector;

-- Crear base de datos de tests
CREATE DATABASE tu_base_de_datos_test;

-- Verificar que la extensión está instalada
SELECT * FROM pg_extension WHERE extname = 'vector';

5. Conectar Laravel y correr migraciones

php artisan migrate

6. Pruebas automatizadas con base de datos separada

Para que las pruebas pasen con postgres actualiza el archivo phpunit.xml actualizando los valores a:

<env name="DB_CONNECTION" value="pgsql"/>
<env name="DB_DATABASE" value="tu_base_de_datos_test"/>