Contao Database Commands Bundle Laravel Package

Getting Started

This bundle is a thin set of Symfony Console commands for Contao that let you do two things from the terminal instead of the install tool UI: run the Contao database schema update, and create an admin user. It exists to make fresh environments (CI, Docker, staging) bootstrappable without clicking through contao/install.

As of 0.2.4 (the current release) the package widened its symfony/console constraint to allow v4, specifically to cover Contao 4.6. That is the only change in this release — no new commands, no renamed commands, no API changes. It is a compatibility bump, not a feature release, so anything you built against 0.2.x continues to work, and the assessment below is unchanged in substance. What it does tell you is the maintenance model: the author bumps constraints per Contao minor, so the version of this bundle you install is coupled to the Contao version you run.

Minimal setup:

composer require fuzzyma/contao-database-commands-bundle:^0.2.4

Pin explicitly. Do not float on * — a future constraint bump could pull a Symfony major you are not on.

Then register the bundle the way your Contao version expects. On Contao 4.4–4.8 that means adding it to app/AppKernel.php:

// app/AppKernel.php
$bundles[] = new Fuzzyma\ContaoDatabaseCommandsBundle\ContaoDatabaseCommandsBundle();

On Contao 4.9+ with the Contao Manager / bundle auto-registration, confirm it actually appears in config/bundles.php before assuming it is active.

First thing to do after install is discover the exact command names, because they are the whole package:

bin/console list --raw | grep -i contao
bin/console list --raw | grep -i admin
bin/console help <command-name>

Do not trust blog posts or the README alone for command names — the original release is from 2018 and the naming may differ from what you expect (contao:database:update vs contao:update vs something namespaced differently). Verify against your installed version.

The first real use case is a deploy-like script:

bin/console cache:clear --env=prod
bin/console <database-update-command> --env=prod --no-interaction
bin/console <admin-create-command> --env=prod --no-interaction

That sequence turns a blank database plus an empty var/ into a working Contao install with a login. Everything else in this assessment builds on that.

Implementation Patterns

Docker entrypoint / first-boot bootstrap. The most common pattern for this bundle is an entrypoint that waits for the database, clears cache, runs the schema update, and creates the admin only if no admin exists:

#!/bin/sh
set -e
until bin/console doctrine:query:sql "SELECT 1" >/dev/null 2>&1; do sleep 2; done
bin/console cache:clear --env=prod --no-warmup
bin/console cache:warmup --env=prod
bin/console <database-update-command> --env=prod --no-interaction
if ! bin/console <list-admins-or-check-command> ... ; then
  bin/console <admin-create-command> --env=prod --no-interaction
fi
exec "$@"

The guard matters: admin creation is typically not idempotent, and a container restart should not fail because the user already exists.

Separate the two concerns into two pipeline steps. Schema updates should run on every deploy; admin creation should run once per environment. Mixing them means a routine deploy re-attempts user creation and can fail an otherwise healthy release. Put admin creation in a one-shot init job, a make init target, or a Terraform/Ansible create step, and leave the DB update in the normal deploy.

Wrap the commands in your own command or Make target. Because this bundle is effectively unmaintained (last release 2018-era, zero dependents) and now version-coupled to Contao minors, treat it as a swappable implementation detail:

db-update:
	bin/console <database-update-command> --env=$(ENV) --no-interaction

admin:
	bin/console <admin-create-command> --env=$(ENV) --no-interaction

If you later move to Contao core equivalents, you change one line per target instead of hunting through CI configs.

Environment parity. Run the exact same target in dev, staging, and prod so that a schema drift in staging is caught before it hits prod. The install-tool path encourages clicking through steps in a browser and silently skipping them in automation; the CLI path forces the steps to be scripted and therefore reproducible.

Pair with core commands where they exist. On newer Contao the core already ships contao:migrate and user-creation commands. The pragmatic pattern is: detect which commands exist at bootstrap and prefer core, falling back to this bundle only on older installs:

