Migration Guide: Amber 1.x to 2.0

Start with the smallest possible upgrade. For many Amber 1.x applications that already use ECR and do not depend on Amber's old bundled integrations, the first—and sometimes only—application change is the Amber version in shard.yml. V2 is mostly additive framework work, not an invitation to rewrite your product.

The standalone Amber CLI is independent from this runtime upgrade. Install or update it when you want V2 generators; an existing application can change its framework shard without being regenerated.

Amber 2.0.0-beta.5 release-gates the framework core and the new ECR web template with Grant, Micrate, and SQLite. Existing applications do not have to replace a working ORM to adopt the framework beta. Gemma, Asset Pipeline, generated auth/API resources, and native output remain separate previews.

Try the direct upgrade first

File: shard.yml — change the existing amber dependency version.

dependencies:
  amber:
    github: amberframework/amber
    version: 2.0.0-beta.5

Keep the rest of the application's dependencies unchanged for this first pass.

Run from: the application root, beside shard.yml.

shards update amber
crystal spec
shards build

If those commands pass, launch the application through its normal development command and smoke-test the routes it actually serves. You do not need to adopt the Schema API, replace an ORM, remove working front-end tooling, or regenerate the project merely because V2 offers newer options.

When the direct upgrade needs a follow-up

The migration remains bounded, but it is not literally one line for every application. Check the matching row only when the application uses that feature:

This inventory is why the guide contains more than a version edit. It is a map for the exceptions, not evidence that an ordinary Amber application must be rebuilt.

What changes in V2

Before changing dependencies in a production application

Create a migration branch and capture a working baseline:

1. Record the Crystal, Amber, ORM, database-driver, Redis, and asset-tool versions.
2. Run the existing specs and build the application binary.
3. Smoke-test the routes, session behavior, background work, WebSockets, and static assets the application actually uses.
4. Back up the database and prove the restore procedure before changing an ORM or running a schema migration.
5. List every Slang/Kilt template, Webpack entry point, Redis integration, and framework-generated file that will need an explicit decision.

Do not begin by deleting the old asset, persistence, or session configuration. Keep the last working path available until its replacement has passed the same checks.

1. Restore the framework baseline

After the direct upgrade commands above, resolve any compile errors against the V2 routing, controllers, views, and configuration guides. Keep persistence and asset-tool changes out of this step whenever possible.

2. Move generated and legacy views to ECR

Amber V2 removes Kilt and Slang from the supported framework path. Convert one view boundary at a time, preserve its rendered HTML contract, and run the request or feature specs that exercise it. New V2 generators emit ECR.

The Views guide documents layouts, partials, helpers, and escaping behavior for the V2 path.

3. Make sessions and pub/sub explicit

Amber V2 includes in-memory session and pub/sub adapters. They keep a clean application independent of Redis, but their state is local to one process.

Applications that require shared state across processes or hosts must register and test an external implementation. Redis is not a built-in adapter guarantee; it is one backend an application can integrate through the adapter interfaces.

Use the Redis-to-adapters guide to inventory the existing behavior, then verify expiration, logout, session rotation, broadcasts, and multi-process delivery before switching production traffic.

4. Keep an existing persistence migration separate

Amber CLI 2.0.6 installs Grant and SQLite in a newly generated web application. That default does not require an existing Granite or Jennifer application to change ORM during the framework upgrade. Keep its current persistence layer for the first pass, then verify compatibility against the application's Crystal version, shard versions, and real queries.

If you choose to move to Grant, treat that as a second migration with its own branch, database backup, restore proof, schema diff, representative reads and writes, and rollback plan. Do not mix two ORMs unless ownership of connections, transactions, migrations, and models is explicit. Review the model-layer boundary and Granite-to-Grant guide first.

5. Preserve working assets before replacing tooling

Released CLI 2.0.6 compiles browser-ready files from app/assets/ into a fingerprinted public/assets/ manifest without requiring Node.js or a bundler. That does not require an existing application to remove a working Webpack pipeline during the framework upgrade.

If you adopt native ESM and the build-time Asset Pipeline contract, treat it as its own migration. Compare the complete manifest; rewritten local CSS and JavaScript dependencies; image, font, and binary bytes and MIME types; import behavior; cache headers; read-only runtime; and atomic production deployment before retiring the previous build. The Webpack-to-ESM guide and Asset Pipeline guides describe that independently reviewable migration; existing asset tooling may remain in place while the framework dependency changes.

6. Adopt optional V2 features after the baseline passes

Schema API, jobs, mailers, adapters, and expanded testing helpers can be adopted independently. Add one application boundary, write or update its specs, and restore the complete build before moving to the next.

7. Migrate request validation action by action

The old params.validation API is deprecated, not removed. Existing blocks continue to compile and run after the V2 framework upgrade:

File: an existing action under src/controllers/ — this code may remain unchanged during the first upgrade pass.

validation = params.validation do
  required(:email) { |value| value.email? }
end

Amber plans to retain that API throughout the initial V2 compatibility window and remove it no earlier than a later minor release such as 2.5. The exact removal release will be announced separately. A deprecation warning is a prompt for a gradual migration, not evidence that a V1 application must rewrite all controllers before adopting V2.

For one action at a time:

1. create its request contract under src/schemas/;
2. bind it above the action with schema :action, SchemaClass;
3. read typed values with validated_as(SchemaClass) or the normalized hash with validated_params;
4. add response_schema when the action returns a machine-readable API contract; and
5. prove valid, malformed, unsupported-media, invalid-value, and invalid-response behavior before converting the next action.

The declared schema runs automatically before the action. Do not replace the old validator with a manual SchemaClass.validate(request) call; that is not the V2 controller API. The complete Schema guide shows the executable request and response path with exact file locations.

Verification gates

Use observed behavior instead of an estimated migration timeline:

A migration boundary is complete when its previous behavior is reproduced or an intentional change is documented and tested—not when a predetermined number of days has elapsed.

Getting help

When reporting a migration problem, include the smallest failing example plus the Crystal version, Amber version, previous Amber version, relevant shard versions, exact command, and complete output.

• Review the Amber V2 release notes.
• Ask in the Amber Discord.
• Report framework behavior in the Amber issue tracker.
• Report CLI and generator behavior in the Amber CLI issue tracker.