Skip to content
Sample uses of CockroachDB with popular ORMs
Ruby Go Python Java Makefile JavaScript Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
go/gorm Single quote ADDR environment variable Aug 15, 2017
java/hibernate testing: decimal precision fixes Mar 1, 2017
node/sequelize sequelize: npm audit fix Feb 25, 2019
python django: Demo app created Oct 14, 2019
ruby ruby/activerecord: bump puma to ipv6-compatible version Oct 13, 2017
testing Removing the django test until it stops flaking Oct 15, 2019
vendor/github.com vendor: vendor deps May 31, 2017
.gitignore teach docker not to create directories as root May 18, 2017
Gopkg.lock
Gopkg.toml vendor: vendor deps May 31, 2017
LICENSE Initial commit Jun 24, 2016
Makefile django: Demo app created Oct 14, 2019
README.md Update README with install instructions May 18, 2018
docker.sh Upgrade docker image to get gem >= 3 Jan 3, 2019

README.md

Cockroach ORM examples

This repo contains example uses of CockroachDB with popular ORMs. Each example will implement the sample application spec presented below.

See the CockroachDB ORM Compatibility Plan for a roadmap towards supporting various ORMs.

Installation

Clone this repo into your $GOPATH manually, e.g.,

$ cd ~/go/src/github.com/cockroachdb
$ git clone https://github.com/cockroachdb/examples-orms

This is required because this project uses Go to drive the automated tests, so it will look for things in your $GOPATH. If you try to clone it to a non-$GOPATH directory, it will fail roughly as follows:

$ cd ~/some/random/dir/examples-orms
$ make test
go test -v -i ./testing
testing/api_handler.go:13:2: cannot find package "github.com/cockroachdb/examples-orms/go/gorm/model" in any of:
	/usr/local/Cellar/go/1.10/libexec/src/github.com/cockroachdb/examples-orms/go/gorm/model (from $GOROOT)
	/Users/rloveland/go/src/github.com/cockroachdb/examples-orms/go/gorm/model (from $GOPATH)
testing/api_handler.go:11:2: cannot find package "github.com/pkg/errors" in any of:
	/usr/local/Cellar/go/1.10/libexec/src/github.com/pkg/errors (from $GOROOT)
	/Users/rloveland/go/src/github.com/pkg/errors (from $GOPATH)
make: *** [test] Error 1

However, this is not actually a Go project, so go get -d will also fail (hence the need to manually clone).

$ go get -d github.com/cockroachdb/examples-orms
package github.com/cockroachdb/examples-orms: no Go files in /Users/rloveland/go/src/github.com/cockroachdb/examples-orms

Testing

To run automated testing against all ORMs using the latest binary of CockroachDB, run:

$ make test

To run automated testing against all ORMs using a custom CockroachDB binary, run:

$ make test COCKROACH_BINARY=/path/to/binary/cockroach

Project Structure

The repository contains a set of directories named after programming languages. Beneath these language directories are sub-directories named after specific ORM used for example application implementations.

Each ORM example uses whatever build tool is standard for the language, but provides a standardized Makefile with a start rule, which will start an instance of the sample application.

For instance, the directory structure for an example application of the Hibernate ORM will look like:

java
└── hibernate
    ├── Makefile
    └── example_source

Sample App

The sample application which each example implements is a JSON REST API modeling a company with customers, products, and orders. The API exposes access to the management of this company.

The purpose of the example application is to test common data access patterns so that we can stress various features and implementation details of each language/ORM.

Schema

An ideal schema diagram for the sample application looks like:

Customer
  |
  v
Order  <->  Product

The schema is implemented by each application using ORM-specific constructs to look as close as possible to:

CREATE DATABASE IF NOT EXISTS company_{language}_{ORM};

CREATE TABLE IF NOT EXISTS customers (
  id           SERIAL PRIMARY KEY,
  name         STRING
);

CREATE TABLE IF NOT EXISTS orders (
  id           SERIAL PRIMARY KEY,
  subtotal     DECIMAL(18,2)
  customer_id  INT    REFERENCES customers(id),
);

CREATE TABLE IF NOT EXISTS products (
  id           SERIAL PRIMARY KEY,
  name         STRING,
  price        DECIMAL(18,2)
);

CREATE TABLE IF NOT EXISTS product_orders (
  id           SERIAL PRIMARY KEY,
  product_id   INT    REFERENCES products(id),
  order_id     INT    REFERENCES orders(id) ON DELETE CASCADE
);

JSON API

Each example will expose a RESTful JSON API. The endpoints and example curl command lines are:

GET    /customer
    curl http://localhost:6543/customer

GET    /customer/:id
    curl http://localhost:6543/customer/1

POST   /customer
    curl -X POST -d '{"id": 1, "name": "bob"}' http://localhost:6543/customer

PUT    /customer/:id
    curl -X PUT -d '{"id": 2, "name": "robert"}' http://localhost:6543/customer/1

DELETE /customer
    curl -X DELETE http://localhost:6543/customer/1

GET    /product
    curl http://localhost:6543/product

GET    /product/:id
    curl http://localhost:6543/product/1

POST   /product
    curl -X POST -d '{"id": 1, "name": "apple", "price": 0.30}' http://localhost:6543/product

PUT    /product
DELETE /product

GET    /order
    curl http://localhost:6543/order

GET    /order/:id
    curl http://localhost:6543/order/1

POST   /order
    curl -X POST -d '{"id": 1, "subtotal": 18.2, "customer": {"id": 1}}' http://localhost:6543/order

PUT    /order
DELETE /order

The semantics of each endpoint will be fleshed out when necessary.

Unresolved Questions

  • Can the schema be completely standardized across ORMs without too much of a hassle with overriding default type and naming conventions?
You can’t perform that action at this time.