Build a Go App with CockroachDB

2020-02-16

This tutorial shows you how build a simple Go application with CockroachDB using a PostgreSQL-compatible driver or ORM.

We have tested the Go pq driver and the GORM ORM enough to claim beta-level support, so those are featured here. If you encounter problems, please open an issue with details to help us make progress toward full support.

{{site.data.alerts.callout_success}} For a more realistic use of GORM with CockroachDB, see our examples-orms repository. {{site.data.alerts.end}}

Before you begin

  1. Install CockroachDB.
  2. Start up a secure or insecure local cluster.
  3. Choose the instructions that correspond to whether your cluster is secure or insecure:

Step 1. Install the GORM ORM

To install GORM, run the following commands:

$ go get -u github.com/lib/pq # dependency
$ go get -u github.com/jinzhu/gorm
## Step 2. Create the `maxroach` user and `bank` database {% include {{page.version.version}}/app/create-maxroach-user-and-bank-database.md %} ## Step 3. Generate a certificate for the `maxroach` user Create a certificate and key for the `maxroach` user by running the following command. The code samples will run as this user. {% include copy-clipboard.html %} ~~~ shell $ cockroach cert create-client maxroach --certs-dir=certs --ca-key=my-safe-directory/ca.key ~~~ ## Step 4. Run the Go code The following code uses the [GORM](http://gorm.io) ORM to map Go-specific objects to SQL operations. Specifically, `db.AutoMigrate(&Account{})` creates an `accounts` table based on the Account model, `db.Create(&Account{})` inserts rows into the table, and `db.Find(&accounts)` selects from the table so that balances can be printed. Copy the code or download it directly. {% include copy-clipboard.html %} ~~~ go {% include {{ page.version.version }}/app/gorm-basic-sample.go %} ~~~ Then run the code: {% include copy-clipboard.html %} ~~~ shell $ go run gorm-basic-sample.go ~~~ The output should be: ~~~ Initial balances: 1 1000 2 250 ~~~ To verify that funds were transferred from one account to another, start the [built-in SQL client](use-the-built-in-sql-client.html): {% include copy-clipboard.html %} ~~~ shell $ cockroach sql --certs-dir=certs -e 'SELECT id, balance FROM accounts' --database=bank ~~~ ~~~ +----+---------+ | id | balance | +----+---------+ | 1 | 1000 | | 2 | 250 | +----+---------+ (2 rows) ~~~
## Step 2. Create the `maxroach` user and `bank` database {% include {{page.version.version}}/app/insecure/create-maxroach-user-and-bank-database.md %} ## Step 3. Run the Go code The following code uses the [GORM](http://gorm.io) ORM to map Go-specific objects to SQL operations. Specifically, `db.AutoMigrate(&Account{})` creates an `accounts` table based on the Account model, `db.Create(&Account{})` inserts rows into the table, and `db.Find(&accounts)` selects from the table so that balances can be printed. Copy the code or download it directly. {% include copy-clipboard.html %} ~~~ go {% include {{ page.version.version }}/app/insecure/gorm-basic-sample.go %} ~~~ Then run the code: {% include copy-clipboard.html %} ~~~ shell $ go run gorm-basic-sample.go ~~~ The output should be: ~~~ Initial balances: 1 1000 2 250 ~~~ To verify that funds were transferred from one account to another, start the [built-in SQL client](use-the-built-in-sql-client.html): {% include copy-clipboard.html %} ~~~ shell $ cockroach sql --insecure -e 'SELECT id, balance FROM accounts' --database=bank ~~~ ~~~ +----+---------+ | id | balance | +----+---------+ | 1 | 1000 | | 2 | 250 | +----+---------+ (2 rows) ~~~

What's next?

Read more about using the GORM ORM, or check out a more realistic implementation of GORM with CockroachDB in our examples-orms repository.

You might also be interested in using a local cluster to explore the following CockroachDB benefits: