Services & database

Backend projects include a local database and development services. Find access details, the normal backup workflow and the limits of data persistence here.

Which services are available?

Use these services for local application data, captured email and database administration. They require an active backend role; frontend-only projects do not have this database or these services.

MariaDB is part of every backend runtime, not an optional service toggle.
Mailpit and phpMyAdmin are enabled by default in new backend projects.
Elasticsearch and Mercure are optional services and disabled by default. Enable them only when your application needs them.

MariaDB: The application inside the stack reaches the database at mariadb:3306.
Mailpit: Captures local email. Its browser inbox is at a URL such as http://tools.my-project.localhost/mp/; SMTP inside the stack is mailpit:1025.
phpMyAdmin: Browser access to the database, at a URL such as http://tools.my-project.localhost/pma/. Sign in with the project credentials printed by access phpmyadmin.
Elasticsearch: Optional internal search service at elasticsearch:9200.
Mercure: Optional hub at /.well-known/mercure on backend runtime project hosts. The application manages publication tokens; anonymous subscriptions are permitted in the local container.

Manage services

Work in the project directory. services list shows configured optional services, not their reachability. If Mailpit was disabled, you can enable it again as follows:

Inspect service settingsbash

dwell services list

Enable Mailpit and start the projectbash

dwell services enable mailpit
dwell up

To disable it, use dwell services disable mailpit. Changes synchronize local state and can restart active services. up starts a previously stopped project.

Use access details

Start the environment with dwell up. The following queries show configured access details; use the actual printed URL including any gateway port.

Inspect project database credentialsbash

dwell access db

Inspect phpMyAdmin address and loginbash

dwell access phpmyadmin

Inspect Mailpit addressbash

dwell access mailpit

The general dwell access overview hides passwords. Explicit db and phpmyadmin queries show the project user and password; treat their output as confidential, including JSON. The MariaDB root password is never printed. Disabled tools have no usable access entry.

mariadb is an internal stack host. Dwell publishes no database port on your machine; the credentials therefore do not automatically work in a desktop client at localhost:3306. Use phpMyAdmin for normal browser access. Access does not check whether a service is running.

Export and import data

Export saves the current project database to an SQL file. Choose a new filename for each backup: db export does not overwrite existing files. The following example writes relative to the project directory.

Save the database as SQLbash

dwell db export backups/before-update.sql

Without a filename, dwell db export writes to .dwell/backups/[data-namespace]-db.sql. The CLI prints the concrete destination. For repeated backups, use new export filenames or named snapshots.

Import replaces the current project database from an SQL file. Check its source and contents and back up important data before confirming. This example uses the file exported above:

Import an SQL filebash

dwell db import backups/before-update.sql

Dwell requires confirmation and creates a safety snapshot first. On failure, it attempts to restore the previous data from that snapshot. Read the result; if recovery fails, keep the reported snapshot for manual recovery. A safety snapshot does not replace a separate backup.

Take a snapshot before changes

A snapshot is a named SQL backup in .dwell/backups/. Create one before an update or a risky data change. Use new names for further snapshots; duplicate names are rejected.

Save the state before an updatebash

dwell db snapshot before-update

If you later want to return to that state, use restore. It replaces the current project database after confirmation and also creates a safety snapshot first.

Restore a named snapshotbash

dwell db restore before-update

Keep Dwell backups with their companion files and the associated persistent project state. Modified or incomplete backups may be rejected; the technical reference covers exact integrity and restore rules.

Persistence, runtime and backups

down stops the environment without deleting project files or persistent Docker volumes. Database data lives in the volume; captured Mailpit messages remain in persistent project state.

Persistent data: Database volumes, local secrets, Mailpit files and backups must be preserved deliberately and backed up separately when needed.
Runtime: .dwell/runtime/ contains generated files, process state and logs. It is refreshed and is not a data backup.
Backup: SQL exports and snapshots save database contents. They do not replace backups of project files, uploads or all other service data. Keep important backups outside the project directory too.

Notes & limits

Database commands require Docker and a working backend runtime. They can start a stopped MariaDB temporarily and stop it again afterwards if they started it. Import SQL only from trusted sources. Access queries do not create or repair secrets; restore the original secrets if credentials are missing. Deleting database volumes deletes the database they contain.

Next steps

Check the routing guide for application and tool addresses. The projects guide explains starting, inspecting and stopping the environment.

Check routing & access →Use your project every day →

Technical reference

Services, access and persistence ↗Complete service and database commands ↗Repository service configuration ↗