The db command
db manages database connections and schema generation: ping checks the
connections, migrate creates the tables from entity attributes, sql shows the
generated DDL without running it.
The command lives on the winter-ppa package
The database layer is not part of the kernel — it is installed separately. Without it
db does not work at all, ping included: every subcommand answers and refuses.
| [=================================== Db ===================================]
| [!] The 'db' command needs the database layer, which is not installed.
| [i] Add it with: composer require flytachi/winter-ppa
| [=================================== Db ===================================]The refusal is total rather than partial, deliberately. If half the subcommands worked, the conclusion would be “the command is broken”, and the search would start in the wrong place. Nothing working, with a reason given, reads as “a package is missing” — which is the truth.
call db --help still prints without the package: the help page is where you learn what
the command is and why the dependency is worth installing. It shows a Requires line
always, and warns on top of it when the package is absent.
What db is and why
db is the console interface to the project’s database.
The problem. You need to check that the application can reach the database, and to bring the schema up on a new machine. Doing that with external utilities and by hand is extra steps.
The solution. db gives you a connectivity check and schema generation straight
from the project’s code — across every configured connection. That is what this page
is about.
Subcommands
| Subcommand | Purpose |
|---|---|
ping |
Connect to every configuration; show the driver, the DSN, the latency and the status |
migrate |
Run the DDL (grouped by type) |
sql |
Print the DDL to stdout without running it (a preview) |
pool |
Show the running server’s connection-pool load |
php call db ping
php call db sql # preview
php call db migrate # executePhase flags (migrate and sql)
They pick which parts of the schema to generate. Without flags — all five:
| Flag | Phase | Note |
|---|---|---|
-e |
Extensions | pgsql only |
-s |
Schemes | pgsql only |
-t |
Tables | — |
-i |
Indexes | — |
-c |
Constraints | FK, CHECK |
php call db migrate # every phase
php call db migrate -t -i # tables + indexes onlyScope (plugins)
| Option | Scope |
|---|---|
| (none) | The application (Project) |
--plugin=<name> |
One plugin |
--plugins |
Every plugin |
php call db migrate --plugin=acme/billing
php call db sql --plugin=acme/billing -sping always pings everything
The --plugin / --plugins options apply to migrate and sql only. db ping
always checks the application and every plugin, ignoring those options.
Migration behaviour
- Only
#[Migratable]configurations run, in priority order High → Normal → Low. - Rerun: only extensions use
IF NOT EXISTS; for everything else an “object already exists” error becomes[EXIST]rather than[FAILED](pgsql42P06/42P07/42710, mysql42S01and driver code1061for indexes). An existing constraint on MySQL and any repeat on SQLite are not recognised this way and give[FAILED]— details in Migrations. - With
DEBUG=truethe SQL error text is shown for a[FAILED].
The full schema-generation rules, the opt-in and the limitations are on the Migrations page.
db pool — pool load
php call db pool | [==================== Connection pools — web workers ====================]
| [ Main\MainDbConfig ]
| active 12
| idle 3
| total 15
| maximum 20
| workers 2
| saturated 1 of 2 workers
| Main\MainDbConfig ........................................... [SATURATED]
| [===================== Connection pools — processes =====================]
| [ Main\MainDbConfig ]
| active 4
| idle 2
| total 6
| maximum 10
| processes 2
| Main\MainDbConfig ........................................... [OK]
| open connections per config
| Main\MainDbConfig 21 (web 15 + processes 6)
| per source
| worker#0 Main\MainDbConfig active=2 idle=3 total=5 max=10 pid=4101 age=0s
| worker#1 Main\MainDbConfig active=10 idle=0 total=10 max=10 pid=4102 age=3s
| process Main\Process\ReportProcess Main\MainDbConfig active=1 idle=1 total=2 max=5 pid=4120 age=1s
| daemon Main\Daemon\Emails.0 Main\MainDbConfig active=3 idle=1 total=4 max=5 pid=4131 age=2sEvery OS process has a pool: every web worker, every process and
every daemon worker. So the output is split into groups — web
workers and processes — and ends with a line per source, with its pid. Each group shows,
per config, the summed active, idle, total, maximum, the number of sources
(workers or processes) and a badge: [OK], or [SATURATED] when at least one source’s
pool is fully taken (the saturated line says how many).
What to look at is the source lines, not the overall total: a request waits for a free
connection in its own process’s pool, so one saturated worker or process means real
latency even when there is enough room in aggregate. The “open connections per config” line
is how many connections the application holds open per config; hold it against the
database’s own max_connections (configs pointing at one server add up).
The data comes from the running server
The console is a separate process and cannot peer into the server’s memory, so the
workers and processes publish their statistics on a timer themselves
(PPA_POOL_TELEMETRY, 5 seconds by default). A process that stops removes its record at
once.
If the server is not running, or has never opened a connection, the command says plainly that there is no telemetry. In detail — how the pool works.
Next
- Migrations — how entities turn into a schema
- Database connection —
DbConfigclasses,#[Migratable] - Console — overview