## TL;DR
Metasploit's database is a local PostgreSQL instance it does not always start itself, especially after reboots, package updates, or when running under a different user. Check the service, start it, verify the connection configuration msfconsole is using, and reinitialise only if the database itself is damaged, since session and host data live there.

```text
msfconsole "failed to connect to the database" on tester box
```

## Use this when
- msfconsole starts with a failed to connect to the database message or shows the database as disconnected in its status.
- Search and workspace features complain the database is offline on the tester box.

## Not for this skill when
- The database connects and the problem is slow module search. That is a cache rebuild, not a connection fix.
- You deliberately run without a database for a one-off check. The warning is then expected and harmless.

## Steps
1. Run the status check msfconsole offers, and note whether it names a database, a host, and an error, then exit cleanly. Verify: Verify: you have the exact connection target msfconsole is trying to use.
2. Check the PostgreSQL service state at the OS level and start it if it is stopped, which is the common case after a reboot on Kali and similar builds. Verify: Verify: the service reports running.
3. Start msfconsole again and check database status; if it connects, confirm your workspace and a few known hosts are present. Verify: Verify: status shows connected and prior engagement data is visible.
4. If it still fails, inspect the database connection configuration file Metasploit uses for a wrong user, socket path, or a configuration left by another user account. Verify: Verify: the configuration matches the local instance and the account you run msfconsole as.
5. As a last resort, use the Metasploit database reinitialisation command, understanding it creates a fresh empty database, and export anything precious first if the old one can be reached at all. Verify: Verify: the reinitialised database connects and you have consciously accepted the data reset.

## Variant phrasings
### msfdb init start postgresql metasploit kali
The service phrasing on Kali-style installs.
### metasploit db_status not connected after reboot
The reboot phrasing.
### msfconsole database config wrong user socket
The configuration phrasing.

Compatibility: Compatibility: Metasploit Framework 6.x with its bundled PostgreSQL setup; service names differ between Kali, Ubuntu packages, and the official installer.

## Why it happens
The framework treats the database as an external service: it stores hosts, services, loot, and workspaces there, but process supervision belongs to the OS. Anything that stops PostgreSQL, changes its socket, or switches the running user breaks the connection while msfconsole itself stays healthy, which is why the fix lives at the service and configuration layer.

## Edge cases / pitfalls
- Reinitialising the database destroys stored engagement data; it is the last step, never the first.
- Running msfconsole under sudo sometimes connects to a different user's database and looks like data loss; check the account before panicking.
- Keep engagement data handling in mind: the database contains client host data and belongs in the same backup and wipe routine as project files.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2BoWZMmcQL9mSgdhsEYw7Q