# 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...

Custom GitHub Action with Go

# Getting Started

In this article we are going to learn how to use [GoMock](https://github.com/golang/mock) to generate mock implementations of `interface`s in Go.

# Installing GoMock

GoMock works as a command line application to generate mocked source code, but you also have to install it in your application to use the generated mock code.

Installing the cli tool:

```
go install github.com/golang/mock/mockgen@v1.6.0
```

Installing gomock in your go project:

```
go get github.com/golang/mock/gomock
```

# Generating mock code

Let's say we have the following code in your `main.go` file.

```go
package main

// 👇 an interface acting as API Client
type ApiClient interface {
	GetData() string
}

// 👇 a function using the ApiClient interface
func Process(client ApiClient) int {
	data := client.GetData()
	return len(data)
}

func main() {

}
```

In the above piece of code we have an interface `ApiClient` that is being used by the `Process` function. Lets say we want to test the `Process` function and we require a mock implementation of `ApiClient` when doing so.

To generate mock implementation of `ApiClient` run the following code in the project root:

```
mockgen -source=main.go -destination=mocks/main.go
```

This will generate a mock implementation of the interfaace `ApiClient` and write the code into `mocks/main.go` file.

We don't really care about the generated code but here is the generated code to satisfy your curiosity (don't bother to understand it, just glance over it).

```go
// Code generated by MockGen. DO NOT EDIT.
// Source: main.go

// Package mock_main is a generated GoMock package.
package mock_main

import (
	reflect "reflect"

	gomock "github.com/golang/mock/gomock"
)

// MockApiClient is a mock of ApiClient interface.
type MockApiClient struct {
	ctrl     *gomock.Controller
	recorder *MockApiClientMockRecorder
}

// MockApiClientMockRecorder is the mock recorder for MockApiClient.
type MockApiClientMockRecorder struct {
	mock *MockApiClient
}

// NewMockApiClient creates a new mock instance.
func NewMockApiClient(ctrl *gomock.Controller) *MockApiClient {
	mock := &MockApiClient{ctrl: ctrl}
	mock.recorder = &MockApiClientMockRecorder{mock}
	return mock
}

// EXPECT returns an object that allows the caller to indicate expected use.
func (m *MockApiClient) EXPECT() *MockApiClientMockRecorder {
	return m.recorder
}

// GetData mocks base method.
func (m *MockApiClient) GetData() string {
	m.ctrl.T.Helper()
	ret := m.ctrl.Call(m, "GetData")
	ret0, _ := ret[0].(string)
	return ret0
}

// GetData indicates an expected call of GetData.
func (mr *MockApiClientMockRecorder) GetData() *gomock.Call {
	mr.mock.ctrl.T.Helper()
	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetData", reflect.TypeOf((*MockApiClient)(nil).GetData))
}
```

Look closely we have an struct called `MockApiClient` that has all the functions of `ApiClient` (`GetData` in this case). Additionally we have a function called `NewMockApiClient` that we can use to get an instance of `MockApiClient` in our tests.

# Using the mock code

Create a new file called `mock_test.go` and add the following code:

```go
package main

import (
	"github.com/golang/mock/gomock"
	mock_main "github.com/gurleensethi/playground/mocks"
	"testing"
)

func TestProcess(t *testing.T) {
	ctrl := gomock.NewController(t)
    
    // 👇 create new mock client
	mockApiClient := mock_main.NewMockApiClient(ctrl)
    
    // 👇 configure our mock `GetData` function to return mock data
	mockApiClient.EXPECT().GetData().Return("Hello World")

	length := Process(mockApiClient)

	if length != 11 {
		t.Fatalf("want: %d, got: %d\n", 11, length)
	}
}
```

We use the `NewMockApiClient` function to get an instance that we can use wherever `ApiClient` interface is expected.

```go
mockApiClient := mock_main.NewMockApiClient(ctrl)
```

Pay attention to how we configure the `GetData` function on the mock client to return the data that we want.

```go
mockApiClient.EXPECT().GetData().Return("Hello World")
```

