In a Rails 8.1 app's generated `bin/docker-entrypoint`, when does `db:prepare` run, and why does it not run for `bin/rails console` or a `bin/jobs` container?
answer
- checks the command's last two arguments
- ./bin/rails then server
- bash -e stops on failure
- exec "${@}" hands over
- flags after server skip it
basics
~10 sThe entrypoint runs ./bin/rails db:prepare only when the command's last two arguments are exactly ./bin/rails and server, as in the default thrust CMD; a console, bin/jobs or a server with extra flags skips it.
solid answer
~40 sThe generated `bin/docker-entrypoint` is a `#!/bin/bash -e` script. It compares `"${@: -2:1}"` with `./bin/rails` and `"${@: -1:1}"` with `server`; the default `CMD ["./bin/thrust", "./bin/rails", "server"]` matches because only the last two arguments are checked. When they match, it runs `./bin/rails db:prepare`, which creates and loads the schema for a missing database or runs pending migrations on an existing one, then it hands the process over with `exec "${@}"`. `bin/rails console` ends in `console`, and a Kamal job role running `bin/jobs` ends in `bin/jobs`, so neither migrates. The string match is literal, so `bin/rails server` without `./` or `./bin/rails server -p 3000` also skips it. Because of `-e`, a failing `db:prepare` stops the script and the server never starts.
go deeper
Recall that the entrypoint prepares the database only when the container starts the Rails server, then hands over to the real command.
Explain the last-two-arguments check, why the thrust-wrapped CMD matches, what db:prepare does for a missing versus existing database, and the role of bash -e.
Discuss migrations at boot against health-check timeouts, concurrent hosts and advisory locks, backward-compatible schema changes, and commands that silently skip the step.
Decide whether migrations belong in container boot at all, or in a separate gated deploy step, given the team's database size and release cadence.
## The script as generated Rails 8.1 writes `bin/docker-entrypoint`, and the Dockerfile's final stage sets `ENTRYPOINT ["/rails/bin/docker-entrypoint"]`. Docker therefore runs the script with the `CMD` (or whatever command you pass to `docker run` or Kamal) as its arguments. When the app uses Active Record, the script is: ```bash #!/bin/bash -e # If running the rails server then create or migrate existing database if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then ./bin/rails db:prepare fi exec "${@}" ``` With `--skip-active-record` the `if` block is not generated and the script only `exec`s. ## Reading the condition - `"${@: -2:1}"` is bash for "the second-to-last argument", and `"${@: -1:1}"` is "the last argument". - The default command is `./bin/thrust ./bin/rails server`. Its last two arguments are `./bin/rails` and `server`, so the check passes even though Thruster is the first word. - The comparison is a **literal string match**. It does not parse options or normalise paths. | Command passed to the container | Last two args | `db:prepare` runs? | |---|---|---| | `./bin/thrust ./bin/rails server` (default) | `./bin/rails` `server` | Yes | | `./bin/rails server` (`--skip-thruster` default) | `./bin/rails` `server` | Yes | | `./bin/rails server -p 3000` | `-p` `3000` | No | | `bin/rails server` | `bin/rails` `server` | No, because of the missing `./` | | `./bin/rails console` | `./bin/rails` `console` | No | | `bin/jobs` (the commented `job` role in `deploy.yml`) | one argument only | No | ## What `db:prepare` does here Its full semantics belong with the migration tasks; for the entrypoint, what matters is: 1. if a configured database does not exist yet, it is created, its schema loaded and, for the primary database, seeds run, so the first boot on an empty server or volume produces a working database; 2. if it exists, pending migrations run; 3. in a multi-database app (the generated SQLite setup has `primary`, `cache`, `queue` and `cable`), each database is prepared. Only then does `exec "${@}"` replace the shell with the real command, so Thruster (and through it Puma) becomes the process Docker signals on stop. ## Failure behaviour The shebang's `-e` makes bash exit as soon as any command fails. If `db:prepare` raises, because a migration is broken or the database is unreachable, the script exits non-zero before `exec`, the container stops, and the new release never serves traffic. With Kamal, the proxy keeps sending requests to the old container because the new one never answers its `/up` health check. ## Running it by hand You can reproduce each branch locally with the built image: - `docker run bookstore` uses the default `CMD`, so the entrypoint prepares the database and then starts Thruster and Puma; - `docker run -it bookstore ./bin/rails console` skips preparation and opens a console; - `docker run bookstore ./bin/rails db:prepare` runs the task explicitly as the command itself, which is how a separate release step would run it. ## Production consequences a senior engineer names - **Migrations run at boot, before the health check passes.** A long migration can outlast Kamal's `deploy_timeout` (30 seconds by default) and fail the deploy even though it is still progressing. Run long data migrations separately. - **Old code meets the new schema.** During a rolling deploy the previous container keeps serving while the new one has already migrated, so migrations must be backward-compatible with the release still running. - **Several web hosts migrate at once.** Each container runs `db:prepare`; on PostgreSQL and MySQL, Active Record's migrator takes an advisory lock, so one host migrates and another that collides gets `ActiveRecord::ConcurrentMigrationError` and fails its boot. - **Job containers depend on the web container having migrated.** `bin/jobs` never migrates, so a job host booted first can run new code against an old schema. - **Custom commands silently lose the step.** Adding a flag to the server command, or dropping the `./`, turns automatic migrations off with no warning.
- The bookstore's web role is changed to run `./bin/rails server -b 0.0.0.0`. What breaks, and what are two ways to fix it?The entrypoint now sees `-b` and `0.0.0.0` as the last two arguments, so `db:prepare` is skipped and new migrations never run at boot. Either keep the flags out of the command (Puma already reads `PORT` and binds every interface outside development), or edit the entrypoint's condition, or run `bin/rails db:prepare` as an explicit deploy step.
- Why does the script end with `exec "${@}"` instead of just `"${@}"`?`exec` replaces the bash process with the command, so Thruster becomes the container's main process and receives the stop signal directly. Without it, bash would stay as the parent and the server would not get the SIGTERM it needs for a graceful shutdown.
- The entrypoint runs db:migrate before every command, including bin/rails console
- db:prepare drops and reloads the schema on every deploy
- Adding flags after server on the CMD still triggers db:prepare
- If a migration fails, the server starts anyway on the old schema
- A bin/jobs container migrates the database itself before working jobs
Assumes the Rails 8.1 app generator's bin/docker-entrypoint, which checks the last two arguments so the Thruster-wrapped CMD still matches.