Upgrading to 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:
DB_URL=postgres://app@db/app?timezone=Asia/DhakaAfter: 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:
DB_ALLOW_LOCAL_TIMEZONE=trueThe 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.
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 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):
| 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:
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 laterConverting 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, movePOST /tokens(tokens.store) into the group witha.RequireConfirmed, and confirm the password in tests that create tokens (/confirm-password). - A reset revokes more.
Resetinapp/handlers/auth.gochanges 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’spassword_changedmessage 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.