Forem: Kengo Wada

When APIs Fail: A Developer's Journey with Retries, Back Off, and Jitter

Kengo Wada — Mon, 21 Jul 2025 15:26:28 +0000

You’ve just built your billion-dollar app.
It fetches and sends data to a web of external services. Stripe handles your payments. Twilio sends your OTPs and messages. You’ve got at least one AI model doing something magical. Maybe you’ve even thrown in a dash of crypto, because why not? You didn’t become a tech billionaire by building basic CRUD apps.

But then, it happens. A request fails.
At first, you think: “I must’ve messed up.”
And sure, during development you fixed those user-side bugs, bad requests, missing parameters, the dreaded 422 Unprocessable Entity. But now the errors you’re seeing are different.

You’re getting:

500 Internal Server Error - what even is that?
503 Service Unavailable - cool, cool, but when will it be available?
408 Request Timeout - like you, the API seems too busy to respond.

You double-check your code. Everything’s clean. Your app did nothing wrong.

The problem? The services you rely on just couldn’t keep up with your success.

Now, you have a choice:
You could accept the failure and move on, or…
You could build a resilient system that doesn’t just give up the moment an API gets cranky.

This is where our story begins, with retries.
But as you’ll see, retrying isn’t as simple as looping and hoping. We’ll explore how retries can go wrong, how to back off gracefully, and how adding a little randomness, jitter, can save you (and the API) from a world of pain.

Retries

Not every failed request deserves a second chance.

When a request fails, the first thing you need to do is understand why. Some failures are your fault, like sending malformed data that the server just can't process. In these cases, you'll see a 422 Unprocessable Entity, and no amount of retrying is going to magically fix bad input. Fix the payload, not the persistence.

But other times, the failure isn't on you. Maybe you're trying to charge a customer with Stripe and you get hit with a 503 Service Unavailable, or you're waiting for a response that never comes and receive a 408 Request Timeout.
You double-check your request. The headers are right. The data is valid. Everything on your end checks out.

That’s when retries come into play.

For transient errors like these, where the issue is likely temporary, it makes sense to try again. A retry is a way of saying:

Hey, I know you’re having a moment, but I’ll give you another shot.

Let’s look at how a basic retry might work in Python.

from http import HTTPStatus
from typing import Any

import requests


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    return requests.post(url, headers=headers, data=payload)


def main():
    headers = {
        "Authorization": "some-secure-api-token",
        "Content-Type": "application/json",
    }
    payload = {
        "card_number": "1234-1234-1234-1234",
        "cvv": "123",
        "expiry_date": "12/32",
        "amount": 1_000_000.00,
        "currency": "USD",
    }

    response = collect_money(headers, payload)
    if response.status_code == HTTPStatus.OK:
        # Bentley or Rolls Royce?? Nah, both
        print("💰")
        return

    # ! As we can see, if the request doesn't succeed,
    # ! we can't flex. Let's fix this


if __name__ == "__main__":
    main()

Now let's add simple retry

RETRYABLE_STATUS_CODES = {
    HTTPStatus.REQUEST_TIMEOUT,
    HTTPStatus.INTERNAL_SERVER_ERROR,
    HTTPStatus.BAD_GATEWAY,
    HTTPStatus.SERVICE_UNAVAILABLE,
    HTTPStatus.GATEWAY_TIMEOUT,
}


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    while True:
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(f"Transient failure with {response.status_code}. Retrying...")

But hold up, retrying blindly opens the door to a whole new set of problems.
As we just saw, our current implementation keeps retrying forever if the service stays down. That might sound persistent, even noble, but in reality... it’s reckless.

You’ve essentially built an infinite loop that hammers a failing service with requests, over and over again. Not only is this wasteful, but if everyone using the same service does this, it can make things worse for everyone.

We need to put a leash on our enthusiasm.
Enter: max retries.

MAX_RETRIES = 3 # Can be anything, just make it reasonable


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    for i in range(1, MAX_RETRIES + 1):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i}] Transient failure with {response.status_code}. Retrying..."
        )

    return response

