Building a Type-Safe Microservices Backend in Go
Tags: go, programming, tutorial, typesafe
Published: 2023-11-13 13:10:37

## TL;DR
Building microservices applications can be a pain because you normally have to deal with a lot of boilerplate and it can be hard to ensure end-to-end type-safety.🤯

✨In this guide we'll build and deploy a fully type-safe microservices application in Go, implementing the backend for a Trello application as an example.

To build our app, we'll be using [Encore](https://encore.dev), a backend development platform that provides a type-safe [Infrastructure SDK](https://encore.dev/docs/primitives) for declaratively defining infrastructure in Go code. We'll then use Encore to automatically provision and deploy our application.

**🚀 What's on deck:**
- Install Encore
- Create your backend app from a template
- Run locally
- Deploy to Encore's free development cloud

## 💽 Install Encore

Install the Encore CLI to run your local environment:
- **macOS:** `brew install encoredev/tap/encore`
- **Linux:** `curl -L https://encore.dev/install.sh | bash`
- **Windows:** `iwr https://encore.dev/install.ps1 | iex`

## 🔨 Create your app

We'll be starting from a template that has two services, each with a couple of API endpoints and their own databases.

(This example is intended to show how you create microservices applications with Encore. However, Encore can just as easily be used to build monolithic architectures.)

This is what the architecture looks like:

![microservices architecture](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f9hvqum5k4zwua67r99e.png)

In the diagram, `board` and `card` are microservices, and as you can see they each have their own database and a few endpoints.

When you have installed Encore, create a new application from the template using this command:

```bash
encore app create my-app-name --example=trello-clone
```

## 🏁 Running locally

Before running the application, make sure you have synced the project dependencies by running `go mod tidy` and that you have [Docker](https://docker.com) installed and running. (Docker is required when running Encore applications locally that use SQL databases.)

To start the Encore application, run:

```bash
encore run
```

You should see this, which means Encore has compiled and started your app, including necessary local infrastructure like PostgreSQL databases:

![encore run](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tf32fe1rdamm47fgimcq.jpg)

While it's running, open <http://localhost:9400/> to view Encore's [local developer dashboard](https://encore.dev/docs/observability/dev-dash).

![local dev dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6vopnk0e0w1u1knsvjh9.png)

From there you can view API documentation, make API calls, and see local traces for each request.

This is what the `board` service looks like in the built-in service catalog:

![service catalog](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/23rgoo2qiq341oflmp1i.jpg)

## 🤔 How it works: Services & APIs

### Defining services

With Encore you create a microservice by [defining one or more APIs](https://encore.dev/docs/primitives/services-and-apis#defining-apis) within a regular Go package. Encore's parser recognizes this as a service and uses the package name as the service name.

### Defining API endpoints

With Encore you only need to add an annotation, `//encore:api` to a regular function to turn it into and API endpoint.

You can define your own schemas and use built-in auth-handers if you wish. Learn more in the [API schemas docs](https://encore.dev/docs/develop/api-schemas).📚

### Making API calls

To make an API call between services, you import the other service as a package, and then call it's APIs using regular function calls.

When compiling your app, Encore automatically generates the necessary boilerplate code to wire up your application.✨

### Flexible deployment strategies
When deploying, Encore automatically [provisions the required infrastructure](https://encore.dev/docs/deploy/infra) for each service.

When you create your environment, you can configure if you wish to deploy each service as a separate process or if you wish to use a single process for all services.

This means you can deploy the same code in different ways for different environments, to optimize for cost and performance as required.💡

## 🤔 How it works: Using Databases with Encore

Encore treats SQL databases as logical resources and natively supports **PostgreSQL** databases.

To create a database, import `encore.dev/storage/sqldb` and call `sqldb.NewDatabase`, assigning the result to a package-level variable. (Databases must be created from within an Encore service.)

To start using the database, you only need to [define the schema](https://encore.dev/docs/primitives/databases#defining-a-database-schema) by creating a migration file.

Encore takes care of [provisioning the database](https://encore.dev/docs/primitives/databases#provisioning-databases), running new schema migrations during deploys, and connecting to it.

## 🕹 Let's try our new app

When your app is running, you can ping the `board.Create` endpoint to create a new Trello board, which will get stored in the database:

```bash
curl 'http://localhost:4000/board.Create' -d '{"Name":"my board"}'
```

Check the local development dashboard (<localhost:9400>) to see the request you just made and view a trace of the response.🧐

![trace](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7kz3jzfy76bftoyvb172.jpg)

## 🚀 Deploy to the cloud

Now let's deploy our application to a staging environment in Encore's free development cloud. To do this, we only need to **git push**:

```bash
git add -A .
git commit -m 'Commit message'
git push encore
```

Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.🌍

## 🍰 Great job - you're done!

You now have the foundations of a scalable and production-ready microservices backend running in the cloud.🎉

For real production-scale traffic, you can connect your cloud account (AWS/GCP) and deploy there with a click. You can deploy the same code to various services like CloudRun, EKS, GKE, or Fargate.

Keep building with these [Open Source Encore App Templates](https://encore.dev/templates).👈

If you have questions or want to share your work, join the developers' hangout in Encore's [community Slack](https://encore.dev/slack).👈