Databases & services

Beyond serving PHP sites, Butler manages the backing services your projects need — databases, caches, a mail catcher, search and object storage. A fresh install ships none of these; you add exactly the ones you want.

Components vs. services

Butler draws a small but useful distinction:

• A component is an installed binary — for example the MySQL engine or the Redis server. Installing a component downloads and verifies the binary but doesn’t run anything.
• A service is a running instance of a component — an actual MySQL server listening on a port, with its own data directory. You can run more than one instance of the same component (say, two MySQL versions) as separate services.

The menu bar app mirrors this: a Components section for what’s installed and a Services section for what’s running.

Install a component

butler install mysql
butler install redis
butler install mailpit

See what you have installed:

butler components

Butler’s catalog includes databases (MySQL, PostgreSQL, MariaDB, MongoDB), caches (Redis, Valkey), mail (Mailpit), search (Typesense) and S3-compatible storage — installed on demand as verified static binaries.

Manage a running service

Once a component is installed, manage instances of it with butler service:

butler service add mysql          # create + start an instance (on a unix socket)
butler service add mysql --tcp    # …or listen on 127.0.0.1:3306 instead
butler service status mysql
butler service stop mysql
butler service restart mysql

By default an instance listens on a unix socket; pass --tcp (or --port) to bind a loopback TCP port instead. See Connecting to databases for the details.

For everyday start/stop across everything, the top-level commands are quickest:

butler start            # start Butler's services
butler stop             # stop them
butler restart mysql    # restart one by name

Run butler start with no arguments in a terminal and it confirms before starting everything.

Databases

Install a database engine, add a service instance, and connect your app to it on 127.0.0.1 with the default port for that engine — see Connecting to databases for the exact hosts, ports and credentials. You can also have Butler create a database and wire it up when you link a project — set it in the project’s butler.yml:

database:
  type: mysql
  name: my_app_local
  createOnLink: true

Mail

Install Mailpit to catch outgoing mail locally. Point your app’s SMTP settings at Mailpit’s local port and every message your app sends lands in Mailpit’s inbox instead of a real recipient — ideal for testing password resets, receipts and the like.

Logs

Every service writes to a log you can tail:

butler log mysql

The app’s Logs section shows the same output live for any process.

Remove what you don’t need

butler service remove mysql     # remove a running instance
butler component remove mysql   # remove the installed binary

Butler guards against removing a component that a service still depends on, so you won’t accidentally pull the binary out from under a running instance.