With that change, we’ve tamed our retries.

In this example, we’ve set a limit of 3 attempts, but the exact number is up to you. It should be reasonable, based on how critical the request is and how often the downstream service is likely to recover.

Right now, we simply return the final response. But in a real-world system, you might want to do more: log every failed attempt, store intermediate responses for debugging, or return a structured error indicating that this request failed after multiple retries.

But hey, that’s a story for another time. Let’s keep things simple for now.

Back Off

Now that we’ve added retries, things are looking better.
But there’s one big issue: our code is way too fast.

The time between retries is practically nonexistent. If the service is down, we just hammer it over and over again in rapid succession. Now imagine thousands of users doing the same thing, it starts to look a lot like a DDoS attack.

Picture this: someone’s busy, clearly overwhelmed, and you ask them for something. They say, “Wait…”, but before they even finish the word, you’re already asking again.
Do that enough times and even the calmest person would reach for… well, let’s just say you’d be testing the limits of their patience and the local laws.

We need to give services a breather between retries.
This is where we introduce back off, a deliberate pause before trying again.

Quick note:
For these examples, we’ll use seconds as our unit of time for delays, but in a real-world system, that could be milliseconds, minutes, or whatever suits your use case. The concept stays the same.

Constant Back Off

Just like the name suggests, this strategy waits the same amount of time between each retry. It’s the simplest form of backoff and incredibly easy to implement and reason about.

But simplicity has its limits.

While constant backoff works fine in development or low-traffic environments, it doesn’t scale well under load. In high-concurrency systems, it can cause a phenomenon known as a retry storm, when multiple clients all retry at the exact same intervals, bombarding the server in perfect sync.

This retry pattern creates the perfect conditions for a server meltdown.
(You might also hear it called a “thundering herd” problem in other documentation, it’s the same issue with a different name.)

That said, constant back off is still useful. It’s great for testing APIs, simulating retry behavior, or even as a baseline for tuning more advanced strategies like exponential back off(we'll get there).

BACK_OFF_TIME = 2


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    for i in range(1, MAX_RETRIES + 1):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i}] Transient failure with {response.status_code}. Retrying..."
        )

        time.sleep(BACK_OFF_TIME)

    return response

Linear Back Off

In linear backoff, the time between retries increases at a steady, predictable rate.
Typically, this delay grows based on the retry attempt number.

For example, if we start with a 1-second base delay, the first retry waits 1 second, the second waits 2 seconds, the third waits 3 seconds, and so on.

This approach is slightly better than constant backoff for reducing immediate contention, especially when multiple clients are retrying around the same time. The gradually increasing delays can help space out retry attempts just enough to give a struggling server a breather.

But linear backoff isn’t without flaws.

It still suffers from the same core issue as constant back off, many clients can still retry in sync, especially if they all follow the same retry pattern. This makes it vulnerable to retry storms (also called thundering herd problems) under high traffic.

Another problem is that it ramps up too slowly.

If a service is seriously struggling, say it’s under heavy load or temporarily offline, your app is still retrying too often. The delays (1s, 2s, 3s…) aren’t big enough to give the service time to breathe.

In those situations, what you really need is a more aggressive approach, one that quickly increases the wait time between retries.

BASE_DELAY = 1


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    for i in range(1, MAX_RETRIES + 1):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i}] Transient failure with {response.status_code}. Retrying..."
        )

        time.sleep(BASE_DELAY + i - 1)

    return response

Exponential Back Off

With exponential backoff, the delay between retries grows exponentially with each attempt.
A common pattern uses a base of 2: so you’d wait 1 second, then 2 seconds, then 4, 8, 16… and so on, usually up to a defined maximum delay.

This strategy is much better at reducing pressure on struggling systems. As the delay increases, the retry frequency slows down significantly, which gives the service more time to recover. It also greatly lowers the chances of multiple clients retrying at the same time, which helps avoid retry storms.

