RUEN
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
The 'db' command needs the database layer, which is not installed.
Add it with:  composer require flytachi/winter-ppa

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=bill
php call db sql --plugin=bill -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.
  • Idempotent: “object already exists” errors become [EXIST] rather than [FAILED] (pgsql 42P06/42P07/42710, mysql 42S01/42000).
  • 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
MainMainDbConfig
active 12 · idle 3 · total 15 · maximum 20 · workers 2
saturated  1 of 2 workers                    [SATURATED]
per worker
worker#0  MainMainDbConfig  active=2  idle=3 total=5  max=10  age=0s
worker#1  MainMainDbConfig  active=10 idle=0 total=10 max=10  age=3s

What to look at is the worker lines, not the overall total: a request waits for a free connection in its own worker’s pool, so one saturated worker means real latency even when there is enough room in aggregate.

The data comes from the running server

The console is a separate process and cannot peer into the server’s memory, so the workers publish their statistics on a timer themselves (PPA_POOL_TELEMETRY, 5 seconds by default).

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