Upgrading Go Fiber v2 to v3
One of the things I like about Go in general is its commitment to backwards compatibility. More than any other language I’ve used — and I consider this a major feature — I have had by far the fewest issues when upgrading between versions. This benefit also extends to libraries (packages) you use (unlike, say, javascript or python). While you need a bit more under the hood knowledge than magic frameworks, things in Go seem to Just Work™.
Technically, you need to expect breaking changes when you migrate between versions, but even then, despite massive overhauls, you hope things need only minor tweaks.
Fiber is usually the tool I go to first when needing to put together web services. Despite it getting some side-eye from purists, I find it intuitive, easy to use, and very fast with a solid ecosystem of supporting packages. It’s not as batteries-included as Rails (and lacks some features like automatic swagger docs from the code like FastAPI), but it gets the job done, is blazingly performant, and I can hold it all in my head when coding things.
I’ve been handling a major API, web service, and ingestiong processing system for a while now which has been happily humming along on Fiber v2 for over a year. Fiber’s recent bump to v3 had plenty of warnings they were making changes, and while it didn’t deliver any performance leaps or massive new features, what it has done is made the framework more cohesive, the middlware more logical, and cleaned up things architecturally so things make even more sense than they did previously.
The Migration Tool
One thing I have to say I thought was great was the included migration tool. While it can be argued a lot of framework have this built in, this was a lot more explicit and genuinely useful as you could see what changes were being proposed before testing or deploying anything. After installing the new version, you simply:
| |
It sort of reminds me of Go 1.26’s go fix feature to modernize and update all
your Go code. Horrendously helpful, explains what it’s doing, and does a great
job bringing you up to current idioms (and, in my case, teaching me some new
things I didn’t know.).
Some people reported issues with this and needing to change code back to past v2 versions though not the actual details on what that was
It flawlessly moved my rather complex code base to new conventions without issue.
Bottom line: use it.
Gotchas
Outh2 Interaction
I’ve been using the goth_fiber package for some time to provide OAuth2 logins
in the application. When we were looking at the beta of v3 a while back, this
needed to be modified with the changes to the Session middleware. Not updating
it broke logins across the board (and I have to say Oauth2 is not so easy to
test in dev environments).
I actually ended up providing a PR to update the library to Fiber v3 which ended up merged into the v2 branch release .
Things went a little more easily after that, but if you are using OAuth2, you will definitely need to deal with the sessions changes or face breakages.
Middleware changes
I actually like the way middleware has been cleaned up across the board in v3 and certain functions (like static, for example) moved into Midleware. Makes more sense and for a predictable way things should be used from the actualy applications.
One thing that did catch me out was the Session middleware changes though. In particular, previously I needed to automatically destroy
Trusted Proxies
This one took me off guard a little since the feature was not one I used, but I
do have traefik in front of my entire application in production to handle
security and as an SSL endpoint terminator (I am very happy with traefik by
the way. If you’re not using it already, I highly recommend it.).
Now though, and this is somethign that shuld be in the migration docs, if you do
have a proxy, trusted proxies are basically required, which means you need to
add this stanza to your main.go’s’ app.Config or all users being blocked as
you do not get rewrites of the X-Forwarded-For header which, well… breaks
things.
So, definitely read the Trusted Proxies section of the App changes. I do feel this could be written a bit better, since if you do have a proxy it will break things, but in an otherwise sterling release, it’s probably just an honest oversight considering how most people are most likely using Fiber.
Fin
Overall, the V3 upgrade was fairly painless and issues were really limited to authentication and session mechanisms that are common to all Go apps. Why Fiber does not have a standard authentication library like Devise or Better Auth. Go purists insist on rolling their own, but I personally find this a waste of tie for standard functionality like this.
Good luck on your migration!
If this post was useful, or you have some constructive feedback, please lemme know via mail or elephant below. Feel free to mention or ping me on @awws on mastodon or email me at hola@wakatara.com .