Because of this, exponential back off is well-suited for high-load, distributed systems, and is often the go-to strategy for handling transient errors in production environments.

However, it’s not perfect.

If the issue resolves quickly, say after a very brief glitch, you might still be stuck waiting longer than necessary for the next retry. That’s the trade off: we gain resilience, but sometimes at the cost of speed.

def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    for i in range(1, MAX_RETRIES + 1):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i}] Transient failure with {response.status_code}. Retrying..."
        )

        time.sleep(2**i - 1)

    return response

Jitter

At this point, you're probably thinking:

Okay, you used the word "jitter" in the title, but what the hell is it?

And listen, there’s a reason I have the billion-dollar app and you don’t.
(Kidding. Mostly.)

Jokes aside, jitter is all about introducing randomness into your back off delays.

Up until now, all our retry strategies have been very... predictable. Constant. Linear. Exponential. If ten clients fail at the same time, they’ll all retry at the same time. Again. And again. And again. That predictability is exactly what causes retry storms (aka thundering herds).

Jitter shakes things up.

Instead of waiting exactly 4 seconds after the 3rd retry, for example, we might wait somewhere between 0 and 4 seconds. Each client gets a slightly different delay, so retry attempts are spread out rather than stacked on top of each other.

This reduces the chance of all clients hitting the server simultaneously, like traffic lights going green at staggered times instead of all at once.

It's most commonly paired with exponential back off, where the delays grow quickly and predictably.
But hey, with enough creativity (or chaos), you can slap jitter onto just about any back off strategy.

Full Jitter

With full jitter, we take the calculated exponential back off delay, and then add randomness.

More specifically, we pick a random value between 0 and the current exponential delay. This spreads retries out nicely across time and makes it much less likely that multiple clients will retry at the same moment.

It’s easy to implement, and it significantly improves resilience in distributed systems by reducing congestion and maximizing the spread of retry attempts.

But like everything, it has its trade-offs.

Since the delay is random between 0 and the upper bound, it’s possible for some retries to happen almost immediately.
If you're in a situation where you need a minimum wait time, this can be a problem.
Also, without a cap, the exponential growth can cause delays to become unreasonably long. That’s why most implementations include a cap to limit how big the delay can get.

delay = random(0, min(cap, base * 2^attempt))

Where:
- cap: This is maximum delay between requests
- base: The initial delay for the first retry
- attempt: The current attempt retry number

MAX_DELAY = 5


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    for i in range(MAX_RETRIES):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i+1}] Transient failure with {response.status_code}. Retrying..."
        )

        # Here our base delay is 1
        delay = random.randint(0, min(MAX_DELAY, 2**i))
        time.sleep(delay)

    return response

Equal Jitter

This strategy guarantees a minimum delay, then adds some randomness on top. The idea is to split the calculated delay in half: use one half as the minimum wait, and the other half as the random spread. This way, we avoid retries happening almost instantly, which can still happen with full jitter.

base_delay = min(cap, base * 2^attempt) / 2
delay = base_delay + random(0, base_delay)

With this, all retries wait at least half of the calculated delay, and then add a random amount on top. This prevents very short delays and still spreads out retry attempts, reducing the chance of retry storms.

Equal jitter strikes a balance between responsiveness and stability: it ensures a consistent minimum wait time while still adding some randomness. That said, it has its downsides. Compared to full jitter, the range of delays is narrower, and average delays tend to be longer, since we avoid those short, fast retries.

MAX_DELAY = 5


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    for i in range(MAX_RETRIES):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i}] Transient failure with {response.status_code}. Retrying..."
        )

        base_delay = min(MAX_DELAY, 2**i) // 2
        delay = base_delay + random.randint(0, base_delay)
        time.sleep(delay)

    return response

Decorrelated Jitter

This is a rare but intriguing variation. Its main goal is to further spread out retry attempts by making the delay depend not only on the current attempt, but also on the previous delay value. This creates a more dynamic and adaptive retry strategy.

