# Purpose of this article

In this article I want to give you a taste of what building Go web applications with [Echo](https://echo.labstack.com/) framework looks like. It is **hard and time** consuming to go through the entire documentation of a framework to just get the feel of what it is like and if the framework is for you. 

We will use the example of a Todo app for demonstration covering topics like **routing**, **middleware**, **authentication**, **path/query parameters**, **request body** and more. The complete example application can be found in [this](https://github.com/gurleensethi/echo-todo) github repository.

## Why a todo app?

I have seen a lot of hate 😠 towards todo apps being used as an example in tutorials and courses. Todo apps are a great way to showcase the technology/framework to the reader **without requiring the reader to gain additional context of the project**. When you read "todo app" you already know the what the requirements are. Additionaly todo apps cover the most common operations of framework/libraries which is **CRUD** (create, read, update, delete) data.

# Project Setup

Create a new project using `go mod init <your_module_name>` and install the echo framework.

```shell
go get github.com/labstack/echo/v4
go get github.com/labstack/echo/v4/middleware
```

# Setting up a Data Store

You need a way to store/manage the todos, you will not be using a database as that is not the focus of this article, you will be storing the data **in-memory**.

Create file in the **main** package itself called `todomanager.go` and paste the following code in it. We have something called a `TodoManager`, we will be adding all the CRUD operations as functions on this `TodoManager` so give this code a good read.

```go:todomanager.go
package main

import (
	"sync"
)

// Todo represents our todo
type Todo struct {
	ID         string `json:"id"`
	Title      string `json:"title"`
	IsComplete bool   `json:"isDone"`
}

type TodoManager struct {
	todos []Todo
	m     sync.Mutex // we want all our operations to be atomic
}

func NewTodoManager() TodoManager {
	return TodoManager{
		todos: make([]Todo, 0),
		m:     sync.Mutex{},
	}
}
```

# Setting up Echo

Now you are going to set up a simple http server using `echo`.

```go:main.go
package main

import (
	"github.com/labstack/echo/v4"
)

func main() {
	e := echo.New()

	e.Start(":8888")
}
```

Run the code using `go run main.go`. This will start an http server on port `8888` and you should see the following output in your terminal.

```shell
   ____    __
  / __/___/ /  ___
 / _// __/ _ \/ _ \
/___/\__/_//_/\___/ v4.9.0
High performance, minimalist Go web framework
https://echo.labstack.com
____________________________________O/_______
                                    O\
⇨ http server started on [::]:8888
```

# Building the app

Let's start adding functionality to the app. The steps will be quite similar for all of the operations: **1.** Add a function in `TodoManager`, **2.** Add an api endpoint in echo.

The code snippets below will only showcase new additions and leave out the already written code, if you feel lost or want to see the enitre working thing head over to the [this](https://github.com/gurleensethi/echo-todo) GitHub repo that contains the complete working example.

## Get all the todos

Inside `TodoManager` add a function to return all todos.

```go:todomanager.go
...

func (tm *TodoManager) GetAll() []Todo {
	return tm.todos
}
```

Add a `GET` route on echo.

```go:main.go
package main

import (
	"net/http"

	"github.com/labstack/echo/v4"
)

func main() {
	tm := NewTodoManager() // 👈 instance of todo manager

	e := echo.New()

	// 👇 new GET route
	e.GET("/", func(c echo.Context) error {
		todos := tm.GetAll()

		return c.JSON(http.StatusOK, todos) // 👈 sending json data back
	})
    
	e.Start(":8888")
}
```

It is as simple as using the `GET` function on **echo** and providing it with a **route path** and a **function**. 

**Note:** The function signature has a single parameter of type `echo.Context`, it is not your standard `func(http.ResponseWriter, *http.Request)` signature.

Let's send a curl request and see the output.

```bash
❯ curl -s localhost:8888/ | jq

[]
```

As expected you will see an empty array because there is no todo yet 🤷‍♂️.

## Middleware to log all requests

**Echo** has the concept of middlewares which are functions that run before the actual request function.

Let's set up a middleware to **log all the requests** to terminal.

You will be using an inbuilt middleware provided by **echo** (you will see an example of a custom middleware later) from its `github.com/labstack/echo/v4/middleware` package.

```go:main.go
package main

import (
	"net/http"

	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

func main() {
	tm := NewTodoManager()

	e := echo.New()

	e.Use(middleware.Logger()) // 👈 log all requests

	e.GET("/", func(c echo.Context) error {
		todos := tm.GetAll()

		return c.JSON(http.StatusOK, todos)
	})

	e.Start(":8888")
}
```

If you send a request again you should see a json object being printed in the standard output.

```shell
{"time":"2022-09-08T04:07:37.20349-04:00","id":"","remote_ip":"127.0.0.1","host":"localhost:8888","method":"GET","uri":"/","user_agent":"curl/7.79.1","status":200,"error":"","latency":72063,"latency_human":"72.063µs","bytes_in":0,"bytes_out":3}
```

Echo has a number of built in middlewares, check out the documentation on middleware [here](https://echo.labstack.com/middleware/).

## Authenticated routes

Before we proceed adding additional routes in our application, let's talk about authentication. I am not going to discuss how to do authentication (not the focus of this article). I am going to show you how to make **routes accessible only by logged in user**.

⭐️ A common pattern in backend applications is to pass an **auth token** as a header in every request, `Authorization: <auth_token>`.

You will use [Echo Groups](https://echo.labstack.com/guide/routing/#group) to group together routes that require authentication and add a custom middleware that will check for the presence of an auth token, for simplicity it will be a simple string equality check.

```go:main.go
func main() {
	...
    
	authenticatedGroup := e.Group("/todos", func(next echo.HandlerFunc) echo.HandlerFunc {
		return func(c echo.Context) error {
        	// 👇 check for auth token
			authorization := c.Request().Header.Get("authorization")
			if authorization != "auth-token" {
				c.Error(echo.ErrUnauthorized)
				return nil
			}
            
            // 👇 token exists, keep moving forward
			next(c)
			return nil
		}
	})

	...
}
```

Any routes added onto `authenticatedGroup` will have the **middleware executed before the actual route** is executed.

In this middleware, there is a check for `authentication` header, if the header is empty or not valid an error is returned using echo's `c.Error`.

Sending a request without a header will give you back this response.

```bash
❯ curl -s localhost:8888/todos/ | jq

{
  "message": "Unauthorized"
}
```

## Create new todo

Using the previous **authenticated group** add a route to create a new todo.

Let's take care of the `TodoManager` part by adding a `Create` function.

```go:todomanager.go
// 👇 required data to create new todo
type CreateTodoRequest struct {
	Title string `json:"title"`
}

func (tm *TodoManager) Create(createTodoRequest CreateTodoRequest) Todo {
	tm.m.Lock()
	defer tm.m.Unlock()

	newTodo := Todo{
		ID:         strconv.FormatInt(time.Now().UnixMilli(), 10),
		Title:      createTodoRequest.Title,
		IsComplete: false,
	}

	tm.todos = append(tm.todos, newTodo)

	return newTodo
}
```

Now set up a `POST` route which will parse the request body and call the `TodoManager.Create` function.

```go:main.go
func main() {
	...

	authenticatedGroup.POST("/create", func(c echo.Context) error {
		requestBody := CreateTodoRequest{}

		// 👇 parses the body and "binds" it to the passed type
		err := c.Bind(&requestBody)
		if err != nil {
			return err
		}

		todo := tm.Create(requestBody)
        
		return c.JSON(http.StatusCreated, todo)
	})

    ...
}
```

Since this create route is on the **group** that requires **authentication** you need to pass the auth token. Making the request using `curl`, you get back a new todo.

```bash
❯ curl -s -X POST localhost:8888/todos/create \
  -H "Content-Type: application/json" \
  -H "Authorization: auth-token" \
  -d '{ "title": "Todo Title" }' \
  | jq

{
  "id": "1662719050096",
  "title": "Todo Title",
  "isDone": false
}
```

Fetch all the todos using the `GET /` endpoint.

```bash
❯ curl -s localhost:8888/ | jq

[
  {
    "id": "1662719050096",
    "title": "Todo Title",
    "isDone": false
  }
]
```

## Complete a todo

Now you will add a new `PATCH /todos/:id/complete` endpoint that marks a todo as complete. Here you will see how to parse **path parameters** in echo.

First add a new function `Complete(ID string)` in the `TodoManager`.

```go:todomanager.go
func (tm *TodoManager) Complete(ID string) error {
	tm.m.Lock()
	defer tm.m.Unlock()

	// Find the todo with id
	var todo *Todo
	var index int = -1

	for i, t := range tm.todos {
		if t.ID == ID {
			todo = &t
			index = i
		}
	}

	if todo == nil {
		return echo.ErrNotFound
	}

	// Check todo is not already completed
	if todo.IsComplete {
		err := echo.ErrBadRequest
		err.Message = "todo is already complete"
		return err
	}

	// Update todo
	tm.todos[index].IsComplete = true

	return nil
}
```

**Notice** that the errors being returned are from echo itself, `echo.ErrNotFound` and `echo.ErrBadRequest`. If these errors are passed to echo's `e.Error` function, echo will automatically set the appropriate **status code** and message in the response.

```go:main.go
func main() {
	...

	authenticatedGroup.PATCH("/:id/complete", func(c echo.Context) error {
		id := c.Param("id") // 👈 getting the path parameter

		err := tm.Complete(id)
		if err != nil {
			c.Error(err)
			return err
		}

		return nil
	})

	...
}
```

The value path parameter (`id`) is being grabbed by using `c.Param` function. There is a similar function in echo called **`c.QueryParam`** to get values of query parameters.

```bash
❯ curl -i -X PATCH localhost:8888/todos/1662757576599/complete \
-H "Content-Type: application/json" \
-H "Authorization: auth-token" 

HTTP/1.1 200 OK
Date: Fri, 09 Sep 2022 21:06:25 GMT
Content-Length: 0
```

## Deleting a todo

Add a function in `TodoManager` to remove a todo.

```go:todomanager.go
func (tm *TodoManager) Remove(ID string) error {
	tm.m.Lock()
	defer tm.m.Unlock()

	index := -1

	for i, t := range tm.todos {
		if t.ID == ID {
			index = i
			break
		}
	}

	if index == -1 {
		return echo.ErrNotFound
	}

	tm.todos = append(tm.todos[:index], tm.todos[index+1:]...)

	return nil
}
```

Add a route on authenticated group to delete a the todo.

```go:main.go
func main() {
	...
    
	authenticatedGroup.DELETE("/:id", func(c echo.Context) error {
		id := c.Param("id")

		err := tm.Remove(id)
		if err != nil {
			c.Error(err)
			return err
		}

		return nil
	})

	...
}
```

Just like the complete todo endpoint you are parsing the path parameter using `c.Param`.

```bash
❯ curl -i -X POST localhost:8888/todos/1662763466488 \
-H "Content-Type: application/json" \
-H "Authorization: auth-token"

HTTP/1.1 200 OK
Date: Fri, 09 Sep 2022 22:44:33 GMT
Content-Length: 0
```

---

I hope this article gave you a good overview of [echo](https://echo.labstack.com/) framework, there is so much more you can do with echo, if you are interested visit the echo's official page [here](https://echo.labstack.com/).

In this article I want to give you a taste of what building Go web applications with Echo framework looks like. Sometimes it quite tedious and time consuming

Echo - A Go web framework - Todo App

# Getting Started

In this article I am going to show you how to embed static files inside a Go binary. Embedding files can serve many purposes such as embedding a React app and serving it over http all inside a single Go binary.

# Embed a single file

We will start by embedding a single file and print it out to standard output.

Let's prepare a simple index.html static file.

```html:index.html
<html>
  <head>
      <title>Embedded File</title>
  </head>
  <body>
      <h1>Hello from Go!</h1>
  </body>
</html>
```

Write the Go code to embed the file.

```go:main.go
package main

import (
	_ "embed"
	"fmt"
)

//go:embed index.html
var staticFile string

func main() {
	fmt.Println(staticFile)
}
```

For embedding to work you need three things:

1. Import the `embed` package (`import _ "embed"`).
2. A variable to hold the data of embedded file (`var staticFile string`).
3. Using comment specify which file to import `//go:embed index.html`. The comment goes right above the variable.

**Note: Both `main.go` and `index.html` are in the same directory. Go will look for the file relative to the `main.go` file.**

Build the binary using `go build` and run it, the html file will be the output.

```txt
<head>
    <title>Embedded File</title>
</head>
<body>
    <h1>Hello from Go!</h1>
</body>
</html>
```

There are 3 valid types for the variable that holds embedded file: `string`, `[]byte` and `embed.FS`.

# Embed a directory

Instead of embedding a single file, we can embed an entire directory. 

Let's prepare a directory, create a new `static` folder and place the `index.html` file in it.

Create a new `page.html` file in the `static` folder.

```html:static/page.html
<html>
    <head>
        <title>Embedded File</title>
    </head>
    <body>
        <h1>Page</h1>
    </body>
</html>
```

So the folder structure looks like this.

```txt
static
  |- index.html
  |- page.html
main.go
```

Since we are embedding a directory we will use `embed.FS` type here.

```go:main.go
package main

import (
	"embed"
	"fmt"
)

//go:embed static
var fs embed.FS

func main() {
	files, _ := fs.ReadDir("static")

	for _, f := range files {
		fmt.Println(f.Name())
	}
}
```

`embed.FS` has a function called `ReadDir` that lists the content of a directory, in the above code example we list all the files inside the `static` folder.

The output will be:

```txt
index.html
page.html
```

**Reading one of the files from the directory**

```go:main.go
package main

import (
	"embed"
	"fmt"
)

//go:embed static
var fs embed.FS

func main() {
	file, _ := fs.ReadFile("static/index.html") // 👈
	fmt.Println(string(file))
}
```

# Embed multiple directories

You can go one step ahead and embed multiple folders. Let's create a new `static2` folder and paste the same `index.html` folder.

```go:main.go
package main

import (
	"embed"
	"fmt"
)

//go:embed static static2
var fs embed.FS

func main() {
	files, _ := fs.ReadDir(".")

	for _, f := range files {
		fmt.Println(f.Name())
	}
}
```

In the embedding comment, specify another folder separated with a space `//go:embed static static2`.

The output will be:

```txt
static
static2
```

# Serve embedded directory over http

We can take advantage of this embedding feature and serve our static files over http using.

```go:main.go
package main

import (
	"embed"
	"net/http"
)

//go:embed static
var fs embed.FS

func main() {
	http.Handle("/", http.FileServer(http.FS(fs)))
	http.ListenAndServe(":8080", nil)
}
```

Visit `http://localhost:8080/static/index.html` in your browser to see the file in action.

Read more about `embed` package and its functionality on the official docs [here](https://pkg.go.dev/embed).

Thank you for reading this article 🙏🏻 please consider joining the mailing list below.

In this article I am going to show you how to embed static files inside a Go binary. Embedding files can serve many purposes such as embedding a React app...

Embed file in a Go binary

# Getting Started

If you have been writing Go you probably have heard of the popular http router [chi](https://go-chi.io/#/). In this article you are going to learn how to print all the routes registered in a router, this is very helpful for debugging purposes.

If you want to learn about chi, please read [Restful routing with Chi](https://thedevelopercafe.com/articles/restful-routing-with-chi-in-go-d05a2f952b3d).

# Setting up a router

I assume you have a project with **chi** setup (if not please [install chi](https://go-chi.io/#/pages/getting_started)).

Let's assume an application that has a router with 3 routes registered.

```go:main.go
package main

import (
	"fmt"
	"github.com/go-chi/chi/v5"
	"net/http"
)

func main() {
	router := chi.NewRouter()

	router.Get("/articles", sayHello)
	router.Get("/articles/{articleID}", sayHello)

	router.With(func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			next.ServeHTTP(w, r)
		})
	}).Post("/articles", sayHello) // 👈 route with middleware
}

func sayHello(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Hello World"))
}
```

Look closely one of these routes (`POST` route) has a middleware setup as well. So now we want to print out **all** the routes and the **number** of middlewares setup on each routes.

# Print routes with chi.Walk

We want to print each route in the format: `[<method>]: '<route>' has <x> middlewares`.

Chi provides a built in function called [`chi.Walk`](https://github.com/go-chi/chi/blob/master/tree.go#L827-L863) that traverses the route tree and calls a calback function for each route.

It has a long function signature so scroll the code below to the right to see it all.

```go
chi.Walk(router, func(method string, route string, handler http.Handler, middlewares ...func(http.Handler) http.Handler) error {
	fmt.Printf("[%s]: '%s' has %d middlewares\n", method, route, len(middlewares))
	return nil
})
```

**chi** will call the passed function for each route and our `fmt` statement inside it will print the required information.

Putting it together the entire example looks like this.

```go:main.go
package main

import (
	"fmt"
	"github.com/go-chi/chi/v5"
	"net/http"
)

func main() {
	router := chi.NewRouter()

	router.Get("/articles", sayHello)
	router.Get("/articles/{articleID}", sayHello)

	router.With(func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			next.ServeHTTP(w, r)
		})
	}).Post("/articles", sayHello)

	// 👇 the walking function 🚶‍♂️
	chi.Walk(router, func(method string, route string, handler http.Handler, middlewares ...func(http.Handler) http.Handler) error {
		fmt.Printf("[%s]: '%s' has %d middlewares\n", method, route, len(middlewares))
		return nil
	})
}

func sayHello(w http.ResponseWriter, r *http.Request) {
	w.Write([]byte("Hello World"))
}
```

And will print the following output.

```txt
[GET]: '/articles' has 0 middlewares
[POST]: '/articles' has 1 middlewares
[GET]: '/articles/{articleID}' has 0 middlewares
```

Thank you for reading this article 🙏🏻 hope it was helpful.

If you have been writing Go you probably have heard of the popular http router chi. In this article you are going to learn how to print all the routes...

Print all routes in Chi router

# Getting Started

[SQLBoiler](https://github.com/volatiletech/sqlboiler) is a package that introspects your database schema and generates a static ORM client. In this article I am going to give you a taste of SQLBoiler, this is not an in-depth article on **SQLBoiler** (that will come later).

Below is what the workflow looks like with **SQLBoiler**.

![Go SQLBoiler workflow](https://tdc-public.nyc3.digitaloceanspaces.com/photos/a3513976-0029-4706-bdd8-37c88eaf6229-go-sqlboiler-workflow.png)

I highly recommend you to follow the article and replicate everything on your local machine. The code for this article is available in this [GitHub repository](https://github.com/gurleensethi/go-sql-boiler-example), please go ahead and clone it.

This is a fairly information packaged article 📦 so give some good amount of time to read it.

# Installing SQLBoiler CLI tool

To generate the static ORM client you need the SQLBoiler cli, install it using `go install`.

```bash
go install github.com/volatiletech/sqlboiler/v4@latest
```

SQLBoiler requires you to install a driver based on the database you are using (list of [supported databases](https://github.com/volatiletech/sqlboiler#supported-databases) by SQLBoiler).

We will be using PostgreSQL for this article, install the postgres driver.

```bash
go install github.com/volatiletech/sqlboiler/v4/drivers/sqlboiler-psql@latest
```

CLI part is all done ✅ let's move on to the project.

# Project Setup

SQLBoiler reads the schema directly from your database. We need a database with a schema. I am not going to spend time on schema creation.

I have already provided a **sample schema** in the GitHub repository of this article, all you need is **Docker** installed on your machine. Make sure you have cloned [this repository](https://github.com/gurleensethi/go-sql-boiler-example).

## Setting up database

Once the project is cloned, run `docker compose up` in the project folder and you will have the database ready to go.

Here are the `create table` queries that run behind the scenes.

```sql
CREATE TABLE author(
  id serial primary key,
  email varchar not null,
  name varchar not null
);

CREATE TABLE article(
  id serial primary key,
  title varchar not null,
  body text,
  created_at timestamp default now(),
  author_id int not null,
  constraint fk_author_id foreign key(author_id) references author(id)
);
```

You have got two tables, `author` and `article`, the relationship between them is pretty self explanatory.

![Go SQLBoiler Schema](https://tdc-public.nyc3.digitaloceanspaces.com/photos/015d093e-7241-43fc-b3d8-ec59f17d25db-go-sqlboiler-schema.png){.center .large}

## Setting up go project

Go ahead a create a new `go` project and initialize it with `go mod init` as we will be installing a handful of packages.

Install the following packages in the project.

```bash
go get github.com/lib/pq
go get github.com/volatiletech/sqlboiler/v4
go get github.com/volatiletech/null/v8
```

- [`github.com/lib/pq`](https://github.com/lib/pq) is the go postgres driver, if you have ever wrote `SQL` in `Go`, you know you need a database driver.
- [`github.com/volatiletech/sqlboiler/v4`](https://github.com/volatiletech/sqlboiler/) is the SQLBoiler package, the generated ORM code relies on this package.
- [`github.com/volatiletech/null/v8`](https://github.com/volatiletech/null) is package for better handling of `nil` types in `Go`.

Next, create the `main.go` file.

```go:main.go
package main

import (
	_ "github.com/lib/pq"
)

func main() {
}
```

# Generating Code with SQLBoiler

Before we generate the ORM client, we need to tell **SQLBoiler** how to connect to our database i.e. we need a configuration file, SQLBoiler stores it configuration in file called `sqlboiler.toml`.

## Creating SQLBoiler configuration file

Create a new file called `sqlboiler.toml`. I have documented what each property means in the code below.

```toml:sqlboiler.toml
# Directory in which the generated static code is to be kept.
output = "db/models" 

# Each time new code is generated, completely wipe out the old one.
wipe = true

# The `go` package name used in the generated code.
pkgname = "dbmodels"

# Adds global variant of the generated functions, more on this later.
add-global-variants = true

# Generates code for enum types as well.
add-enum-types = true

# This is the postgres config, which should be self explanatory.
[psql]
dbname = "postgres"
host = "localhost"
port = 2345
user = "postgres"
pass = "postgres"
sslmode = "disable"
```

## Generating the static ORM

Now that cli is installed and the configuration file is setup, you can generate the ORM client.

```bash
sqlboiler psql 
```

This will generate the static code in `db/models` directory 🎉. You can take a look at the generated code [here](https://github.com/gurleensethi/go-sql-boiler-example/tree/main/db/models).

# Using generated code

Now is the juciy part 😋 let's start uing the generate code.

First of all let's write some initialization code.

```go:main.go
package main

import (
	"database/sql"

	_ "github.com/lib/pq"
	"github.com/volatiletech/sqlboiler/v4/boil"
)

func main() {
	db := connectDB()

	boil.SetDB(db)
}

func connectDB() *sql.DB {
	db, err := sql.Open("postgres", "postgres://postgres:postgres@localhost:2345/postgres?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}
	return db
}
```

`connectDB` is a function that relies on `Go`'s inbuilt `sql` package to connect to the postgres database.

> **Global variants**: `boil.SetDB(db)` is an interesting one, so **SQLBoiler** can generate *global variants* of the functions, these functions are appended with a `G` at the end of the function name. For example the **Insert** function will have a **InsertG** variant, the difference is that when using **Insert** function you will each time have to pass the `db` instance to it, whereas **InsertG** will use the `db` instance set using `boil.SetDB(db)`, freeing you up from the hassle of passing `db` around the functions.

## Creating Author

Write a function that creates a new author and insert it into the database.

```go:main.go
package main

import (
	"context"
	"database/sql"
	"log"

	dbmodels "github.com/gurleensethi/go-sql-boiler-example/db/models"
	_ "github.com/lib/pq"
	"github.com/volatiletech/sqlboiler/v4/boil"
)

func main() {
	ctx := context.Background()
	db := connectDB()

	boil.SetDB(db)

	author := createAuthor(ctx)
}

// 👇 function that creates a new author
func createAuthor(ctx context.Context) dbmodels.Author {
	author := dbmodels.Author{
		Name:  "John Doe",
		Email: "johndoe@email.com",
	}

	err := author.InsertG(ctx, boil.Infer()) // 👈 insert author
	if err != nil {
		log.Fatal(err)
	}

	return author
}
```

Run the code using `go run main.go`.

**SQLBoiler** generates a lot of useful types, it will generate a type for each table which has many functions on it, one of them is `InsertG` (global variant) which is used to insert data into db.

**Database Log**

If you running the database provided in the example repository of this article, I have enabled logging on the database so you can see **exactly** what queries are being run my **SQLBoiler**.

```text
LOG:  execute <unnamed>: INSERT INTO "author" ("email","name") VALUES ($1,$2) RETURNING "id"
DETAIL:  parameters: $1 = 'johndoe@email.com', $2 = 'John Doe'
```

## Creating Article

Write a function that creates a new article and insert it into the database.

```go:main.go
package main

import (
	"context"
	"database/sql"
	"log"

	dbmodels "github.com/gurleensethi/go-sql-boiler-example/db/models"
	_ "github.com/lib/pq"
	"github.com/volatiletech/null/v8"
	"github.com/volatiletech/sqlboiler/v4/boil"
)

func main() {
	ctx := context.Background()
	db := connectDB()

	boil.SetDB(db)

	author := createAuthor(ctx)
	createArticle(ctx, author) // 👈 new article
	createArticle(ctx, author) // 👈 new article
}

// 👇 function that creates a new article
func createArticle(ctx context.Context, author dbmodels.Author) dbmodels.Article {
	article := dbmodels.Article{
		Title:    "Hello World",
		Body:     null.StringFrom("Hello world, this is an article."),
		AuthorID: author.ID,
	}

	err := article.InsertG(ctx, boil.Infer()) // 👈 insert article
	if err != nil {
		log.Fatal(err)
	}

	return article
}
```

Database query log:

```text
LOG:  execute <unnamed>: INSERT INTO "article" ("title","body","created_at","author_id") VALUES ($1,$2,$3,$4) RETURNING "id"
DETAIL:  parameters: $1 = 'Hello World', $2 = 'Hello world, this is an article.', $3 = '2022-08-06 20:11:49.012108', $4 = '1'
LOG:  execute <unnamed>: INSERT INTO "article" ("title","body","created_at","author_id") VALUES ($1,$2,$3,$4) RETURNING "id"
DETAIL:  parameters: $1 = 'Hello World', $2 = 'Hello world, this is an article.', $3 = '2022-08-06 20:11:49.016963', $4 = '1'
```

## Selecting Author and Article

In this piece of code, we are selecting an `Author` by ID and then selecting all the `Article`s created by that author.

```go:main.go
package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"

	dbmodels "github.com/gurleensethi/go-sql-boiler-example/db/models"
	_ "github.com/lib/pq"
	"github.com/volatiletech/null/v8"
	"github.com/volatiletech/sqlboiler/v4/boil"
)

func main() {
	ctx := context.Background()
	db := connectDB()

	boil.SetDB(db)

	author := createAuthor(ctx)
	createArticle(ctx, author)
	createArticle(ctx, author)
	selectAuthorWithArticle(ctx, author.ID)
}

// 👇 function that selects author and articles.
func selectAuthorWithArticle(ctx context.Context, authorID int) {
	author, err := dbmodels.Authors(dbmodels.AuthorWhere.ID.EQ(authorID)).OneG(ctx)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Author: \n\tID:%d \n\tName:%s \n\tEmail:%s\n", author.ID, author.Name, author.Email)

	articles, err := author.Articles().AllG(ctx)
	if err != nil {
		log.Fatal(err)
	}

	for _, a := range articles {
		fmt.Printf("Article: \n\tID:%d \n\tTitle:%s \n\tBody:%s \n\tCreatedAt:%v\n", a.ID, a.Title, a.Body.String, a.CreatedAt.Time)
	}
}
```

Databae query log:

```text
LOG:  execute <unnamed>: SELECT "author".* FROM "author" WHERE ("author"."id" = $1) LIMIT 1;
DETAIL:  parameters: $1 = '1'
LOG:  execute <unnamed>: SELECT "article".* FROM "article" WHERE ("article"."author_id"=$1);
DETAIL:  parameters: $1 = '1'
```

## Eager loading articles

**SQLBoiler** allows for earger loading of data, in our case we can load the articles of an author when we are fetching the articles. Update the `selectAuthorWithArticle` to have eager loading.

```go:main.go
package main

import (
	// ...other imports
	"github.com/volatiletech/sqlboiler/v4/queries/qm"
)

// ...other code

func selectAuthorWithArticle(ctx context.Context, authorID int) {
	author, err := dbmodels.Authors(
		dbmodels.AuthorWhere.ID.EQ(authorID),
		qm.Load(dbmodels.AuthorRels.Articles), // 👈 eager loading articles
	).OneG(ctx)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Author: \n\tID:%d \n\tName:%s \n\tEmail:%s\n", author.ID, author.Name, author.Email)

	for _, a := range author.R.Articles {
		fmt.Printf("Article: \n\tID:%d \n\tTitle:%s \n\tBody:%s \n\tCreatedAt:%v\n", a.ID, a.Title, a.Body.String, a.CreatedAt.Time)
	}
}
```

Eagerly loaded relations are stored in the `.R` property, so here it is `author.R.Articles`.

Database query log:

```text
LOG:  execute <unnamed>: SELECT "author".* FROM "author" WHERE ("author"."id" = $1) LIMIT 1;
DETAIL:  parameters: $1 = '2'
LOG:  execute <unnamed>: SELECT * FROM "article" WHERE ("article"."author_id" IN ($1));
DETAIL:  parameters: $1 = '2'
```

## Joining Tables

If you observe the database query logs, eager loading is still sending out two queries, what if we want to fetch this data in a single query, well we can do that using using a `join`.

Let's use the `NewQuery` function to create a custom query. Updating the `selectAuthorWithArticle` to fetch data using a join.

```go:main.go
package main

import (
	// ...other imports
	"github.com/volatiletech/sqlboiler/v4/queries/qm"
)

// ...other code

func selectAuthorWithArticle(ctx context.Context, authorID int) {
	// since each database row will contain info for author and article.
	type AuthorAndArticle struct {
		Article dbmodels.Article `boil:"articles,bind"`
		Author  dbmodels.Author  `boil:"author,bind"`
	}

	authorAndArticles := make([]AuthorAndArticle, 0)

	err := dbmodels.NewQuery(
		qm.Select("*"),
		qm.From(dbmodels.TableNames.Author),
		qm.InnerJoin("articles on articles.author_id = author.id"),
		dbmodels.AuthorWhere.ID.EQ(authorID),
	).BindG(ctx, &authorAndArticles)
	if err != nil {
		log.Fatal(err)
	}

	for _, authorAndArticle := range authorAndArticles {
		author := authorAndArticle.Author
		a := authorAndArticle.Article

		fmt.Printf("Author: \n\tID:%d \n\tName:%s \n\tEmail:%s\n", author.ID, author.Name, author.Email)
		fmt.Printf("Article: \n\tID:%d \n\tTitle:%s \n\tBody:%s \n\tCreatedAt:%v\n", a.ID, a.Title, a.Body.String, a.CreatedAt.Time)
	}
}
```

Database query log:

```text
LOG:  execute <unnamed>: SELECT * FROM "author" INNER JOIN article on article.author_id = author.id WHERE ("author"."id" = $1);
DETAIL:  parameters: $1 = '4'
```

As you can observe, only one query is being sent to the database.

# Ending

In my opinion **SQLBoiler** has a lot of potential to be the go-to `SQL` package in `Go`, there are still some small quircks in the library but once addressed it will go 🚀 🌕. Definitely visit the [SQLBoiler](https://github.com/volatiletech/sqlboiler)'s official documentation and dive deep into available functionality.

Thank you for reading this article 🙏🏻 if you learned something new consider joining the mailing list to get notified about articles likes these 😀.

SQLBoiler is package that introspects your database schema and generates a static ORM client. In this article I am going to give you a taste of SQLBoiler.

SQL in Go with SQLBoiler

# Getting Started

If you have been programming in Go for a while or have just picked it up, you might know that Go doesn't have any native `Set` type, if you didn't knew, now you know 😀.

In this article you are going to learn how to create a `Set` using the native `Map` type.

# Defining Operations

A `Set` mainly has three functions:

- **Add:** add a new value to the set.
- **Remove:** remove a value from the set.
- **Contains:** check if a value exists in the set.

# Writing Set

Let's create a set that can holds `string` values.

```go
type StringSet struct {
	m map[string]struct{}
}

func NewStringSet() StringSet {
	return StringSet{
		m: make(map[string]struct{}),
	}
}

func (s StringSet) Add(value string) {
	s.m[value] = struct{}{}
}

func (s StringSet) Contains(value string) bool {
	_, ok := s.m[value]
    return ok
}

func (s StringSet) Remove(value string) {
	delete(s.m, value)
}
```

We choose a map of type `map[string]struct{}`, the `key` of the map is your actual value. Additionally we use the `value, ok :=` idiom to [check the existance of key in the map](https://thedevelopercafe.com/articles/check-if-a-map-contains-a-key-in-go-and-more-d47bc9bc8b0b).

Let's write some sample code that uses this `StringSet`.

```go:main.go
package main

import "fmt"

func main() {
	set := NewStringSet()

	set.Add("1")
	set.Add("2")

	fmt.Println(set.Contains("1")) // Prints 'true'
	fmt.Println(set.Contains("3")) // Prints 'false'

	set.Remove("1")

	fmt.Println(set.Contains("1")) // Prints 'false'
}
```

Go only allows types to be used as keys that are comparable. These comparable types include `bool`, `int`, `string`, `array` (not slices), `interface`, `struct`.

Some types that cannot be used as keys of a map include `slice`, `functions`, `map`. If you try to use these types as keys of map as below:

**But what about Set for other types?**

This is all great but what about `IntSet`, `FloatSet` and set for various other types, do you have to write all this repetitive code 😰? this is where generics comes to rescue. If you have not already, [learn about generics](https://go.dev/doc/tutorial/generics).

# Generic Set

Most of the code stays the same as before, we only add generic type `T` to the struct and all the functions.

```go
// generics only allows types that are comparable
type AllowedKeys interface {
	~string |
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
	~float32 | ~float64
}

type Set[T AllowedKeys] struct {
	m map[T]struct{}
}

func NewSet[T AllowedKeys]() Set[T] {
	return Set[T]{
		m: make(map[T]struct{}),
	}
}

func (s Set[T]) Add(data T) {
	s.m[data] = struct{}{}
}

func (s Set[T]) Remove(data T) {
	delete(s.m, data)
}

func (s Set[T]) Contains(data T) bool {
	_, ok := s.m[data]
	return ok
}
```

Let's use the above `Set` to create an integer set.

```go:main.go
func main() {
	s := NewSet[int]()

	s.Add(10)

	fmt.Println(s.Contains(10))
	fmt.Println(s.Contains(11))

	s.Remove(10)

	fmt.Println(s.Contains(10))
}
```

We can simplify the generic `Set` code a little bit more by using the [`constraints`](https://pkg.go.dev/golang.org/x/exp/constraints) package from google.

Install the package:

```bash
 go get golang.org/x/exp/constraints
```

And update the generic `Set` code:

```go
type Set[T constraints.Ordered] struct {
	m map[T]struct{}
}

func NewSet[T constraints.Ordered]() Set[T] {
	return Set[T]{
		m: make(map[T]struct{}),
	}
}

func (s Set[T]) Add(data T) {
	s.m[data] = struct{}{}
}

func (s Set[T]) Remove(data T) {
	delete(s.m, data)
}

func (s Set[T]) Contains(data T) bool {
	_, ok := s.m[data]
	return ok
}
```

Thank you for reading this article 🙏🏻 hope you learned something new.

If you have been programming in Go for a while or have just picked it up, you might know that Go doesn't have any native Set type, if you didn't knew, now you know. 

Create Set in Go using Map

# The solution

To check if a key exists in a map use the "comma ok" pattern, `value, ok := yourMap[key]`. When getting a value from a `map` Go can return a second value which is a `bool` denoting if the key exists inside the map for not.

Here is an example.

```go:main.go
package main

import "fmt"

func main() {
	myMap := map[string]string{
		"key":   "value",
		"hello": "world",
	}

	value, ok := myMap["dog"]
    
	fmt.Println(ok) // prints 'false'
	fmt.Println(value) // prints '' (empty string)
}
```

You are fetching the value for key `dog` in the map which doesn't exists. The value of `ok` will tell you if the key exists inside the map.

**nil Map**

This also works in case the map is `nil`.

```go:main.go
package main

import "fmt"

func main() {
	var myMap map[string]string // map is `nil`

	fmt.Println(myMap == nil) // Prints 'true'

	value, ok := myMap["dog"]
    
	fmt.Println(ok) // prints 'false'
	fmt.Println(value) // prints '' (empty string)
}
```

Below are some more interesting facts about `map`s in Go that you may or may not know.

---

# Passing maps into functions

When you are passing a map to a function you are not passing a copy of the map, you are passing a copy of the pointer that points to the map, so essetially the function would have access to the same map. Any changes made to the map by the function will reflect in the caller.

```go:main.go
package main

import "fmt"

func main() {
	myMap := map[string]string{
		"key": "value",
	}

	fmt.Println(myMap) // Prints 'map[key:value]'

	DoWork(myMap)

	fmt.Println(myMap) // Prints 'map[dog:cat key:value]'
}

func DoWork(m map[string]string) {
	m["dog"] = "cat"
}
```

The `DoWork` function ends up adding a new entry(`dog: cat`) to the `myMap`.

# Implementing a set using a map

Go doesn't have a set type, but not to worry as implementing a set using a `map` is very easy. We need a `map[T]bool` type of map where `T` is the type of set you looking for.

A set mainly has 3 functions `Add` (to add values to set), `Contains` (check if value existins in set) and `Remove` (remove a value from a set).

Let's design a new type in Go called `StringSet`.

```go
type StringSet struct {
	m map[string]bool // underlying map holding set values
}

func NewStringSet() StringSet {
	return StringSet{
		m: make(map[string]bool),
	}
}

func (s StringSet) Add(value string) {
	s.m[value] = true
}

func (s StringSet) Contains(value string) bool {
	return s.m[value]
}

func (s StringSet) Remove(value string) {
	delete(s.m, value)
}
```

Using the above `StringSet`.

```go
package main

import "fmt"

func main() {
	set := NewStringSet()

	set.Add("1")
	set.Add("2")

	fmt.Println(set.Contains("1")) // Prints 'true'
	fmt.Println(set.Contains("3")) // Prints 'false'

	set.Remove("1")

	fmt.Println(set.Contains("1")) // Prints 'false'
}
```

# Keys allowed in a map

Go only allows types to be used as keys that are comparable. These comparable types include `bool`, `int`, `string`, `array` (not slices), `interface`, `struct`.

Some types that **cannot** be used as keys of a map include `slice`, `functions`, `map`. If you try to use these types as keys of map as below:

```go
package main

import "fmt"

func main() {
	myMap := make(map[[]int]string) // ❌ will not compile
	fmt.Println(myMap)
}
```

you will get the compile error `./main.go:6:20: invalid map key type []int`.

Thank you for reading this article 🙏🏻 hope you learned something new.

To check if a key exists in a map use the "comma ok". When getting a value from a map Go can return a second value which is a bool denoting if the key exists inside the map for not.

Check if a map contains a key in Go and more

# Getting Started

In this tutorial you are going to learn how to use the [migrate](https://github.com/golang-migrate/migrate) tool (written in Go and quite popular in Go community) to execute database migrations. As a second part you will write some Go code to read the data from the database. 

You are going to use [**PostgreSQL**](https://www.postgresql.org/) as the database of choice in this article, but **migrate** is compatible with many more databases check out the list [here](https://github.com/golang-migrate/migrate#databases).

# Setup

## Installation

`migrate` is a cli tool that is used to run migrations, it can also be used programtically, but in this tutorial we are going to use it via cli. There are multiple ways to install the `migrate` cli, such as brew, scoop, etc.  Take a look at the [installation document](https://github.com/golang-migrate/migrate/blob/5bf05dc3236ef077e5927c9ca9ca02857a87c582/cmd/migrate/README.md#installation) to see all the available options.

We are going to install it using `go install`. 

```bash
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
```

## Database

To run the sample postgres database I have provided you with a `docker-compose.yaml` file. Clone the [github project](https://github.com/gurleensethi/go-migrate-example) and run `docker compose up`. This will run a postgres database on port **5454**.

*You are free to setup a postgres db as you like, there is nothing special in the above setup.*

# Creating Migrations

You are going to create a `posts` table which will have to 2 columns, **title** and **body**.

To create a new migration run the `migrate create` command with appropriate options.

```bash
migrate create -ext sql -dir db/migrations create_posts_table
```

- **ext** specifies the file extension to use when creating migrations file.
- **dir** specifies which directory to create the migrations in.

This will create two migrations in `db/migrations` folder matching the pattern: `<timestamp>_create_posts_table.down.sql` and `<timestamp>_create_posts_table.up.sql`.

- **UP** migration will contain the sql to create the post table.
- **DOWN** migration will contain the sql to revert what has been done in the **up** migration.

## Writing SQL

In the `<timestamp>_create_posts_table.up.sql` migration file write the sql to create **posts** table.

```sql
CREATE TABLE IF NOT EXISTS posts (title varchar, body varchar);
```

In the `<timestamp>_create_posts_table.down.sql` migration file write the sql to drop **posts** table.

```sql
DROP TABLE IF EXISTS posts;
```

# Running migrations

**migrate** needs a way to connect the database to execute the sql statements. For this you will need a valid postgres connection string following the format:

```
postgres://<username>:<password>@localhost:<port>/<db_name>?sslmode=disable
```
  
If you are using the database using the `docker-compose.yaml` method specified above, the connection string will look like this:

```
postgres://postgres:postgres@localhost:5454/postgres?sslmode=disable
```

To run migrations use `migrate up` command with the appropriate options.

```bash
export DB_URL='postgres://postgres:postgres@localhost:5454/postgres?sslmode=disable'

# Run migrations
migrate -database ${DB_URL} -path db/migrations up
```

## Rolling back migrations

To roll back all the migrations i.e. execte all the `*.down.sql` files you use the `migration down` command.

```bash
export DB_URL='postgres://postgres:postgres@localhost:5454/postgres?sslmode=disable'

migrate -database ${DB_URL} -path db/migrations down
```

# Writing Code

Now that you have the `posts` table in the database, you are going to write some Go code to access the data. This is an optional section, feel free to skip it.

The complete code is available in this [GitHub repository](https://github.com/gurleensethi/go-migrate-example).

To access a postgres database we need a database driver, let's use the popular [pq](https://github.com/lib/pq) package.

```bash
go get github.com/lib/pq
```

Making a connection to the database.

```go
package main

import (
	"database/sql"
    "log"
    _ "github.com/lib/pq"
)

func main() {
	// credentials used from the compose setup previously
	db, err := sql.Open("postgres", "postgres://postgres:postgres@localhost:5454/postgres?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}

	defer db.Close()
    
    if err := db.Ping(); err != nil {
		log.Fatal("Failed to ping db", err)
	}
}
```

Create a struct to represent a row of `post` table.

```go
type Post struct {
	Title string
	Body  string
}
```

Selecting all the posts from db and displaying them.

```go
package main

import (
	"database/sql"
    "log"
    "fmt"
    _ "github.com/lib/pq"
)

type Post struct {
	Title string
	Body  string
}

func main() {
	...
    // previous code of db connection setup
    ...
    
    // query all the posts
	result, err := db.Query("SELECT * FROM posts;")
	if err != nil {
		log.Fatal(err)
	}

	defer result.Close()

	// iterate over all the posts and print them
	for result.Next() {
		var p Post

		err := result.Scan(&p.Title, &p.Body)
		if err != nil {
			log.Fatal(err)
		}

		fmt.Printf("%+v\n", p)
	}
}
```

Thank you for reading this article 🙏🏻 hope you enjoyed it.

In this tutorial you are going to learn how to use the migrate tool to execute database migrations. As a second part you will write some Go code to read the...

Database migrations in Go using Migrate package

# Getting Started

In this article you are going to learn how to use the [go-playground/validator](https://github.com/go-playground/validator/) package to validate data in your go application. [validator](https://github.com/go-playground/validator/) uses [struct tags](https://stackoverflow.com/a/30889373/6878730) to specify the validation constraints. This allows seamless integration to existing applications without the need of excess re-write of existing code.

# Installing validator

Create a new go project and using the `go get` command install the validator package as follows.

```bash
go get github.com/go-playground/validator/v10
```

At the time of writing, the current version of validator is `v10` do check the [GitHub Page](https://github.com/go-playground/validator/) to latest releases.

# An example

Let's take the example of signing up a user, we want **email**, **password** and an optional **name**.

```go
type SignUpPayload struct {
	Email    string
	Password string
	Name     string
}
```

Following are the validation requirements we want for our fields.
- **Email** is required and should be in email format.
- **Password** is required, should be minimum **8** characters and should contain atleast once special character from the set of **!@#?**.
- **Name** is optional, but if provided should be minimum **4** characters long.

Updating the example, adding struct tags.

```go
type SignUpPayload struct {
	Email    string  `validate:"required,email"`
	Password string  `validate:"required,min=8,containsany=!@#?*"`
	Name     string `validate:"omitempty,min=4"`
}
```

A lot of these tags should be self explanatory, `requried` means fields cannot be empty, `email` checks for email format, `min` checks of minimum length, `containsany` checks for existence of atleast once specified character.

You should use `omitempty` when a field is optional, but when any value to the field is provided the validators will kick in.

The struct is ready, let's use the validator to actually validate an instance of this struct.

```go
func main() {
	// creating a signup payload
	payload := SignUpPayload{
		Email:    "test@test.com",
		Password: "securepass#",
	}
	
    // get an instance of a validator
	v := validator.New()
	
    // call the `Struct` function passing in your payload
	err := v.Struct(payload)
	if err != nil {
		fmt.Println(err)
	}
}
```

The above payload conforms to the validation rules provided previously so `err` will be `nil`. Let's see an exampel that will fail.

```go
func main() {
	payload := SignUpPayload{
		Email:    "test@testcom", // 👈 invalid email
		Password: "securepass", // 👈 missing required character
		Name:     "123", // 👈 min length is not 4
	}

	v := validator.New()

	err := v.Struct(payload)
	if err != nil {
		fmt.Println(err)
	}
}
```

Running this example will print the following in the console.

```text
Key: 'SignUpPayload.Email' Error:Field validation for 'Email' failed on the 'email' tag
Key: 'SignUpPayload.Password' Error:Field validation for 'Password' failed on the 'containsany' tag
Key: 'SignUpPayload.Name' Error:Field validation for 'Name' failed on the 'min' tag
```


# Error handling

While checking if `err` is not `nil` is enough to know that validation failed, sometimes you may want to have more information from the error produced. The errors procuded by validator is of type `validator.ValidationErrors`, so you can cast the err to this type and obtain more information. Let me show you how.

```go
func main() {
	payload := SignUpPayload{...}

	v := validator.New()

	err := v.Struct(payload)
    if err == nil {
    	return
    }

	// doing due diligence by checking cast was successful
	validationErr, ok := err.(validator.ValidationErrors)
	if !ok {
		fmt.Println(err)
		return
	}

	for _, vErr := range validationErr {
		fmt.Printf("'%s' has a value of '%v' which does not satisfy '%s'.\n", vErr.Field(), vErr.Value(), vErr.Tag())
	}
}
```

`validator.ValidationErrors` is actually a slice of `validator.FieldError`, so you can loop over all the errors.

The output of the above program will be:

```text
'Email' has a value of 'test@testcom' which does not satisfy 'email'.
'Password' has a value of 'securepass' which does not satisfy 'containsany'.
'Name' has a value of '123' which does not satisfy 'min'.
```

# Validating variables

Validator provides the ability to validate individual variables using `Var` function. First argument is the value to validate and second are the validation tags (just like in struct validation).

```go
func main() {
	var password = "securepass"

	v := validator.New()

	// 👇
	err := v.Var(password, "required,min=8,containsany=!@#?*")
	if err != nil {
		fmt.Println(err)
	}
}
```

# End

**Recommendation:** A point to note when using validator in your application is to use the same instace of validator throughout the application i.e. `v := validator.New()`, use the same `v` across your application. The reason as specified in the soruce code of **validator**:

> It caches information about your struct and validations, in essence only parsing your validation tags once per struct type. Using multiple instances neglects the benefit of caching.

Valdiator provides over 100 validation tags, checkout the documentation [here](https://github.com/go-playground/validator/).

Thank you for reading this article 🙏🏻 more content coming soon.

In this article you are going to learn how to use the go-playground/validator package to validate data in your go application. validator uses struct tags to

Payload validation in Go with Validator

# Getting Started

In this article I am going to show you how to **create** and **parse** JWT tokens extracting information from them in the beautiful language of Go using the [go-jwt](https://github.com/golang-jwt/jwt) package.

This article presumes the following:

- You know how to program in **Go**.
- You know what **JWT**s are and how they work (this is not an article on JWT itself 😬).

# Setup

I highly recommend following this article and trying out the code yourself. The complete example code can be found in this [github repository](https://github.com/gurleensethi/go-jwt-tutorial).

Start by creating a new project using `go mod init <your repository path>`.

```shell
go mod init github.com/gurleensethi/go-jwt-tutorial
```

## Adding the go-jwt package

I will be using the [go-jwt](https://github.com/golang-jwt/jwt) package to create and parse JWT tokens.

```shell
go get -u github.com/golang-jwt/jwt/v4
```

At the time of writing this article the latest version for this package is `v4`, check for the latest releases on the [go-jwt](https://github.com/golang-jwt/jwt)'s github repostiroy.

# Creating JWT Token

When creating JWT token's we need a secret key, so start by defining a new key.

```go:main.go
package main

const key = "my secure jwt key" // 👈

func main() {
}
```

To create new tokens we use the [`jwt.NewWithClaims`](https://pkg.go.dev/github.com/golang-jwt/jwt#NewWithClaims) function.

```go:main.go
package main

import (
	"fmt"
	"log"
	"github.com/golang-jwt/jwt/v4"
)

const key = "my secure jwt key"

func main() {
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.RegisteredClaims{}) // 👈
    
    jwtToken, err := token.SignedString([]byte(key)) // 👈
    if err != nil {
    	log.Fatal(err)
    }
    
    fmt.Printf("JWT Token: %s\n", jwtToken)
}
```

Let me break this down for you:

- **NewWithClaims** takes two parameters, a **signing method** and **claims**. Claims is the actual data that the JWT token will contain.
- **jwt.NewWithClaims** doesn't create the new token, you need to call the `SignedString` function passing it the **secret key** to get the actual JWT token.
- **jwt.RegisteredClaims** are the common/standard JWT claims that are usually present in a JWT token payload such as `iat` (token issue time), `exp` (token expiry time) and many more. I highly recommend checking our the source code for **RegisteredClaims** [here](https://github.com/golang-jwt/jwt/blob/main/claims.go#L15-L45).

## Creating token with data

The code until now creates JWT token but it doesn't contain any user provided data. It is simple, instead of providing the `jwt.RegisteredClaims` as the payload, you will embed `jwt.RegisteredClaims` in another struct with additional information, lets call it `UserClaim`.

```go
type UserClaim struct {
	jwt.RegisteredClaims
	ID    int 
	Email string
	Name  string
}
```

Use this `UserClaim` as the second argument to the `jwt.NewWithClaims` function.

```go
token := jwt.NewWithClaims(jwt.SigningMethodHS256, UserClaim{
	RegisteredClaims: jwt.RegisteredClaims{},
	ID: "1",
	Email: "email@email.com",
	Name: "First Last",
})
```

I am going to refactor the JWT token creation process into a separate function called `CreateJWTToken`, below is the complete code.

```go:main.go
package main

import (
	"fmt"
	"log"
	"github.com/golang-jwt/jwt/v4"
)

const key = "my secure jwt key"

// Data that will be in the token
type UserClaim struct {
	jwt.RegisteredClaims
	ID    int 
	Email string
	Name  string
}

func main() {
	jwtToken, err := CreateJWTToken(1, "email@email.com", "First Last")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("JWT Token: %s\n", jwtToken)
}

// 👇
func CreateJWTToken(id int, email string, name string) (string, error) {
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, UserClaim{
		RegisteredClaims: jwt.RegisteredClaims{},
		ID: id,
		Email: email,
		Name: name,
	})

	// Create the actual JWT token
	signedString, err := token.SignedString([]byte(key))

	if err != nil {
		return "", fmt.Errorf("error creating signed string: %v", err)
	}

	return signedString, nil
}
```

# Parsing JWT Token

Parsing JWT tokens and extracing data from it can be done using the [`jwt.ParseWithClaims`](https://pkg.go.dev/github.com/golang-jwt/jwt#ParseWithClaims) function (there is another function [`jwt.Parse`](https://pkg.go.dev/github.com/golang-jwt/jwt#Parse) which will allow you to just parse and check if token is valid).

```go
var jwtToken string // a token generated from previous code
var userClaim UserClaim

token, err := jwt.ParseWithClaims(jwtToken, &userClaim, func(token *jwt.Token) (interface{}, error) {
	return []byte(key), nil
})
```

A more complete working example of parsing JWT token.

```go:main.go
package main

import (
	"fmt"
	"log"
	"github.com/golang-jwt/jwt/v4"
)

const key = "my secure jwt key"

type UserClaim struct {
	jwt.RegisteredClaims
	ID    int 
	Email string
	Name  string
}

func main() {
	jwtToken := "a token generated from previous code"
	var userClaim UserClaim
	
    // 👇
	token, err := jwt.ParseWithClaims(jwtToken, &userClaim, func(token *jwt.Token) (interface{}, error) {
		return []byte(key), nil
	})
	if err != nil {
		log.Fatal(err)
	}

	// Checking token validity 
	if !token.Valid {
        log.Fatal("invalid token")
	}
    
    fmt.Printf("Parsed User Claim: %d %s %s\n", userClaim.ID, userClaim.Email, userClaim.Name)
}
```

A thing to notice here is how `jwt.ParseWithClaims` accepts the secret key, it takes a function as the 3rd argument in which you have to return the key.

You can check validity of the token using the `Valid` boolean.

If the token is valid, `UserClaim` will be populated with the information inside the token.

Thank you for reading this article 🙏🏻 I highly recommend going through the complete example [here on GitHub](https://github.com/gurleensethi/go-jwt-tutorial/blob/main/main.go).

In this article I am going to show you how to create and parse JWT tokens extracting information from them in the beautiful language of Go using the go-jwt package.

JWT with Go

# Getting Started

In this article you are going to learn how to create a custom GitHub Action in Go. GitHub provides us two ways to build custom GitHub Actions, you can either build actions using JavaScript 💩 or you can use Docker 🐳. I am going to use Docker + Go to build custom GitHub Action, while doing so I will point out some important things to take note of.

This articles assumes the following pre-requisites:
- You know what [GitHub Actions](https://docs.github.com/en/actions) are and you have used them before.
- You have basic understanding of [Docker](https://www.docker.com/).

# Writing Go Code

For now lets keep the code simple and just print a message. Create a `main.go` file and add the following code to it.

```go:main.go
package main

import "fmt"

func main() {
	fmt.Println("Hello World From GitHub Action")
}
```

# Writing Dockerfile

There is no need to do anything specific for the `Dockerfile`, all you need is a regular docker image that runs the go code. Create a new `Dockerfile` and add the following code to it.

```dockerfile:Dockerfile
FROM golang:1.18.3-alpine3.16

WORKDIR /app

COPY ./ ./

RUN go build -o /bin/app main.go

ENTRYPOINT ["app"]
```

You might have noticed that (`RUN go build -o /bin/app main.go`) when building the go code the executable is being stored inside the `bin` directory. This is not a requirement, you can store the executable wherever you want.

# Writing action.yml

`action.yml` is the file that tells GitHub *"Hey GitHub! This repository contains a GitHub Action"*. You can define a lot of metadata related to the action in this file. I highly recommend to give this documentation a read if you are developing a GitHub Action 👉 [Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).

Create a new `action.yml` file and add the following code to it.

```yaml:action.yml
name: "github-action-go"
description: "An example of building github actions with Go"
runs:
  using: docker
  image: Dockerfile
```

The `runs` section is the one where you can specify to GitHub to run this action using Docker.

# Publishing the Action

Now you are all set to go, create a new repository and push the code. Before you can use an action you need to publish it by creating a release on GitHub. On the repository click on **create a new release**.

![GitHub create new release](https://tdc-public.nyc3.digitaloceanspaces.com/photos/3882c22a-1bd1-4042-84e8-4918a0d70465-github-create-new-release.png){.medium .center}

You will need to create a tag before the release, create a tag named `v1` (you can name it whatever you want but keeping proper versions is highly recommended).

![GitHub action create tag](https://tdc-public.nyc3.digitaloceanspaces.com/photos/00462c47-efdd-41a2-95e9-94c049b920a1-github-action-create-tag.png){.medium .center}

Give the release a title and click on **Publish Release**.

# Using the Action

Once the release is created you can start using the action in any github repositories, an example [workflow](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) file would look something like this:

```yaml:.github/workflows/workflow.yml
jobs:
  github-action-go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: gurleensethi/github-action-go@v1 # 👈 using custom action
```

You can also use your custom action in the same repository as the action itself.

```yaml:.github/workflows/workflow.yml
jobs:
  github-action-go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ./ # 👈 using action from the repository itself.
```

## How GitHub runs Docker actions

Since the action is supposed to run in as a docker container GitHub uses the `docker run` command to run it, it provides a bunch of arguments. Brave yourself to see the giant command.

```shell
docker run --name e225889822a53557c5068f1d4400b154c_a1b5de --label 72882e 
--workdir /github/workspace --rm -e HOME -e GITHUB_JOB -e GITHUB_REF -e GITHUB_SHA 
-e GITHUB_REPOSITORY -e GITHUB_REPOSITORY_OWNER -e GITHUB_RUN_ID 
-e GITHUB_RUN_NUMBER -e GITHUB_RETENTION_DAYS -e GITHUB_RUN_ATTEMPT 
-e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF 
-e GITHUB_EVENT_NAME -e GITHUB_SERVER_URL -e GITHUB_API_URL -e GITHUB_GRAPHQL_URL 
-e GITHUB_REF_NAME -e GITHUB_REF_PROTECTED -e GITHUB_REF_TYPE -e GITHUB_WORKSPACE 
-e GITHUB_ACTION -e GITHUB_EVENT_PATH -e GITHUB_ACTION_REPOSITORY 
-e GITHUB_ACTION_REF -e GITHUB_PATH -e GITHUB_ENV -e GITHUB_STEP_SUMMARY 
-e RUNNER_OS -e RUNNER_ARCH -e RUNNER_NAME -e RUNNER_TOOL_CACHE -e RUNNER_TEMP 
-e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN 
-e ACTIONS_CACHE_URL -e GITHUB_ACTIONS=true -e CI=true 
-v "/var/run/docker.sock":"/var/run/docker.sock" 
-v "/home/runner/work/_temp/_github_home":"/github/home" 
-v "/home/runner/work/_temp/_github_workflow":"/github/workflow" 
-v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" 
-v "/home/runner/work/github-action-go/github-action-go":"/github/workspace" 72882e:225889822a53557c5068f1d4400b154c
```

There is bunch of good stuff here, it sets the working directory `--workdir /github/workspace`, passes a bunch of environment variables using the `-e` flag and attaches a lot of volumes. Give this command a good read it might help you in something you are developing.

# Action Input and Container Arguments

GitHub Actions allow you to specify [inputs](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs) which the user of the action can pass when defining the workflow file.

The code for this section is available in the [input_args](https://github.com/gurleensethi/github-action-go/tree/input_args) branch of the repository.

Let's refactor the code to accept the message from the user instead of harcoding it. Update the `main.go` code to print all the arguments passed to the program.

```go:main.go
package main

import (
	"fmt"
	"strings"
	"os"
)

func main() {
	fmt.Println(strings.Join(os.Args[1:], " "))
}
```

If you run `go run main.go hello world` you will get the output `hello world`.

Update the `action.yml` to accept input from the user, let's call it `message`.

```yaml:action.yml
name: "github-action-go"
description: "An example of building github actions with Go"

inputs:
  message:
    required: true

runs:
  using: docker
  image: Dockerfile
```

As you can see I have added a new `inputs` section where I have defined an input called `message`. 

This input needs to be passed as args to the go program, you can do this by using the `args` option under `run`. Any args you specify with `args` will be passed to the `docker run` command when the action is run.


```yaml:action.yml
name: "github-action-go"
description: "An example of building github actions with Go"

inputs:
  message:
    required: true
    
runs:
  using: docker
  image: Dockerfile
  args:
    - ${{ inputs.message }}
```

Update the worflow file to use this `message` input.

```yaml:.github/workflows/workflow.yml
jobs:
  github-action-go:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: gurleensethi/github-action-go@v1
      	with:
        	message: Hello World from Github Action Input
```

Running the workflow you can see the specified message 🎉 and you can also see that the `docker run` command is being passed the arguments.

![GitHub docker input args](https://tdc-public.nyc3.digitaloceanspaces.com/photos/6a93be02-068f-49da-850b-c982e6d35866-github-docker-input-args.png){.center .large}

There is so much more you can do with GitHub Actions and even more with the beautiful language of Go, go out there and build some actions 😉.

Thank you for reading this article 🙏🏻.

In this article you are going to learn how to create a custom GitHub Action in Go. GitHub provides us two ways to build custom GitHub Actions, you can either build...