# Upgrading to v0.3

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

The breaking changes of v0.3, with what to do.

## A database session in local time stops the app

Times are stored in UTC, and the app now checks at startup that the
database session is in UTC too, so the database never writes local times
(`CURRENT_TIMESTAMP`, `NOW()`) next to the app's UTC ones.

**Before:** a `DB_URL` with a session time zone started:

```sh
DB_URL=postgres://app@db/app?timezone=Asia/Dhaka
```

**After:** the app and its commands stop with "the database session's
time zone is Asia/Dhaka, not UTC". Remove `timezone=` (PostgreSQL) or
`time_zone=` (MySQL) from `DB_URL`. For a legacy database whose times are
local, keep it and set:

```sh
DB_ALLOW_LOCAL_TIMEZONE=true
```

## The process's local zone is the app's

Importing Anetos sets Go's local zone (`time.Local`) to `APP_TIMEZONE`,
UTC when unset, whatever the machine's zone or `TZ`. `time.Now()`, log
lines and formatted times on a developer's machine in another zone now
show UTC. Set `APP_TIMEZONE` to keep a local zone; times are stored in
UTC either way. See [times and dates](https://docs.anetos.dev/main/guides/times-and-dates/index.md).

## Binding messages

A value that can't be converted to its field's type (`page=abc`) is
reported with the catalog's `binding.<kind>` message, in the request's
language, instead of the converter's text:

| Before | After |
|---|---|
| `"page": "invalid integer \"abc\""` | `"page": "must be an integer"` |
| `"draft": "must be a boolean"` (JSON) | `"draft": "must be true or false"` |

Clients that match these strings need the new ones; change them for
your app in a catalog (`binding.integer`).

## Translations in projects made before v0.3

`anetos make:auth` writes its text to `locales/en/auth.yaml` and needs a
`locales` folder. In a project made by an earlier `anetos new`, add it as
[Translations](https://docs.anetos.dev/main/guides/translations/index.md#2-load-them) shows: a
`locales/locales.go` embedding the folder, and
`i18n.ForApp(app, locales.FS)` at the start of `setup` in `main.go`.

Once `i18n.ForApp` is called, the HTTP server handles a `locale` query
parameter on page requests (a GET for HTML, not htmx) that names a
supported locale: it stores the choice in a cookie and redirects without
the parameter. A page route that reads its own `locale` parameter (a
filter of content by language) should use another name. API requests and
unsupported values reach your routes as before.

## A remote database is reached over verified TLS

Connections built from `DB_HOST` (PostgreSQL, MySQL) now use TLS and
check the server's certificate unless the host is this machine
(`DB_TLS=verify`). PostgreSQL connected with `sslmode=prefer` before,
which falls back to plain text; MySQL without TLS.

**After:** a server without TLS, or with a certificate signed by its
provider's own authority, refuses the connection (`x509: certificate
signed by unknown authority`). Set `DB_TLS_CA` to the provider's
certificate, or, on a private network you trust, `DB_TLS=skip-verify`
(encrypted) or `DB_TLS=none`. `DB_URL` is unchanged: its own options
decide. The production settings `anetos new` writes use
`sslmode=verify-full` for PostgreSQL's `DB_URL`.

## Security fixes that change behaviour

From the security review ([docs/security/checklist.md](https://github.com/anetos-dev/anetos/blob/main/docs/security/checklist.md)):

| Change | What to do |
|---|---|
| `X-Real-IP` is no longer read; the client's address comes from `X-Forwarded-For` sent by a proxy in `HTTP_TRUSTED_PROXIES` | A proxy that only sets `X-Real-IP` (nginx's `proxy_set_header X-Real-IP`): add `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;` |
| `web.MethodOverride` overrides only form posts (urlencoded or multipart), and never a cross-site one (`Sec-Fetch-Site`, or else an `Origin` other than the host) | A client that sent `_method` with another body: send the real method |
| Every app has a `doctor` command | An app command of your own named `doctor` panics at startup (`registered twice`): rename it |
| Search: at most 10 terms; a term matches as a prefix from 3 letters (`go` matches the word "go", not "golang"); on MySQL, short words InnoDB skips are dropped unless every word is | Nothing, unless tests expect the old matches |
| SQLite: double quotes are identifiers only (`_dqs=0`): `WHERE name = "ada"` fails | Use single quotes for strings in raw SQL |
| `auth.Require` sets `Cache-Control: no-store` on what it lets through | A route that set its own `Cache-Control` before the middleware: set it in the handler, after |
| The `log` mail driver leaves out the bodies in production | Use a real driver in production (`doctor` warns) |
| Local storage writes files 0640 and folders 0750 (were 0644 and 0755) | Another user that must read the files (a web server serving them directly): run the app with a group they share. The systemd unit `anetos new` writes keeps them to the app (`UMask=0077`, a dynamic user): serve files through the app |
| `anetos add` asks before running a plugin's code, in a terminal | Scripts are unaffected (no terminal); `--yes` skips the question |
| `anetos dev` answers 403 to host names other than localhost, IP addresses and `APP_URL`'s host | Another name (`myapp.test`): `anetos dev --host=myapp.test` |

## MySQL and MariaDB tables are utf8mb4

The tables the schema builder creates (`s.Create`) are now utf8mb4
even when the database's default character set isn't (MariaDB before
11.6 may default to latin1, which refuses most non-Latin text with
`Error 1366: Incorrect string value`). Tables created before v0.3 keep
their character set: `doctor` lists the ones with text columns in
another. Convert them before a new migration adds a string foreign key
to one of them (a utf8mb4 column can't reference a latin1 one: errno
150 on MariaDB, error 3780 on MySQL). Tables linked by string foreign
keys are converted together, with the checks off for the session:

```sql
SET FOREIGN_KEY_CHECKS = 0;
ALTER TABLE tags CONVERT TO CHARACTER SET utf8mb4;
ALTER TABLE post_tags CONVERT TO CHARACTER SET utf8mb4;
SET FOREIGN_KEY_CHECKS = 1;
ALTER DATABASE blog CHARACTER SET utf8mb4; -- for tables made with SQL later
```

Converting rewrites each table: on a large one, do it at a quiet time.
An indexed `VARCHAR` longer than 768 characters is too long for an
index in utf8mb4 (error 1071): shorten it first.

## The server waits for its migrations

With `migrate.ForApp`, the server reports itself unavailable
(`/health/ready` answers 503, `health:check` exits 1) while the
database has migrations the app hasn't run, and logs which; it becomes
ready within 5 seconds of `migrate`. A deploy that migrates before
starting the new version (systemd's unit, a release command, Render's
`preDeployCommand`) sees no change. One that starts the new version,
waits for it to be ready, and only then migrates would wait forever:
migrate first, or set `MIGRATE_READINESS=false`.

## Code that make:auth wrote before v0.3

Apps own the code `make:auth` writes, so the fixes to it don't reach
existing apps. Compare yours with a new project's (`anetos new` in a
scratch folder, then `make:auth`), and apply:

- **API tokens need a confirmed password.** In `routes/auth.go`, move
  `POST /tokens` (`tokens.store`) into the group with
  `a.RequireConfirmed`, and confirm the password in tests that create
  tokens (`/confirm-password`).
- **A reset revokes more.** `Reset` in `app/handlers/auth.go` changes
  the password only if it is still the one the link was made for (two
  uses at once change it once), revokes the API tokens, and, for an
  address never verified, verifies it and turns off two-factor sign-in
  and the Google and GitHub links. Copy the new function.
- `locales/en/auth.yaml`'s `password_changed` message says that API
  tokens keep working after a password change.

The library side needs nothing: `CreateToken` refuses while an admin
acts as the user, and two-factor codes and password confirmations are
checked safely, whatever your code.