delay = min(cap,random(base,previous_sleep×3))

The result is a wider and more irregular spread of retries. Like full jitter, it’s highly effective at reducing retry storms, but it takes a different approach, the randomness is influenced by the delay used in the last attempt.

Pros:

Adapts to runtime behavior, since each delay depends on the last.
Excellent at avoiding retry synchronization.
Offers extreme desynchronization, which can be valuable in some high-concurrency environments.

Cons:

Less predictable, which may be undesirable in some systems.
Can lead to very long delays, especially if a previous delay was high.
Introduces statefulness, since the previous delay must be tracked, unlike pure stateless strategies like full or equal jitter.
Slightly harder to reason about and implement correctly.

In short, decorrelated jitter is powerful, but should be used sparingly, when data or experience shows that your system would benefit from maximum spread and desync in retries.

MAX_DELAY = 5
BASE_DELAY = 2


def collect_money(
    headers: dict[str, str], payload: dict[str, Any]
) -> requests.Response:
    url = "https://important.com/api/v1/path"

    previous_delay = BASE_DELAY

    for i in range(MAX_RETRIES):
        response = requests.post(url, headers=headers, data=payload)

        if response.status_code == HTTPStatus.OK:
            return response

        if response.status_code not in RETRYABLE_STATUS_CODES:
            return response

        print(
            f"[Attempt: {i}] Transient failure with {response.status_code}. Retrying..."
        )

        delay = min(MAX_DELAY, random.randint(BASE_DELAY, previous_delay * 3))
        time.sleep(delay)
        previous_delay = delay

    return response

Let’s wrap this up with a few parting thoughts:

Not every error deserves a retry. Before you blindly try again, make sure retrying makes sense for the failure, some errors are permanent or unrecoverable.
Always cap your retries. Set a finite number of attempts that makes sense for the system. Too few might miss recoverable errors; too many might hammer a broken service.
Don't retry instantly. After a failure, give it a moment. Backing off gives systems a chance to recover, but don’t wait forever either.
Add some randomness. This spreads out retry attempts across clients and helps prevent the dreaded retry storm (also called a thundering herd).
Use the right tool for the job. You don’t need exponential back off with decorrelated jitter for a script running on your laptop. Don’t jump through invisible hoops. Keep it practical, not theatrical.
This isn’t just for APIs. Back off strategies apply to all kinds of networked systems, message queues, database connections, RPC calls, IoT, and more. Anywhere you're making requests across a flaky boundary, these principles can help.

Go Routing 101: Handling and Grouping Routes with net/http

Kengo Wada — Sat, 02 Nov 2024 13:17:43 +0000

Go 1.22 brings two enhancements to the net/http package’s router: method matching and wildcards. These features let you express common routes as patterns instead of Go code. Although they are simple to explain and use, it was a challenge to come up with the right rules for selecting the winning pattern when several match a request.

Go 1.22 added new features to their net/http package to make it a good alternative to using third-party libraries. In this article, we will look at how to handle routing using Golang's net/http package. We will start with the basic route handling and then move on to grouping those routes.

Notes

This assumes you're using Go version >= 1.22
The repo for more details

Basic Routing

Let us start by looking at how to register your routes.

// main.go
package main

import (
    "log"
    "net/http"
)

func main() {
    router := http.NewServeMux()

    router.HandleFunc("GET /users/", getUsers)
    router.HandleFunc("POST /users/", createUser)
    router.HandleFunc("GET /users/{id}/", getUser)
    router.HandleFunc("DELETE /users/{id}/", deleteUser)

    err := http.ListenAndServe(":8000", router)
    if err != nil {
        log.Fatal(err)
    }
}

// Here goes the implementation for getUsers, getUser, createUser, deleteUser
// Check the repo in services/users/routes.go

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

