Type: database | Runner: Dashboard or Agent
Opens a PDO connection to a database server and verifies it accepts connections. Supports MySQL, PostgreSQL, and SQLite via standard PDO DSN strings.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
dsn |
text | Yes | — | PDO Data Source Name. See examples below. |
username |
text | No | — | Database username. Leave empty for SQLite. |
password |
password | No | — | Database password. Use a dedicated read-only monitoring user. |
timeout |
number | No | 5 |
Connection timeout in seconds (1–30). Default: 5. |
DSN examples:
mysql:host=localhost;dbname=app
mysql:host=db.internal;port=3306;dbname=myapp
pgsql:host=localhost;dbname=app
pgsql:host=db.internal;port=5432;dbname=myapp
sqlite:/path/to/database.db
| Status | Condition |
|---|---|
| OK | PDO connection opened successfully — message: Connected to <dsn> |
| Fail | Connection failed (wrong credentials, host unreachable, database not found, timeout) |
| Unknown | No DSN configured |
Choose the runner based on where the database is reachable:
| Scenario | Runner |
|---|---|
| Database has a public or VPN-accessible port | Dashboard |
Database binds to 127.0.0.1 on the monitored server |
Agent |
| Database is inside a Docker network (container hostname as host) | Use Docker Exec instead |
For Docker-internal databases, PDO cannot resolve container names across Docker networks. Use Docker Exec with mysqladmin ping or pg_isready instead — no port exposure, no credential storage in watchdog.
GRANT SELECT ON *.* TO 'monitor'@'%' for MySQL).