CLI · Winter Console

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.

Subcommands ping · migrate · sql · poolSchema from #[Migratable] configsRequires flytachi/winter-ppa

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.

text
 | [=================================== 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
bash
php call db ping
php call db sql        # preview
php call db migrate    # execute

Phase 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
bash
php call db migrate          # every phase
php call db migrate -t -i     # tables + indexes only

Scope (plugins)

Option Scope
(none) The application (Project)
--plugin=<name> One plugin
--plugins Every plugin
bash
php call db migrate --plugin=acme/billing
php call db sql --plugin=acme/billing -s

ping 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] (pgsql 42P06/42P07/42710, mysql 42S01 and driver code 1061 for indexes). An existing constraint on MySQL and any repeat on SQLite are not recognised this way and give [FAILED] — details in Migrations.
  • With DEBUG=true the 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

bash
php call db pool
text
 | [==================== 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=2s

Every 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