var users []User = []User{
    {ID: 1, Name: "Bumblebee", Email: "bumblebee@autobots.com"},
    {ID: 2, Name: "Optimus Prime", Email: "optimus.prime@autobots.com"},
    {ID: 3, Name: "Ironhide", Email: "ironhide@autobots.com"},
    {ID: 4, Name: "Hot Rod", Email: "hot.rod@autobots.com"},
}

func getUsers(w http.ResponseWriter, r *http.Request) {
    response := map[string]any{
        "message": "Done",
        "users":   users,
    }
    utils.WriteJSONResponse(w, http.StatusOK, response)
}

Let's go through the above code:

router := http.NewServeMux() This creates a new request multiplexer. When a request is made, the router examines the request’s URL and selects the most appropriate handler to serve the request.
router.HandleFunc("GET /users/", getUsers) This registers the /users/ route and indicates that this will be a GET method route.
utils.WriteJSONResponse This is a utility function to create a JSON response and can be found in the repo in utils/utils.go

Note: When making requests make sure to add the trailing slash. Doing otherwise will return a 404 not found response
Example:

http://localhost:8000/users returns 404
http://localhost:8000/users/ returns the correct server response

Sample Request:

Request: GET http://localhost:8000/users/
Response:

// statusCode: 200
{
    "message": "Done",
    "users": [
        {
            "id": 1,
            "name": "Bumblebee",
            "email": "bumblebee@autobots.com"
        },
        {
            "id": 2,
            "name": "Optimus Prime",
            "email": "optimus.prime@autobots.com"
        },
        {
            "id": 3,
            "name": "Ironhide",
            "email": "ironhide@autobots.com"
        },
        {
            "id": 4,
            "name": "Hot Rod",
            "email": "hot.rod@autobots.com"
        }
    ]
}

Grouping Routes

As we can see from the above, this would require us to register all endpoints in the same place and can get out of hand quickly. Grouping routes helps you keep your code organized, scalable, and maintainable by putting related routes and logic together. It allows you to apply middleware selectively, encourages reusability, and improves readability, especially as your application grows.
Now let us look at how we can group routes

We will start by registering routes locally in the package where their handler functions are defined. The next step is to bring all those various routes together and start the server.

// services/users/routes.go
package user

import (
    "fmt"
    "net/http"
    "strconv"

    "<your-project-name>/gorouting/utils"
)

type Handler struct{}

func NewHandler() *Handler {
    return &Handler{}
}

func (h *Handler) RegisterRoutes() *http.ServeMux {
    r := http.NewServeMux()
    r.HandleFunc("GET /", getUsers)
    r.HandleFunc("POST /", createUser)

    r.HandleFunc("GET /{id}/", getUser)
    r.HandleFunc("DELETE /{id}/", deleteUser)

    return r
}
// ...

Let's go through the code.

func NewHandler() *Handler This creates a new Handler that is used for dependency injection such as adding access to a database should one be present.
func (h *Handler) RegisterRoutes() *http.ServeMux Here we create a new ServeMux and register routes.

// cmd/api/api.go
package api

import (
    "log"
    "net/http"

    "<your-project-name>/services/user"
)

type APIServer struct {
    addr string
}

func NewAPIServer(addr string) *APIServer {
    return &APIServer{addr: addr}
}

func (s *APIServer) Run() error {
    userHandler := user.NewHandler()
    userRouter := userHandler.RegisterRoutes()

    router := http.NewServeMux()
    router.Handle("/users/", http.StripPrefix("/users", userRouter))

    log.Println("Starting server on port", s.addr)
    return http.ListenAndServe(s.addr, router)
}

Here we are going to focus on the Run method.

userHandler := user.NewHandler() This creates a new handler and this is the point where things like database connections can be passed along to the endpoints that need them. This is called dependency injection.
userRouter := userHandler.RegisterRoutes() This creates a ServeMux containing the user routes.
router.Handle("/api/v1/users/", http.StripPrefix("/api/v1/users", userRouter)) This registers the users with the base URL of /users/. StripPrefix removes the specified prefix from the request URL before routing it to userRouter.

