Connecting to databases

Once you’ve installed a database and started a service (see Databases & services), your app connects to it on local development with permissive local auth, so there’s nothing to configure before you connect.

Instances default to a unix socket

butler service add <db> creates the instance on a unix socket, not a TCP port — nothing is listening on 127.0.0.1:<port> until you ask for TCP. To get the loopback host/port in the table below, add the instance with --tcp (or --port):

butler service add mysql --tcp          # listen on 127.0.0.1:3306
butler service add mysql --port 3307    # a second instance on a chosen TCP port

Prefer the socket? Point your app at the socket path Butler shows for the instance (DB_SOCKET for MySQL/PostgreSQL) instead of a host and port — see Unix sockets below.

Default connection details (TCP mode)

For an instance added with --tcp, connect on 127.0.0.1 with these defaults:

Service	Host	Port	Username	Password
MySQL	127.0.0.1	3306	root	(empty)
MariaDB	127.0.0.1	3307	root	(empty)
PostgreSQL	127.0.0.1	5432	postgres	(empty)
Redis	127.0.0.1	6379	—	(none)
Valkey	127.0.0.1	6380	—	(none)
MongoDB	127.0.0.1	27017	—	(none)
Mailpit (SMTP)	127.0.0.1	1025	—	(none)
Mailpit (web inbox)	127.0.0.1	8025	—	—
Typesense	127.0.0.1	8108	API key	butler

Ports are per instance

These are the defaults for the first instance of each service. If you run a second instance of the same type, Butler assigns it a different port — check the Services section of the app or butler status for the exact port an instance is listening on.

Wiring it into a Laravel app

A typical Laravel .env against Butler’s MySQL:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_app_local
DB_USERNAME=root
DB_PASSWORD=

For PostgreSQL, use DB_CONNECTION=pgsql, port 5432, and username postgres.

Catch outgoing mail with Mailpit:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

Every message your app sends then shows up in Mailpit’s web inbox at http://127.0.0.1:8025 instead of going to a real recipient.

Point Redis at the cache/queue:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Have Butler create the database on link

Instead of creating a database by hand, let Butler create and wire one up when you link the project. Add it to the project’s butler.yml:

database:
  type: mysql
  name: my_app_local
  createOnLink: true

On butler link, Butler creates my_app_local (if it doesn’t exist) so your app connects straight away.

Open a database in a GUI

If you use the app, the Sites section can open a linked site’s database directly in a GUI such as TablePlus — Butler reads the credentials from the project’s .env and hands them off, so you don’t retype host, port and password. From the Services section you can also open or copy a connection string for a running database instance.

Unix sockets

For lower-overhead local connections, a service can run in unix-socket mode instead of TCP. When it does, point your app at the socket path (Butler shows it in the service’s connection details) rather than a host and port — for MySQL and PostgreSQL that’s DB_SOCKET, and for Redis, Butler rewrites the host/port to the socket automatically in copied .env snippets.