Relational database library for Go, with simple and familiar interface.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 54a9c11 Sep 23, 2018
Permalink
Failed to load latest commit information.
examples move examples Jan 11, 2016
meta Support embedding Jan 19, 2018
sql Set SQL table name after checking custom table name Jun 18, 2018
COPYING Create COPYING Sep 23, 2018
README.md Update README.md Jun 17, 2018
create.go Add CreateAndRead method Feb 20, 2016
create_test.go Set SQL table name after checking custom table name Jun 18, 2018
db.go Use timers in query & exec calls Oct 14, 2017
db_test.go Use timers in query & exec calls Oct 14, 2017
delete.go Rename MustUpdate & MustDelete as Update and Delete Jan 14, 2016
delete_test.go Rename MustUpdate & MustDelete as Update and Delete Jan 14, 2016
field-iteration.go Support embedding Jan 19, 2018
fields.go Support embedding Jan 19, 2018
fields_test.go Support embedding Jan 19, 2018
go.mod Add missing dependencies Aug 27, 2018
go.sum Add missing dependencies Aug 27, 2018
main_test.go Set SQL table name after checking custom table name Jun 18, 2018
read.go Rename internal reflect library to meta for avoiding confusion Jan 10, 2016
read_test.go Test scanning to null types Mar 26, 2017
row.go Set SQL table name after checking custom table name Jun 18, 2018
row_test.go Added support for bigint -> int64 Jan 29, 2016
scan.go Return sql.ErrNoRows instead of custom one Feb 28, 2016
sql_reflect.go Rename internal reflect library to meta for avoiding confusion Jan 10, 2016
sql_reflect_test.go Implement scanning to structs Jan 10, 2016
table.go Set SQL table name after checking custom table name Jun 18, 2018
table_test.go Fix tests for mariadb Mar 26, 2017
transaction.go Rename MustUpdate & MustDelete as Update and Delete Jan 14, 2016
transaction_test.go Rename internal reflect library to meta for avoiding confusion Jan 10, 2016
update.go Rename MustUpdate & MustDelete as Update and Delete Jan 14, 2016
update_test.go Support embedding Jan 19, 2018

README.md

CRUD

A minimalistic relational database library for Go.

Features:

Manual:

Install

$ go get github.com/azer/crud

Initialize

import (
  "github.com/azer/crud"
  _ "github.com/go-sql-driver/mysql"
)

var DB *crud.DB

func init () {
  var err error
  DB, err = crud.Connect("mysql", os.Getenv("DATABASE_URL"))
  err = DB.Ping()
}

Define

type User struct {
  Id int `sql:"auto-increment primary-key"`
  FirstName string
  LastName string
  ProfileId int
}

type Profile struct {
  Id int `sql:"auto-increment primary-key"`
  Bio string `sql:"text"`
}

CRUD will automatically convert column names from "FirstName" (CamelCase) to "first_name" (snake_case) for you. You can still choose custom names though;

type Post struct {
  Slug string `sql:"name=slug_id varchar(255) primary-key required"`
}

If no primary key is specified, CRUD will look for a field named "Id" with int type, and set it as auto-incrementing primary-key field.

Create & Drop Tables

CreateTables takes list of structs and makes sure they exist in the database.

err := DB.CreateTables(User{}, Profile{})

err := DB.DropTables(User{}, Profile{})
Reset Tables

Shortcut for dropping and creating tables.

err := DB.ResetTables(User{}, Profile{})
SQL Options

CRUD tries to be smart about figuring out the best SQL options for your structs, and lets you choose manually, too. For example;

type Tweet struct {
 Text string `sql:"varchar(140) required name=tweet"`
}

Above example sets the type of the Text column as varchar(140), makes it required (NOT NULL) and changes the column name as tweet.

Here is the list of the options that you can pass;

  • Types: int, bigint, varchar, text, date, time, timestamp
  • auto-increment / autoincrement / auto_increment
  • primary-key / primarykey / primary_key
  • required
  • default='?'
  • name=?
  • table-name=?

If you'd like a struct field to be ignored by CRUD, choose - as options:

type Foo struct {
 IgnoreMe string `sql:"-"`
}

Create

Simply pass a struct. It can be pointer or not.

user := &User{1, "Foo", "Bar", 1}
err := DB.Create(user)

CreateAndRead

Create a row, and read it back from the DB. The values of the struct you passed get resetted to whatever the corresponding DB row has. In the other words, CreateAndRead creates, and reads. So you got fields generated by the DB scanned to your struct, like ID.

Make sure passing a pointer.

user := User{
  FirstName:"Foo"
}

err := DB.CreateAndRead(&user)

user.Id
// => 123

Read

You can read single/multiple rows, or custom values, with the Read method.

Reading a single row:

Pass your struct's pointer, and a query;

user := &User{}
err := DB.Read(user, "SELECT * FROM users WHERE id = ?", 1)
// => SELECT * FROM users WHERE id = 1

fmt.Println(user.Name)
// => Foo
Reading multiple rows:
users := []*User{}

err := DB.Read(&users)
// => SELECT * FROM users

fmt.Println(len(users))
// => 10
Scanning to custom values:
names := []string{}
err := DB.Read(&names, "SELECT name FROM users")
name := ""
err := DB.Read(&name, "SELECT name FROM users WHERE id=1")
totalUsers := 0
err := DB.Read(&totalUsers, "SELECT COUNT(id) FROM users"

Update

Updates matching row in database, returns sql.ErrNoRows nothing matched.

user := &User{}
err := DB.Read(user, "SELECT * FROM users WHERE id = ?", 1)

user.Name = "Yolo"
err := DB.Update(user)

Delete

Deletes matching row in database, returns sql.ErrNoRows nothing matched.

err := DB.Delete(&User{
  Id: 1
})

Transactions

Use Begin method of a crud.DB instance to create a new transaction. Each transaction will provide you following methods;

  • Commit
  • Rollback
  • Exec
  • Query
  • Create
  • Read
  • Update
  • Delete
tx, err := DB.Begin()

err := tx.Create(&User{
  Name: "yolo"
})

err := tx.Delete(&User{
  Id: 123
})

err := tx.Commit()

Logs

If you want to see crud's internal logs, specify crud in the LOG environment variable when you run your app. For example;

$ LOG=crud go run myapp.go

(More info about how crud's logging work)

Custom Queries

result, err := DB.Query("DROP DATABASE yolo") // or .Exec

Running Tests

DATABASE_URL="?" go test ./...

Why another ORMish library for Go?

  • Simplicity, taking more advantage of reflect library to keep the API simple.
  • Building less things with more complete abstractions
  • Handling errors in an idiomatic way
  • Good test coverage
  • Modular & reusable code
  • Making less unsafe assumptions. e.g: not mapping structs to SQL rows by column index.
  • Complete & tested SQL Options

Apps Using CRUD

What's Missing?

  • Migration: We need a sophisticated solution for adding / removing columns when user changes the structs.
  • Relationships: This was intentionally avoided. Can be considered if there is a clean way to implement it.
  • Testing Transactions: Transactions work as expected but there is a sync bug in the test causing failure. It needs to be fixed.
  • Comments: I rarely comment my code.
  • Hooks: I'm not sure if this is needed, but worths to consider.
  • Foreign Keys: *
  • Query Builder: Building SQL queries programmatically is useful.
  • Make UTF-8 Default: Looks like the default charset is not UTF8.

LICENSE

WTFPL