Sail: databases & Docker services

This guide focuses on services next to laravel.test: SQL engines, Redis, optional RabbitMQ, MongoDB, and dev-friendly extras. It complements the full Sail guide. For queue worker commands see Queues & workers; for .env layout and servers see Environments & deployment.

Navigation: All tools Ā· Sail overview Ā· Queues Ā· Env & deploy Ā· Troubleshooting

Table of contents

Network and hostname rules

All app-side hosts in .env must be Compose service names (pgsql, redis, mongo), not 127.0.0.1, because PHP runs inside laravel.test. From your host machine you reach DB via 127.0.0.1:${FORWARD_DB_PORT} when ports are forwarded.

Redis service (full example)

Add to docker-compose.yml (adjust names to match your published Sail file):

redis:
    image: 'redis:alpine'
    ports:
        - '${FORWARD_REDIS_PORT:-6379}:6379'
    volumes:
        - 'sail-redis:/data'
    networks:
        - sail
    healthcheck:
        test: ["CMD", "redis-cli", "ping"]
        retries: 3
        timeout: 5s

Register sail-redis under top-level volumes:. On laravel.test add:

depends_on:
    redis:
        condition: service_healthy

(If your Compose version does not support condition, use plain depends_on: [redis].)

.env:

REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

Verify: sail exec redis redis-cli ping.

Replace MySQL with PostgreSQL

  1. Remove (or comment) the mysql service and its volume.
  2. Add pgsql from a fresh Sail stub (php artisan sail:install --with=pgsql in a throwaway project) or from laravel/sail stubs/pgsql.stub for your version.
  3. Point laravel.test depends_on at pgsql.
  4. .env:
DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password
  1. Rebuild if the PHP image changes: sail build --no-cache && sail up -d.
  2. Fresh DB: sail artisan migrate:fresh (destroys local data unless you dump/restore).

MongoDB + PHP extension in Sail

1. Compose service (minimal):

mongo:
    image: 'mongo:7'
    ports:
        - '${FORWARD_MONGO_PORT:-27017}:27017'
    volumes:
        - 'sail-mongo:/data/db'
    networks:
        - sail

  1. Add sail-mongo to volumes:.

  2. Laravel typically uses mongodb/laravel-mongodb. The PHP mongodb extension must exist in laravel.test. After sail:publish, edit the runtime Dockerfile (e.g. docker/8.3/Dockerfile):

RUN pecl install mongodb \
    && docker-php-ext-enable mongodb

  1. Rebuild: sail build --no-cache.

  2. Configure the package with host mongo and port 27017 from inside the app container.

RabbitMQ as a container

Use when you adopt an AMQP queue driver package (not core Laravel):

rabbitmq:
    image: 'rabbitmq:3-management-alpine'
    hostname: rabbitmq
    ports:
        - '${FORWARD_RABBITMQ_PORT:-5672}:5672'
        - '${FORWARD_RABBITMQ_MANAGEMENT:-15672}:15672'
    volumes:
        - 'sail-rabbitmq:/var/lib/rabbitmq'
    networks:
        - sail
    environment:
        RABBITMQ_DEFAULT_USER: '${RABBITMQ_USER:-sail}'
        RABBITMQ_DEFAULT_PASS: '${RABBITMQ_PASSWORD:-password}'

Declare volume sail-rabbitmq. Set .env keys expected by your queue package (RABBITMQ_HOST=rabbitmq, etc.). Management UI: http://localhost:15672 (default guest/guest disabled when you set default user aboveā€”use sail/password from the example).

Mailpit (SMTP dev)

Sail often includes Mailpit. Point Laravel mail to the mailpit host and the SMTP port from docker-compose.yml (commonly 1025 inside the network, forwarded on host). Read messages in the HTTP UI on the forwarded web portā€”no real mail leaves the machine.

Meilisearch / Typesense (optional search)

Install-time flag example:

php artisan sail:install --with=meilisearch

Or paste the upstream Meilisearch / Typesense service block from Sail stubs. Set SCOUT_DRIVER / MEILISEARCH_HOST (or equivalent) to the service name and internal port.

Healthchecks and startup order

depends_on alone does not wait for DB readiness. Prefer healthcheck on mysql/pgsql/redis and condition: service_healthy where Compose supports it so php artisan migrate in entry scripts fails less often.

Named volumes and data reset

  • Named volumes persist across sail down.
  • sail down -v deletes those volumesā€”all local DB data gone.
  • For a clean slate without nuking other projects, use docker volume rm on the specific volume name printed by docker volume ls.

See also

ā† All tools