if bin/console list --raw | grep -q 'contao:migrate'; then
  bin/console contao:migrate --no-interaction
else
  bin/console <bundle-update-command> --no-interaction
fi

That keeps one deployment script working across a fleet of sites on different Contao minor versions — which is realistically why you would keep this bundle around at all.

CI integration. In CI the value is being able to spin up a database, apply the schema, seed an admin, and run functional tests (login, backend smoke test) in one job. The command must run non-interactively or the job hangs on a prompt; verify --no-interaction and -n are honored by every command you call before wiring it into CI.

Match bundle version to Contao minor in multi-site fleets. 0.2.4 exists solely because Contao 4.6 needed symfony/console v4. If you operate several sites on different Contao minors, install the bundle version that matches each site rather than a single floating constraint, and record the pairing in your upgrade notes. This is a case where composer.lock discipline across the fleet is cheaper than debugging a constraint conflict during a hotfix.

Gotchas and Tips

Check whether you need this at all before adding it. The package's opportunity score is low and it has no dependents; Contao core has absorbed this functionality in later 4.x releases. If you are on a supported Contao version, run bin/console list first — you may already have the commands and be about to add a dependency you will remove in a month.

Version constraints are the real trap — and 0.2.4 is the proof. This release only widened symfony/console to allow v4 for Contao 4.6. That means the ceiling is still Symfony 4: there is no Symfony 5/6 support, and nothing here addresses PHP 8.x. Installing on a modern stack will either fail to resolve or resolve into an untested combination. Check composer why-not and the package's composer.json for the exact constraint range before committing; if you must use it beyond Symfony 4, expect to fork and patch the constraints yourself. Also note the release cadence — roughly one constraint bump per Contao minor — so if you upgrade Contao you should expect to need a matching bundle release, and that release may never come.

Command names are not guaranteed across versions. Always discover with bin/console list --raw and bin/console help <name> on the actual installed version rather than copying a command name from the README of an old release. A wrong command name is the most common cause of "the bundle does nothing" — the bundle is fine, the script calls something that does not exist.

Cache warmup order. Contao's console commands depend on a compiled container and on DCA metadata being readable. Run cache:clear before the DB update and cache:warmup (or a plain first command) after, and be aware that a stale cache after a schema change can produce confusing "column does not exist" errors that have nothing to do with the update itself.

Permissions and user context. Running these commands as root in a container leaves var/cache and var/logs owned by root, and the web server then cannot write to them — a classic "works in the entrypoint, 500s in the browser" failure. Run as the same user the PHP-FPM/web process uses, or chown -R afterward.

Database credentials must reach the console process. Contao reads DB config from parameters.yml/config/parameters.yml or environment variables depending on version. In Docker, make sure the environment variables are exported to the entrypoint process, not just to the web container, or the command connects to the wrong database (or localhost) and silently updates nothing while still exiting zero in some configurations. Add an explicit connectivity check (doctrine:query:sql "SELECT 1") before the update.

Interactive prompts will hang CI. Password entry and confirmation prompts are the default risk here. If a command does not support --no-interaction cleanly for a given field, that is a hard blocker for automation and a reason to drop the bundle in favor of core commands or a small custom Symfony command that calls the same services directly.

Admin creation is usually not idempotent. Plan for "user already exists" as an expected outcome, not an error: check first, or tolerate and continue. Also watch password length and username validation rules — Contao enforces a minimum password length, and a short value in a seed script fails only on fresh installs, which is exactly when you are least likely to be watching.

The install tool and its lock file. If the environment was ever touched by contao/install, a lock file or install.php may block the CLI path or cause the schema to be considered "not installed." Remove the install entry point and lock file as part of the image build or init step, and do it explicitly rather than relying on the bundle to work around it.

Extension point. The clean way to depend on this without being trapped by it is a trivial custom command in your own app that delegates to whichever implementation is available (core contao:migrate or this bundle). You get a stable command name in your pipelines and a one-file swap when you upgrade Contao — and you sidestep the whole "which 0.2.x matches my Contao minor" question entirely.