# Upgrading to v0.6

Source: https://docs.anetos.dev/main/upgrade/v0.6/

v0.6 removes the names v0.5 deprecated. A project that uses none of
them (your editor and `staticcheck` mark them) needs no change in its
code; its settings, command names and process types may still need one
(below).

Upgrade in this order. `go fix` rewrites the old names only while they
still exist, so it runs on v0.5, before the upgrade:

1. On v0.5 (`v0.5.x`), run `go fix ./...`. It rewrites most of the
   names below. Then rename by hand what it leaves (the
   [calls it can't rewrite](https://docs.anetos.dev/main/upgrade/v0.6.md#what-go-fix-doesnt-rewrite)).
2. Rename the [settings](https://docs.anetos.dev/main/upgrade/v0.6.md#settings-renamed-in-v05-are-no-longer-read)
   in your `.env` files and your deployment's environment.
3. Update the modules: `go get anetos.dev/anetos@v0.6.0`, the tool
   (`go get -tool anetos.dev/anetos/cli/cmd/anetos@v0.6.0`), `admin`,
   the drivers and the plugins you use (`plugins/postmark`) to their
   v0.6.0; then `go mod tidy`.
4. If the project has the coding agents' files (`AGENTS.md`), run
   `go tool anetos agent:update`: v0.6's describe its commands and
   skills.
5. Run `go tool anetos check`. The compiler names any old name left.

## Removed names

Each was deprecated in v0.5 and is removed in v0.6.

| Removed | Use |
|---|---|
| `cache.ForApp`, `queue.ForApp`, `session.ForApp`, `mailer.ForApp`, `storage.ForApp`, `pubsub.ForApp`, `events.ForApp`, `schedule.ForApp`, `encryption.ForApp`, `i18n.ForApp`, `audit.ForApp`, `ai.ForApp`, `rbac.ForApp`, `migrate.ForApp` | `New` of the same package |
| `auth.ForApp`, `social.ForApp` | `auth.New`, `social.New` |
| `openapi.ForApp` | `openapi.Register` |
| `a.SignIn`, `a.SignOutOthers`, `a.SignOutEverywhere` | `a.Login`, `a.LogoutOthers`, `a.LogoutEverywhere` |
| `a.CanTwoFactor`, `a.CanRemember`, `a.CanSignOutEverywhere` | `a.SupportsTwoFactor`, `a.SupportsRemember`, `a.SupportsLogoutEverywhere` |
| `a.ActAs`, `auth.ActAs`, `auth.ActOption` | `a.WithUser`, `auth.WithUser`, `auth.UserOption` |
| `auth.ErrNoPendingSignIn`, `auth.ErrNoUser` | `auth.ErrNoPendingLogin`, `auth.ErrUserNotFound` |
| `auth.DefaultHomeURL` | `auth.WithDefaultHomeURL` |
| `*social.ErrNoAccount` | `*social.NoAccountError` |
| `app.SocialSignIn` (anetostest) | `app.SocialLogin` |
| `mailer.BaseURL`, `mailer.DefaultFrom` | `mailer.WithAppURL`, `mailer.WithDefaultFrom` |
| `storage.BaseURL`, `storage.Public`, `storage.SignWith` | `storage.WithBaseURL`, `storage.WithPublic`, `storage.WithSigner` |
| `i18n.WarnMissing` | `i18n.WithWarnMissing` |
| `i18n.URLNone`, `URLPrefix`, `URLSubdomain` | `i18n.StrategyNone`, `StrategyPrefix`, `StrategySubdomain` |
| `admin.Title`, `admin.UserName` | `admin.WithDefaultTitle`, `admin.WithUserName` |
| `admin.Field[T](title, column)` | `admin.TextColumn[T](column, label)`: the column first, then its label |
| `web.TrustedOrigins` | `web.WithTrustedOrigins` |
| `gcs.ClientOptions`, `s3.Transport` | `gcs.WithClientOptions`, `s3.WithTransport` |
| `postmark.BaseURL`, `HTTPClient`, `Stream` | `postmark.WithBaseURL`, `WithHTTPClient`, `WithStream` |
| `events.BusOption`, `audit.Option` | `events.Option`, `audit.TrackOption` |
| `session.NewContext`, `web.RouteFromContext`, `web.ClientIPFrom` | `session.WithSession`, `web.CurrentRoute`, `web.ClientIP` |
| `anetos.Unit`, `UnitFunc`, `app.StartUnit`, `AroundUnits`, `HasAroundUnits` | `anetos.Operation`, `OperationFunc`, `app.StartOperation`, `AroundOperations`, `HasAroundOperations` |
| `anetos.Roles`, `app.Supervisor().Roles()` | `anetos.ProcessTypes`, `ProcessTypes()` |
| `db.Untracked`, `db.TxWith`, `db.PruneTrashed`, `page.HasMore()` | `db.AllowRepeatedQueries`, `db.TxWithOptions`, `db.Prunable`, `page.HasNext()` |
| `t.UniqueLive(…)`, `.UniqueLive()` (migrations) | `UniqueWithoutTrashed` |
| `pubsub.MaxAttempts`, `cache.Forget` | `pubsub.Tries`, `cache.Delete` |
| `c.Events()`, `web.View(…)`, `s.String(key)` (a session) | `c.EventStream()`, `web.Render(…)`, `s.GetString(key)` |
| `r.HandleStd(method, pattern, h)` | `r.Handle(method, pattern, web.WrapHandler(h))`, or `r.Get(pattern, web.WrapHandler(h))` |
| `ai.Func(name, description, fn)` | `ai.NewTool(name, description, fn)` |
| `fake.Embeddings()` (`ai.Fake`) | `fake.EmbedRequests()` |
| `gemini.Options{Config: …}` | `gemini.Options{Params: …}` |
| `storagetest.Features{SignedURLs: true}` | `storagetest.Features{TemporaryURLs: true}` |
| `storage.URLSigner` (a backend's `SignedURL` method) | `storage.TemporaryURLBackend` (`TemporaryURL`) |
| `gcs` and `s3` `(*Backend).SignedURL(…)`, called directly | `(*Backend).TemporaryURL(…)`, or the disk's `TemporaryURL` |
| `i18n.CommunicationPreference` (a user's `CommunicationLocale` method) | `i18n.MailLocalePreference` (`PreferredMailLocale`) |
| A plugin's `Listen(bus)` | `Listeners(bus)` (`ext.HasListeners`) |

## What go fix doesn't rewrite

`go fix ./...` (Go 1.26 and later) leaves these alone, and they don't
build on v0.6:

- **Calls of generic functions whose type arguments are inferred:**
  `auth.ForApp(app, users)`, `social.ForApp(…)`, `ai.Func(…)` and
  `admin.UserName(…)`. Go's inliner doesn't rewrite them yet; rename
  them by hand. (`db.PruneTrashed[T]` and `admin.Field[T]`, always
  written with their type argument, are rewritten, `admin.Field`'s
  arguments swapped for `admin.TextColumn`.) Check an
  `auth.ForApp[*User](…)` with its type argument written out after
  `go fix`: Go 1.27.2's inliner rewrites it into code that doesn't
  compile (`auth.Users[**User]`); write `auth.New(app, users)`.
- **The error variables** `auth.ErrNoUser` and `auth.ErrNoPendingSignIn`
  (a variable can't be inlined): use `auth.ErrUserNotFound` and
  `auth.ErrNoPendingLogin`.
- **Methods of generic types:** `a.SignIn`, `a.SignOutOthers`,
  `a.SignOutEverywhere`, `a.CanTwoFactor`, `a.CanRemember`,
  `a.CanSignOutEverywhere` and `a.ActAs` (`auth.Auth[U]`), and
  `page.HasMore()` (`db.Page[T]`). The
  [v0.5 guide's commands](https://docs.anetos.dev/main/upgrade/v0.5.md#logging-in) rename the `auth` ones.
- **Fields:** gemini's `Options.Config` and storagetest's
  `Features.SignedURLs`.
- **Methods your types implement.** These don't fail to build: the
  framework stops calling them, so v0.6 reports them instead.
  - A storage backend with `SignedURL` and no `TemporaryURL`:
    `TemporaryURL` fails with `has SignedURL, renamed TemporaryURL in
    v0.5`. Rename the method.
  - A user model with `CommunicationLocale` and no `PreferredMailLocale`:
    `i18n.ForUser` logs an error once and uses the display locale.
    Rename the method.
  - A plugin with `Listen` and no `Listeners`: `ext.Load` fails with
    `it has Listen, renamed Listeners in v0.5`. Rename the method.

## Settings renamed in v0.5 are no longer read

v0.5 read these settings under their former names too, with a warning.
v0.6 doesn't. If a former name is set and its new name isn't, the service
that reads it refuses to start, naming the new one:

```text
config: DB_CONNECTION (Config.Driver): renamed DB_DRIVER, and the former name is no longer read: rename it in your settings
```

So an app can't silently fall back to a default, such as SQLite for the
database. With both names set, the new one is used, and `doctor` says to
remove the former.

| Former name | Name |
|---|---|
| `DB_CONNECTION` | `DB_DRIVER` |
| `DB_DATABASE` | `DB_NAME` |
| `DB_USERNAME` | `DB_USER` |
| `MIGRATE_ON_RUN` | `DB_MIGRATE_ON_START` |
| `MIGRATE_READINESS` | `DB_MIGRATE_READINESS` |
| `SEARCH_LANGUAGE`, `SEARCH_RANKING` | `DB_SEARCH_LANGUAGE`, `DB_SEARCH_RANKING` |
| `CACHE_STORE` | `CACHE_DRIVER` |
| `SESSION_LIFETIME`, `SESSION_MAX_LIFETIME` | `SESSION_TTL`, `SESSION_MAX_TTL` |
| `AUTH_REMEMBER_LIFETIME` | `AUTH_REMEMBER_TTL` |
| `QUEUE_POLL` | `QUEUE_POLL_INTERVAL` |
| `LOCALE_URL` | `APP_LOCALE_STRATEGY` |

The [v0.5 guide's command](https://docs.anetos.dev/main/upgrade/v0.5.md#settings-with-one-name-per-idea)
renames them in your `.env` files. Rename them in your deployment's
environment and secrets too, and the keys of another database
connection by hand: they keep its prefix (`ANALYTICS_DB_CONNECTION` is
`ANALYTICS_DB_DRIVER`).

A setting of your own renamed with a `was` tag still works as before:
the former name is read, with a warning. `was:"OLD,removed"` is the new
form for a former name you stop reading.

## Commands, process types and a rule

The names before v0.5 are refused with an error naming the one to use
(a command exits with status 2, `run` with status 1):

| Before v0.5 | Use |
|---|---|
| `./app routes:list` | `./app route:list` |
| `./app plugins:list`, `./app plugins:env` | `./app plugin:list`, `./app plugin:env` |
| `./app lang:check` | `./app locale:check` |
| `./app schedule:run <task>` | `./app schedule:test <task>` (`schedule:run` takes no arguments) |
| `go tool anetos lang:add`, `add lang` | `go tool anetos locale:add` |
| `go tool anetos make:admin:resource` | `go tool anetos make:admin-resource` |
| `run --only=http`, `workers`, `listeners` | `run --only=web`, `worker`, `listener` |
| `anetos.ProcessTypes("workers")` and the others, `app.Run(ctx, "http")` | `"worker"`, `"web"`, `"listener"` |
| The validation rule `unique_live` | `unique_without_trashed` |

Check your deploy files too: a Procfile, a systemd unit, a Kubernetes
manifest or a cron line may still name an old command or process type.

## A web project with frontend/

In a web project, `frontend/` is now the frontend that Vite builds for
the pages ([Bundle JavaScript and CSS with Vite](https://docs.anetos.dev/main/guides/vite/index.md)).
When it has a `package.json`, `anetos dev` runs
`frontend/node_modules/vite/bin/vite.js`, and `anetos build` and
`anetos check` install its packages and run its `build` script. If your
web project's `frontend/` is something else, rename it before you
upgrade the tool. An API project's `frontend/` is left alone.

## The tool and projects made before v0.5

`anetos` no longer adds `views/ui` to a web project that has none.
v0.5's projects have it, but if yours was removed, `make:crud` and
`make:auth` stop and write nothing. `go tool anetos css:use <css
framework> --force` writes one. The tool no longer reads
`views/ui/kit.json`, the record of v0.5's development builds;
`views/ui/css.json` replaced it. And `go tool anetos generate` no
longer treats a `models_gen.go` that starts with the header before v0.5
(`// Code generated by anetos gen.`) as its own: it neither rewrites
nor removes it. Delete such a file and run `generate` again.