Check out [GoMock documentation](https://github.com/golang/mock) it has a lot more options to configure mocks, it has a reflection mode which allows you to generate mocks of interfaces from packages that you have not written yourself and much more.

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

In this article we are going to learn how to use GoMock to generate mock implementations of interfaces in Go.

Mocking Interfaces in Go with GoMock

Mocking interfaces in Go with GoMock

# Getting Started

In this tutorial you are going to learn how to use [Chi](https://github.com/go-chi/chi) router to create HTTP endpoints in Go. We will also take a look at using middleware in Chi and grouping routes.

# Installing Chi

Setup a new Go project using `go mod init ...` and install Chi using the following command.

```shell
go get -u github.com/go-chi/chi/v5
```

# Writing HTTP Endpoints

A good thing about Chi is its ease of use and minimal API. Creating an endpoint is as simple as follows.

1. We start by creating a new router using `chi.NewRouter()`

```go
router := chi.NewRouter()
```

2. We register a new `GET` endpoint with the path `/`.

```go
router.Get("/", func(writer http.ResponseWriter, request *http.Request) {
	_, err := writer.Write([]byte("Hello World"))
	if err != nil {
		log.Println(err)
	}
})
```

Notice that chi takes the standard `http.HandlerFunc` as the handler function for an endpoint. FYI, `http.HandlerFunc` underlying type declaration is `type HandlerFunc func(ResponseWriter, *Request)`.

3. Chi router implements `http.Handler` interface so you can directly use it with `http.ListenAndServe`.

```go
err := http.ListenAndServe(":3000", router)
if err != nil {
	log.Println(err)
}
```

Here is the full working example.

```go
package main

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

func main() {
	// 1. Create a new router
	router := chi.NewRouter()

	// 2. Register an endpoint
	router.Get("/", func(writer http.ResponseWriter, request *http.Request) {
		_, err := writer.Write([]byte("Hello World"))
		if err != nil {
			log.Println(err)
		}
	})

	// 3. Use router to start the server
	err := http.ListenAndServe(":3000", router)
	if err != nil {
		log.Println(err)
	}
}
```

## HTTP Methods

Writing endpoints with other HTTP methods (`POST`, `PUT`, `DELETE` etc) is exactly like writing the `GET` request above, **chi** provides functions for all of them.

```go
router.Put()
router.Post()
router.Delete()
router.Patch()
```

For endpoints that have a request body, you would parse the body just like you [parse with regular Go http package](https://stackoverflow.com/a/15685432).

# Path Parameters

**chi** provides a function (`chi.URLParam`) to get path parameters that are defined using curly brackets `{ }`.

```go
router.Get("/user/{username}", func(writer http.ResponseWriter, request *http.Request) {
	username := chi.URLParam(request, "username") // 👈 getting path param
	_, err := writer.Write([]byte("Hello " + username))
	if err != nil {
		log.Println(err)
	}
})
```

In this example we define a GET endpoint that has a path parameter `username`, we call `chi.URLParam(request, "username")` to get the value of the path parameter.

To get query params from a request you can use the inbuilt Go functionality `request.URL.Query()`.

# Middleware with Chi

**Chi** lets you to easily add middleware to the router using the `use` function. The `use` function takes in another function as a parameter that takes in a [http.Handler](https://pkg.go.dev/net/http#Handler) and returns a [http.Handler](https://pkg.go.dev/net/http#Handler) as well (**http.Handler** is just an interface with a single function `ServeHTTP(ResponseWriter, *Request)`).

Here is how you would write a middleware to log each request's path.

```go
// 1. Write a middleware
func Logger(handler http.Handler) http.Handler {
	return http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
		log.Println(request.URL.Path)
		handler.ServeHTTP(writer, request)
	})
}

// 2. Register with router
router.Use(Logger)
```

Here is the full example with logging middleware.

```go
package main

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

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

	router.Use(Logger) // 👈 register middleware with router

	router.Get("/", func(writer http.ResponseWriter, request *http.Request) {
		_, err := writer.Write([]byte("Hello World"))
		if err != nil {
			log.Println(err)
		}
	})

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

// 👇 a logging middleware
func Logger(handler http.Handler) http.Handler {
	return http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
		log.Println(request.URL.Path)
		handler.ServeHTTP(writer, request)
	})
}
```

**Chi** provides a wide range of middlewares built into the package itself, you can find the complete list [here](https://go-chi.io/#/pages/middleware).

Using the inbuilt logging middleware from **Chi**:

```go
package main

import (
	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware" // 👈 import middleware package
	"log"
	"net/http"
)

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

	router.Use(middleware.Logger) // 👈 use the inbuilt logging middleware

	...
}
```

# Grouping Routes

**Chi** provides a couple of ways to group routes.

You can use the `chi.Route` function to create sub-routes.

```go
router.Route("/users", func(r chi.Router) {
	r.Get("/{id}", getUser)
	r.Post("/", createUser)
	r.Put("/deactivate", deactivateUser)
})
```

This will add 3 routes to the router `GET /users/{id}` `POST /users/` and `PUT /users/deactivate`.

You can group routes using `chi.Group` which allows you to apply middleware to only grouped routes.

```go
router.Post("/login", login)
router.Post("/signup", login)

// Apply auth middleware to only `GET /users/{id}`
router.Group(func(r chi.Router) {
	r.Use(AuthMiddleware)
	r.Get("/users/{id}")
})
```

Thank you for reading this article 🙏 I hope you learned something new, highly encourage you to read the [chi](https://go-chi.io/) documentation.

 In this tutorial you are going to learn how to use Chi router to create HTTP endpoints in Go. We will also take a look at using middleware in Chi and grouping routes.

Restful routing with Chi in Go

# Getting Started

In this article you will learn how to live reload go applications with one of the popular packages out there [air](https://github.com/cosmtrek/air). First we will learn how to setup up air and start using it right away, then we will see how to customize air with `.air.toml` file.

# Installing air

There are many ways to install **air** as seen in the [installation](https://github.com/cosmtrek/air#installation) section of air's documentation. The way I am going to use here is via `go install` (for `go install` to work you would have to have the `$GOPATH/bin` in your shell path).

```shell
go install github.com/cosmtrek/air@latest
```

# Live reload go code

In a new directory create a `main.go` file with the following content:

```go:main.go
package main

import "fmt"

func main() {
	fmt.Println("Air")
}
```

and run the following command to see live reloading in action:

```shell
air
```

You should see the following output:

```
watching .
!exclude tmp
building...
running...
Air
```

Now go ahead change the code and save the file:

```go
package main

import "fmt"

func main() {
	fmt.Println("Air Changed") // 👈 update message
}
```

**Air** will detect that the file is changed and you will see the new message:

```
watching .
!exclude tmp
building...
running...
Air Changed
```

**Air** creates a directory called `tmp` where it stores the built binary and executes it.

# Configuring air with config file

You can cutomize **Air** using a `.air.toml` file.

Run the following command in the project directory to generate a `.air.toml` file.

```
air init
```

This will generate a `.air.toml` file with the following output:

```toml:.air.toml
root = "."
testdata_dir = "testdata"
tmp_dir = "tmp"

[build]
  bin = "./tmp/main"
  cmd = "go build -o ./tmp/main ."
  delay = 1000
  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
  exclude_file = []
  exclude_regex = ["_test.go"]
  exclude_unchanged = false
  follow_symlink = false
  full_bin = ""
  include_dir = []
  include_ext = ["go", "tpl", "tmpl", "html"]
  kill_delay = "0s"
  log = "build-errors.log"
  send_interrupt = false
  stop_on_error = true

[color]
  app = ""
  build = "yellow"
  main = "magenta"
  runner = "green"
  watcher = "cyan"

[log]
  time = false

[misc]
  clean_on_exit = false

[screen]
  clear_on_rebuild = false
```

Let's take an example, set `clean_on_exit` to `true`, this will delete the `tmp` (air stores the build binary file) folder when you exit **air**.

```toml
[misc]
  clean_on_exit = true
```

Run the **air** command by passing the config using `-c` option:

```shell
air -c .air.toml
```

To find the documentation of all the properties of `.air.toml` read the [air_example.toml](https://github.com/cosmtrek/air/blob/master/air_example.toml) file.

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

In this article you will learn how to live reload go applications with one of the popular packages out there air. First we will learn how to setup up air...