// cmd/main.go
package main

import (
    "log"

    "<your-project-name>/cmd/api"
)

func main() {
    server := api.NewAPIServer(":8000")
    if err := server.Run(); err != nil {
        log.Fatal(err)
    }
}

“With Go 1.22, net/http is now more versatile, offering route patterns that improve clarity and efficiency. This approach to grouping routes shows how easy it is to maintain scalable code while taking advantage of Go’s built-in routing capabilities.” ChatGPT

Now that we have managed to group the user routes. Clone the repo and try adding another service.

GORM and Goose Migrations

Kengo Wada — Sun, 12 May 2024 10:02:31 +0000

Let's get started with handling migrations in Go with GORM and Goose.

Prerequisites

Go installed
GORM Supported SQL Database(I'll be using Postgresql)

Note:
You may refer to this repo for the file structure.

Install Goose Locally

Follow the steps here to install Goose for your operating system.

I tried using the installation script with Ubuntu 20.04 but I run into errors and found a solution here

wget http://github.com/golang-migrate/migrate/releases/latest/download/migrate.linux-amd64.deb
sudo dpkg -i migrate.linux-amd64.deb

goose --help // To test if install went well.

Start Dummy Project

Create a directory

mkdir app
cd app

Initialize it as a Go project

go mod init app

Create main.go in the root of your project

package main

func main() {

}

Getting Started With GORM

Create database directory

mkdir database
cd database
touch postgres.go

Add the following to database/postgres.go

package database

import (
    "database/sql"
    "os"

    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

var dbURL := os.Getenv("GOOSE_DBSTRING")

var GORM_DB *gorm.DB
var SQL_DB *sql.DB
var DB_MIGRATOR gorm.Migrator

func ConnectToDatabase() (error) {
    db, err := gorm.Open(postgres.Open(dbURL), &gorm.Config{})
    if err == nil {
        GORM_DB = db
        SQL_DB, _ = db.DB()
        DB_MIGRATOR = db.Migrator()
    }
    return err
}

At this point you'll have failed import errors, so let's fix that

go mod tidy

Now create env in your projects root directory

mkdir env
touch env/goose.env

Add the following to env/goose.env

export GOOSE_DRIVER='postgres'
export GOOSE_DBSTRING='postgres://user:password@localhost:5432/db_name?sslmode=disable'
export GOOSE_MIGRATION_DIR='./migrations'

Now source the environment variables

source env/goose.env

Creating Models and Migrations

Create a models directory in your projects root directory

mkdir models
touch models/user.go

Add the following to models/user.go

package models

import (
    "gorm.io/gorm"
)

type User struct {
    *gorm.Model
    Name     string
    Email    string
    Password string
}

Now run goose command to create migration file

mkdir migrations
goose -s create create_user

After this, you'll have import errors. Let's fix this

go mod tidy

Update the 00001_create_user.go file to have the following

package migrations

import (
    "app/database"
    "app/models"
    "context"
    "database/sql"

    "github.com/pressly/goose/v3"
)

func init() {
    goose.AddMigrationContext(upCreateUser, downCreateUser)
}

func upCreateUser(ctx context.Context, tx *sql.Tx) error {
    return database.DB_MIGRATOR.CreateTable(&models.User{})
}

func downCreateUser(ctx context.Context, tx *sql.Tx) error {
    return database.DB_MIGRATOR.DropTable(&models.User{})
}

Bringing It All Together

Update the main.go file to have the following

package main

import (
    "app/database"
    _ "app/migrations" // This loads the migrations init functions

    "github.com/pressly/goose/v3"
)

func main() {
    err := database.ConnectToDatabase()
    if err != nil {
        panic(err)
    }

    if err := goose.SetDialect("postgres"); err != nil {
        panic(err)
    }
    if err := goose.Up(database.SQL_DB, "migrations"); err != nil {
        panic(err)
    }
    // Start server...
}

Now you can run migrations before starting the server

go run .