Upgrading RailsPress

Guide for upgrading the RailsPress engine between versions.

Quick Upgrade

# 1. Update the gem
$ bundle update railspress

# 2. Copy new migrations
$ rails railspress:install:migrations

# 3. Run migrations
$ rails db:migrate

# 4. Restart your server

Step-by-Step Guide

1. Update the Gem

If using a version constraint in your Gemfile:

gem "railspress-engine", "~> 0.2.0"

Run:

$ bundle update railspress-engine

If using a git source:

gem "railspress-engine", git: "https://github.com/your-org/railspress-engine", branch: "main"

2. Copy New Migrations

RailsPress includes a rake task to copy engine migrations to your application:

$ rails railspress:install:migrations

This copies any new migrations from the engine to your db/migrate/ folder. Existing migrations are skipped (matched by migration name, not timestamp).

Check what was copied:

$ ls -la db/migrate/*railspress*

3. Review Migration Changes

Before running migrations, review them for any data implications:

# See pending migrations
$ rails db:migrate:status

# Preview a specific migration
$ cat db/migrate/TIMESTAMP_create_railspress_exports.rb

4. Run Migrations

$ rails db:migrate

For production, consider running migrations separately from deployment:

$ RAILS_ENV=production rails db:migrate

5. Check Configuration

New versions may add configuration options. Review the initializer:

Railspress.configure do |config|
  config.enable_authors
  config.author_class_name = "User"
  config.author_display_method = :name

  config.enable_header_images
end

Check the Configuration guide for new options.

6. Restart Application

# Development
$ rails restart

# Production (example with Puma)
$ pumactl restart

Migration Internals

How Engine Migrations Work

RailsPress migrations live in railspress/db/migrate/. When you run railspress:install:migrations, Rails copies them to your app with new timestamps.

Engine migration:

railspress/db/migrate/20241218000001_create_railspress_categories.rb

Becomes in your app:

db/migrate/20241224123456_create_railspress_categories.railspress.rb

The .railspress suffix tracks the migration origin.

Migration Naming Convention

RailsPress uses a fixed timestamp prefix pattern:

New migrations increment the suffix (000007, 000008, etc.).

Checking Migration Status

# See all migrations and their status
$ rails db:migrate:status

# Filter to RailsPress migrations
$ rails db:migrate:status | grep railspress

Rolling Back

If needed, rollback a specific migration:

# Rollback last migration
$ rails db:rollback

# Rollback to specific version
$ rails db:migrate:down VERSION=20241224123456

Troubleshooting

"Migration already exists"

If the rake task reports migrations already exist, they've been copied before. Check:

$ ls db/migrate/*railspress*

Schema Mismatch

If your schema differs from expected migrations:

# Check current schema
$ rails db:schema:dump
$ cat db/schema.rb | grep railspress

# Compare with engine migrations
$ ls railspress/db/migrate/

Missing Tables

If RailsPress tables are missing:

# Re-copy all migrations
$ rails railspress:install:migrations

# Run pending
$ rails db:migrate

Duplicate Migrations

If you have duplicate migrations (same content, different timestamps):

1. Check which are already run: rails db:migrate:status
2. Delete the unrun duplicate
3. If both are run, the second likely failed silently

Version-Specific Notes

Upgrading to 0.2.0

New: Import/Export feature

Adds two new migrations:

• create_railspress_imports
• create_railspress_exports

Requires:

• rubyzip gem (included in railspress dependencies)
• redcarpet gem (included in railspress dependencies)
• ActiveStorage configured (for export file storage)

After upgrade:

$ rails railspress:install:migrations
$ rails db:migrate

Upgrading to 0.1.x

Initial release. Run full install:

$ rails generate railspress:install
$ rails db:migrate

CI/CD Considerations

Automated Upgrades

In CI, ensure migrations run before tests:

- name: Setup database
  run: |
    rails railspress:install:migrations
    rails db:create db:migrate

Production Deployments

For zero-downtime deploys, run migrations before deploying new code if they're additive (new tables, new columns with defaults).

For destructive migrations (removing columns), deploy code first, then migrate.

# Typical deploy sequence
$ git pull origin main
$ bundle install
$ rails railspress:install:migrations
$ rails db:migrate
$ rails assets:precompile
# restart app

Getting Help

• Check the Configuration guide for configuration options
• Check the Import & Export guide for import/export features
• Review engine source: bundle show railspress