Go is becoming a popular choice for those who need to increase the speed of their web server and microservices. Buffalo is a framework to allow rapid development in GO similar to Ruby on Rails. In this tutorial, we will make a basic API with buffalo and deploy it to Heroku.
Prerequisites
- Go Installed
- Buffalo installed
- Postgres
CLI Reference
| Command | Purpose |
|---|---|
| buffalo new {projectname} --api | create new project with api template |
| buffalo dev | run development server |
| buffalo pop create -a | create all databases in database.yml |
| buffalo pop drop -a | drop all databases in database.yml |
| buffalo pop generate fizz {name of migration} | Create new migration |
| buffalo pop migrate | run migrations |
| buffalo pop g model {model name} | generate a model file |
Setup
create a new project with the command
buffalo new project1 --api
The --api flag like in rails will use an alternate template optimized for building apiscd into the new folder project1 and open the folder in your editor
run
buffalo devto make sure the dev server is working
note
In Go 1.16 or later with buffalo 0.16.21 or earlier may have some issues to take care of.
- If it starts asking you to do a go get on a bunch of libraries... do so. I think this is caused in go 1.16 a go install doesn't auto add modules to go.mod so until fixed you'll have to add manually.
go get github.com/gobuffalo/envy@v1.9.0
go get github.com/gobuffalo/pop/v5@v5.3.0
go get github.com/gobuffalo/packr/v2@v2.8.0
go get github.com/rs/cors
go get github.com/gobuffalo/buffalo-pop/v2/pop/popmw@v2.3.0
go get github.com/gobuffalo/validate/v3@v3.1.0
go get github.com/gofrs/uuid@v3.2.0+incompatible
go get
go mod tidy
If you get an error about sqlite3 exporting this into your environment should fix the issue, this seems to not be a go or buffalo issue but an issue regarding libsqlite3 and particular versions of the gcc compiler.
export CGO_CFLAGS="-g -O2 -Wno-return-local-addr"If get an error regarding packr make sure to add the following to the import statement in actions/app.go
"github.com/gobuffalo/packr/v2"
Setting up our database
We will be using Postgres so we need to configure our database settings inside our database.yml.
development:
dialect: postgres
database: project1_development
user: test5
password: test5
host: 127.0.0.1
pool: 5
test:
url: {{envOr "TEST_DATABASE_URL" "postgres://test5:test5@127.0.0.1:5432/project1_test?sslmode=disable"}}
production:
url: {{envOr "DATABASE_URL" "postgres://test5:test5@127.0.0.1:5432/project1_production?sslmode=disable"}}
Your postgres settings may differ, make sure you use a username and password with the appropriate privileges
Migrating our Todo Table
The first step is let's set up our table for our Todos.
buffalo pop generate fizz create_todos
Two new files are created in your migrations folder. An up migration for adding and updating tables and a down migration for undoing those changes.
For the up migration add this...
create_table("todos") {
t.Column("id", "integer", {primary: true})
t.Column("item", "string", {"size": 100})
}
For the down migration add this...
drop_table("todos")
- Run the migration with the command
buffalo pop migrate
Creating our Model
So now that our table has been created we need a model to take advantage of the ORM to interact with the table.
generate a migration with the command
buffalo pop g model todoedit the migration file to match below so that you've added the item field to the struct and renamed any "todoes" to "todos". Also make sure to add the bit about overriding the tablename since it will by default look for a "todoes" table but our table is called "todos". (Make sure the type of your ID field matches the type in your migration)
package models
import (
"encoding/json"
"github.com/gobuffalo/pop/v5"
"github.com/gobuffalo/validate/v3"
"github.com/gofrs/uuid"
"time"
)
// Todo is used by pop to map your todoes database table to your go code.
type Todo struct {
ID int `json:"id" db:"id"`
Item string `json:"item" db:"item"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}
// TableName overrides the table name used by Pop.
func (u Todo) TableName() string {
return "todos"
}
// String is not required by pop and may be deleted
func (t Todo) String() string {
jt, _ := json.Marshal(t)
return string(jt)
}
// Todoes is not required by pop and may be deleted
type Todos []Todo
// String is not required by pop and may be deleted
func (t Todos) String() string {
jt, _ := json.Marshal(t)
return string(jt)
}
// Validate gets run every time you call a "pop.Validate*" (pop.ValidateAndSave, pop.ValidateAndCreate, pop.ValidateAndUpdate) method.
// This method is not required and may be deleted.
func (t *Todo) Validate(tx *pop.Connection) (*validate.Errors, error) {
return validate.NewErrors(), nil
}
// ValidateCreate gets run every time you call "pop.ValidateAndCreate" method.
// This method is not required and may be deleted.
func (t *Todo) ValidateCreate(tx *pop.Connection) (*validate.Errors, error) {
return validate.NewErrors(), nil
}
// ValidateUpdate gets run every time you call "pop.ValidateAndUpdate" method.
// This method is not required and may be deleted.
func (t *Todo) ValidateUpdate(tx *pop.Connection) (*validate.Errors, error) {
return validate.NewErrors(), nil
}
Building our actions
Our actions will be our functions that we will connect routes for our api. To generate some actions use the following command.
buffalo g actions todo index show add
This will generate a todo.go file in the actions folder with a TodoIndex, TodoShow, TodoAdd function which by default attempt to render a template, we'll fix that.
your actions/todo.go should look like this
package actions
import (
"net/http"
"github.com/gobuffalo/buffalo"
"project1/models"
)
// TodoIndex default implementation.
func TodoIndex(c buffalo.Context) error {
// Create an array to receive todos
todos := []models.Todo{}
//get all the todos from database
err := models.DB.All(&todos)
// handle any error
if err != nil {
return c.Render(http.StatusOK, r.JSON(err))
}
//return list of todos as json
return c.Render(http.StatusOK, r.JSON(todos))
}
// TodoShow default implementation.
func TodoShow(c buffalo.Context) error {
// grab the id url parameter defined in app.go
id := c.Param("id")
// create a variable to receive the todo
todo := models.Todo{}
// grab the todo from the database
err := models.DB.Find(&todo, id)
// handle possible error
if err != nil {
return c.Render(http.StatusOK, r.JSON(err))
}
//return the data as json
return c.Render(http.StatusOK, r.JSON(&todo))
}
// TodoAdd default implementation.
func TodoAdd(c buffalo.Context) error {
//get item from url query
item := c.Param("item")
//create new instance of todo
todo := models.Todo{Item: item}
// Create a fruit without running validations
err := models.DB.Create(&todo)
// handle error
if err != nil {
return c.Render(http.StatusOK, r.JSON(err))
}
//return new todo as json
return c.Render(http.StatusOK, r.JSON(todo))
}
Creating the routes
Now the routes will have been added already in actions/app.go when we generated the actions but we'll make some modifications that match the code below.
package actions
import (
"project1/models"
"github.com/gobuffalo/buffalo"
"github.com/gobuffalo/envy"
forcessl "github.com/gobuffalo/mw-forcessl"
i18n "github.com/gobuffalo/mw-i18n"
paramlogger "github.com/gobuffalo/mw-paramlogger"
"github.com/unrolled/secure"
"github.com/gobuffalo/buffalo-pop/v2/pop/popmw"
contenttype "github.com/gobuffalo/mw-contenttype"
"github.com/gobuffalo/x/sessions"
"github.com/rs/cors"
"github.com/gobuffalo/packr/v2"
)
// ENV is used to help switch settings based on where the
// application is being run. Default is "development".
var ENV = envy.Get("GO_ENV", "development")
var app *buffalo.App
var T *i18n.Translator
// App is where all routes and middleware for buffalo
// should be defined. This is the nerve center of your
// application.
//
// Routing, middleware, groups, etc... are declared TOP -> DOWN.
// This means if you add a middleware to `app` *after* declaring a
// group, that group will NOT have that new middleware. The same
// is true of resource declarations as well.
//
// It also means that routes are checked in the order they are declared.
// `ServeFiles` is a CATCH-ALL route, so it should always be
// placed last in the route declarations, as it will prevent routes
// declared after it to never be called.
func App() *buffalo.App {
if app == nil {
app = buffalo.New(buffalo.Options{
Env: ENV,
SessionStore: sessions.Null{},
PreWares: []buffalo.PreWare{
cors.Default().Handler,
},
SessionName: "_project1_session",
})
// Automatically redirect to SSL
app.Use(forceSSL())
// Log request parameters (filters apply).
app.Use(paramlogger.ParameterLogger)
// Set the request content type to JSON
app.Use(contenttype.Set("application/json"))
// Wraps each request in a transaction.
// c.Value("tx").(*pop.Connection)
// Remove to disable this.
app.Use(popmw.Transaction(models.DB))
app.GET("/", HomeHandler)
app.GET("/todo/", TodoIndex)
app.GET("/todo/add", TodoAdd)
app.GET("/todo/{id}", TodoShow) // <--- MAKE SURE THIS IS AT BOTTOM OF LIST
}
return app
}
// translations will load locale files, set up the translator `actions.T`,
// and will return a middleware to use to load the correct locale for each
// request.
// for more information: https://gobuffalo.io/en/docs/localization
func translations() buffalo.MiddlewareFunc {
var err error
if T, err = i18n.New(packr.New("app:locales", "../locales"), "en-US"); err != nil {
app.Stop(err)
}
return T.Middleware()
}
// forceSSL will return a middleware that will redirect an incoming request
// if it is not HTTPS. "http://example.com" => "https://example.com".
// This middleware does **not** enable SSL. for your application. To do that
// we recommend using a proxy: https://gobuffalo.io/en/docs/proxy
// for more information: https://github.com/unrolled/secure/
func forceSSL() buffalo.MiddlewareFunc {
return forcessl.Middleware(secure.Options{
SSLRedirect: ENV == "production",
SSLProxyHeaders: map[string]string{"X-Forwarded-Proto": "https"},
})
}
Testing
- Run
buffalo devto run dev server - create a todo with
localhost:3000/todo/add?item="breakfast" - create 2 or 3 more
- see the full list at
localhost:3000/todo/ - grab an individual one at
localhost:3000/todo/1
If all works let's begin discussing deployment!
Deployment
Add this comment in your go.mod with your version of go -
// +heroku goVersion 1.16create a Procfile in the root of your project with the following
web: ./bin/project1
create a new project on Heroku, under the resources tab create a new Heroku Postgres database
head over to settings and the following config var
GO_ENV=production
go back to resources click on the database to go to its dashboard, go to settings and find the connection URI under credentials
copy it to your local .env in your project
DATABASE_URL=postgres://username:password@server.amazonaws.com:5432/databasename
migrate your database with the command
buffalo pop migrate -e productioncommit and push your code to GitHub
connect it to your Heroku project under the deploy tab, enable automatic deploys, and trigger a manual deploy
Test it out, should be working!!!
Conclusion
While there is still a lot more to learn about working with Buffalo, this should give you a solid foundation to begin exploring further!
Latest comments (7)
I could understand the doc on how to upload files in goBuffalo. Do you have any idea?
I have trouble adding jquery in application.js file . Statements àre not executed . Am I missing some important detail?
is there a git repository we can look at your code to see if its all connected right?
I tried to add an entry - but all seem to fail:
... this results into:
try converting the param to a string in the function strconv.atoi. I'll double check why it was working for me in a bit.
The reason it works for me is cause I send the body via JSON so it's an integer, but if you send it via URL query it will be a string
Hi,
Typo in your example in file
todo.go-- you refer tofunc (u User)-- which does not exist!Should be: