Skip to content
Andurel.Docs
latest

Version

latestlatest1.5.2
Getting Started / latest

Moving to v2

Andurel v2 is not an in-place upgrade from v1. The architecture changed: Echo and Fx are gone, controllers became handlers, models became domains, and Templ pages became Inertia pages. The v2 CLI refuses to upgrade a project across a major version.

Keep a production v1 application on the 1-5-stable line with a v1 CLI (github.com/mbvlabs/andurel@v1.x.y) until you can move it deliberately.

Plan the move

  1. Install the v2 CLI and create a fresh project that matches the v1 application's database and UI choice:

    1go install github.com/mbvlabs/andurel/v2@v2.0.0-beta.1
2andurel new orbit
3cd orbit
4andurel tool sync

  2. Move the schema first: copy the SQL migrations into migrations/ and run andurel db migrate up.

  3. Port one domain at a time into domains/, with its SQL colocated as domains/<entity>.sql, then run andurel sync queries.

  4. Port services, then jobs and email, then handlers and routes, and finally the Inertia pages.

  5. Run both applications against disposable databases and compare user-visible behavior.

  6. Finish with andurel verify --with-tests.

Treat the v2 scaffold as the new baseline. Do not overwrite a v1 project with a v2 scaffold, and do not run broad scripted replacements across the old tree without reviewing each change.

What changes

Area v1 (1.5.2) v2
HTTP Echo controllers and a router package net/http handlers in handlers/, func(ctx context.Context) error, through pkg/anduin
Wiring Fx modules and lifecycle hooks explicit constructors in internal/runtime; no container
Persistence models/ with Bun, generated from the schema domains/, one flat package, SQL colocated, narsilc-generated queries
Routes router/routes registered with Echo route values in routes/, registered in Register(rt *anduin.Router)
UI Templ pages and Datastar Inertia v3 React, Vue or Svelte; Templ only for the root document and email
Config config package backed by the environment the same idea with typed sections that validate at startup
Framework code copied into the project's internal/ and rewritten by andurel upgrade github.com/mbvlabs/andurel/pkg/* modules pinned in go.mod; application code is never rewritten
Code generation scaffold, model, factory, controller, view, routes only andurel generate migration; other layers come from andurel patterns show
Discovery andurel project info, andurel routes andurel inspect project, andurel inspect routes
Database CLI andurel database ... andurel db ...

The old database/ directory splits into migrations/ (SQL) and seeds/ (named seed sets). Queue insertion stays available to the web process, and processing stays in cmd/queue.

Move behavior, not code

Controllers and views do not carry over as-is:

  • A controller method becomes a handler method. Its dependencies become constructor parameters, and its Echo request access becomes anduin calls on the context.
  • A Templ page becomes an Inertia page plus a props struct. Typed component calls become a JSON boundary, so decide which fields the browser is allowed to see.
  • A Datastar interaction becomes frontend state or an ordinary HTTP request. There is no fragment or SSE layer to port.
  • A v1 model becomes a domain entity with andurel:"column" tags, a Validate() method, and the CRUD methods its callers use.
  • Fx module registration becomes one line in internal/runtime, next to the constructors that produce it.

Domain rules should survive the move unchanged. If a rule has to change, frontend or transport concerns were probably mixed into the domain boundary in v1.

Upgrading within v2

Pre-release v2 projects upgrade between releases, not across major versions. andurel upgrade accepts projects created at v2.0.0-alpha.4 or later. It pins the pkg/* modules to the versions verified with the installed CLI, synchronizes the tools, and reports a manual action for every application-owned change the release needs.

Preview first, then apply:

1andurel upgrade --dry-run --diff --json
2andurel upgrade

A real upgrade requires a clean Git worktree, applies the reported manual actions, and is idempotent. After applying the actions, run gofmt -w ., go fix ./..., go vet ./..., and andurel verify.

Projects created before v2.0.0-alpha.4, and all v1 projects, must be recreated with andurel new and ported by hand.