Quick Start

This section will cover how to get up and running with pop quickly for development.

1. Installation

Installation is typical for most Golang packages, but we'll also install the soda utility that will facilitate the database migrations and model creation.

$ go get github.com/gobuffalo/pop/...
$ go install github.com/gobuffalo/pop/soda

2. Configuration

Configuring pop is done via a YAML file. Each stanza is broken down by environment, so that you can have a configuration per environment. In your project, create the file config/database.yml. The development environment can be identified by passing the -e development flag into any soda command.

development:
  dialect: "sqlite3"
  database: "./development.sqlite"

3. Create a model

The soda utility is used to create a model.

$ soda generate model user title:string first_name:string last_name:string bio:text -e development
v3.41.1

--> models/user.go
--> models/user_test.go
--> goimports -w models/user.go models/user_test.go
> migrations/20171218173819_create_users.up.fizz
> migrations/20171218173819_create_users.down.fizz

As you can see there are two folders created: models and migrations. The User model is stored in models/user.go, and an initial migration is stored at migrations/20171218173819_create_users.up.fizz. The fizz file type is an alternative to SQL, however when building out migrations you can force migration files to be in SQL.

4. Create the database

Again, the soda utility is used to create the database.

$ soda create -e development

5. Run the migration

Running the migration creates the tables (models) you just defined.

$ soda migrate up -e development

Now you are ready to begin writing your application.

6. Modifying the Schema

Inevitably your data models will change. It's just a fact of life and the scourge of operations. Suppose you wanted to add a column to our existing schema.

$ soda generate fizz add_location_column
v3.41.1

> migrations/20171219202712_add_location_column.up.fizz
> migrations/20171219202712_add_location_column.down.fizz

Now, you'll have three files created that you'll need to modify. An up migration is a positive change, a down migration is a reverting change. In the 20171219202712_add_location_column.up.fizz file

add_column("user", "location", "string", {"size": 100, "default": "New York, NY"})

and in the 20171219202712_add_location_column.down.fizz file

drop_column("user", "location")

Now you'll need to update the actual model

type User struct {
    ID        uuid.UUID `json:"id" db:"id"`
    CreatedAt time.Time `json:"created_at" db:"created_at"`
    UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
    Title     string    `json:"title" db:"title"`
    FirstName string    `json:"first_name" db:"first_name"`
    LastName  string    `json:"last_name" db:"last_name"`
    Bio       string    `json:"bio" db:"bio"`
    Location  string    `json:"location" db:"location"`        // Add this line
}

Then run the migration

$ soda migrate up -e development
v3.41.1

> add_location_column

0.0033 seconds
dumped schema for ./development.sqlite