mix phoenix_kit.update (phoenix_kit v2.32.1)

Copy Markdown View Source

Igniter-based updater for PhoenixKit.

This task handles updating an existing PhoenixKit installation to the latest version by creating upgrade migrations that preserve existing data while adding new features.

Two-Pass Update Strategy

To prevent configuration timing issues, the update process uses a two-pass strategy:

  1. First Pass (if configuration is missing): Adds required configuration (e.g., Ueberauth settings) via Igniter and prompts you to run the command again.

  2. Second Pass (configuration present): Safely starts the application and completes the update process.

This ensures that the application always starts with all required configuration present, avoiding runtime errors from missing dependencies.

Automatic Updates

The update process also automatically:

  • Updates CSS configuration (enables daisyUI themes if disabled)
  • Rebuilds assets using the Phoenix asset pipeline
  • Applies database migrations (with optional interactive prompt)

Usage

$ mix phoenix_kit.update
$ mix phoenix_kit.update --prefix=myapp
$ mix phoenix_kit.update --status
$ mix phoenix_kit.update --skip-assets
$ mix phoenix_kit.update -y
$ mix phoenix_kit.update --no-start

When the application will not start (--no-start)

The full update runs Mix.Task.run("app.start"), and a column-adding release is exactly when that fails. The newly compiled schema module selects a column the database has not got, so any host child that queries at init — a registry warming a cache, a GenServer loading settings — takes the whole boot down with ERROR 42703 (undefined_column), and the updater that would add the column cannot run. update_mode: true stands PhoenixKit's own supervisor down; it has no say over the host's children.

--no-start runs the two steps that need no application: it generates the chain step-up migration (mix phoenix_kit.gen.migration reads the current version off the migration FILENAMES, never the database) and applies it with mix ecto.migrate, which starts the repo alone. Configuration repair, asset rebuild and module migrations are skipped and reported — every one of them needs the app. Run the full mix phoenix_kit.update once the host boots again.

Options

  • --prefix - Database schema prefix. When omitted, resolves from config :phoenix_kit, :prefix, then defaults to "public". Passing it explicitly also persists the config entry. On prefixed installs the task warns when your existing Oban config lacks the prefix: key.
  • --status - Show current installation status and available updates
  • --force - Force update even if already up to date
  • --skip-assets - Skip automatic asset rebuild check
  • --yes / -y - Skip confirmation prompts and run migrations automatically
  • --no-start - Migrate the database without starting the host application. See "When the application will not start" above.

Examples

# Update PhoenixKit to latest version
mix phoenix_kit.update

# Check what version is installed and what updates are available
mix phoenix_kit.update --status

# Update with custom schema prefix
mix phoenix_kit.update --prefix=auth

# Update without prompts (useful for CI/CD)
mix phoenix_kit.update -y

# Force update with automatic migration
mix phoenix_kit.update --force -y

Version Management

PhoenixKit uses a versioned migration system. Each version contains specific database schema changes that can be applied incrementally.

Run mix phoenix_kit.status to see the currently installed and latest available migration versions.

Safe Updates

All PhoenixKit updates are designed to be:

  • Non-destructive (existing data is preserved)
  • Backward compatible (existing code continues to work)
  • Idempotent (safe to run multiple times)
  • Rollback-capable (can be reverted if needed)