Skip to content
SQL builder and query library for golang
Go
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add CODECOV_TOKEN as argument to codecov Sep 5, 2019
dialect Fix for #163 Sep 21, 2019
docs v9.4.0 Sep 30, 2019
exec v9.4.0 Sep 30, 2019
exp Fix for #172 Oct 3, 2019
internal v9.4.0 Sep 30, 2019
mocks Update go.mod to v9 Sep 18, 2019
sqlgen Fix for #172 Oct 3, 2019
vendor Update dependencies Sep 18, 2019
.gitignore Add codecov.io (#36) Mar 16, 2017
.golangci.yml v7.0.0 Jul 9, 2019
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md (#46) Sep 15, 2017
CONTRIBUTING.md v0.1.0 Mar 8, 2015
HISTORY.md Fix for #172 Oct 3, 2019
LICENSE Create LICENSE (#47) Sep 15, 2017
Makefile v7.0.0 Jul 9, 2019
README.md Fix for #163 Sep 21, 2019
_config.yml Set theme jekyll-theme-cayman Jul 9, 2019
codecov.yml Refactor SQL Generation Logic Aug 22, 2019
database.go Update go.mod to v9 Sep 18, 2019
database_example_test.go v9.4.0 Sep 30, 2019
database_test.go Update go.mod to v9 Sep 18, 2019
delete_dataset.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
delete_dataset_example_test.go v9.0.1 Sep 19, 2019
delete_dataset_test.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
docker-compose.yml v8.5.0 Aug 25, 2019
expressions.go Update go.mod to v9 Sep 18, 2019
expressions_example_test.go v9.0.2 Sep 19, 2019
expressions_test.go Update go.mod to v9 Sep 18, 2019
go.mod Update dependencies Sep 18, 2019
go.sum Update dependencies Sep 18, 2019
go.test.sh Fix data race in query factory initialisation Aug 18, 2019
goqu.go
goqu_example_test.go Change SetTimeLocation to accept *time.Location Sep 22, 2019
goqu_test.go Add github actions Aug 24, 2019
insert_dataset.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
insert_dataset_example_test.go Update go.mod to v9 Sep 18, 2019
insert_dataset_test.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
issues_test.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
select_dataset.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
select_dataset_example_test.go v9.4.0 Sep 30, 2019
select_dataset_test.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
sql_dialect.go Update go.mod to v9 Sep 18, 2019
sql_dialect_example_test.go Update go.mod to v9 Sep 18, 2019
sql_dialect_test.go Update go.mod to v9 Sep 18, 2019
truncate_dataset.go Update go.mod to v9 Sep 18, 2019
truncate_dataset_test.go Update go.mod to v9 Sep 18, 2019
update_dataset.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019
update_dataset_example_test.go v9.0.1 Sep 19, 2019
update_dataset_test.go [ADDED] Using Update, Insert, or Delete datasets in sub selects and C… Sep 25, 2019

README.md

  __ _  ___   __ _ _   _
 / _` |/ _ \ / _` | | | |
| (_| | (_) | (_| | |_| |
 \__, |\___/ \__, |\__,_|
 |___/          |_|

GitHub tag Actions Status GoDoc codecov Go Report Card

goqu is an expressive SQL builder and executor

If you are upgrading from an older version please read the Migrating Between Versions docs.

Installation

If using go modules.

go get -u github.com/doug-martin/goqu/v9

If you are not using go modules...

NOTE You should still be able to use this package if you are using go version >v1.10 but, you will need to drop the version from the package. import "github.com/doug-martin/goqu/v9 -> import "github.com/doug-martin/goqu"

go get -u github.com/doug-martin/goqu

Migrating Between Versions

Features

goqu comes with many features but here are a few of the more notable ones

  • Query Builder
  • Parameter interpolation (e.g SELECT * FROM "items" WHERE "id" = ? -> SELECT * FROM "items" WHERE "id" = 1)
  • Built from the ground up with multiple dialects in mind
  • Insert, Multi Insert, Update, and Delete support
  • Scanning of rows to struct[s] or primitive value[s]

While goqu may support the scanning of rows into structs it is not intended to be used as an ORM if you are looking for common ORM features like associations, or hooks I would recommend looking at some of the great ORM libraries such as:

Why?

We tried a few other sql builders but each was a thin wrapper around sql fragments that we found error prone. goqu was built with the following goals in mind:

  • Make the generation of SQL easy and enjoyable
  • Create an expressive DSL that would find common errors with SQL at compile time.
  • Provide a DSL that accounts for the common SQL expressions, NOT every nuance for each database.
  • Provide developers the ability to:
    • Use SQL when desired
    • Easily scan results into primitive values and structs
    • Use the native sql.Db methods when desired

Docs

  • Dialect - Introduction to different dialects (mysql, postgres, sqlite3 etc)
  • Expressions - Introduction to goqu expressions and common examples.
  • Select Dataset - Docs and examples about creating and executing SELECT sql statements.
  • Insert Dataset - Docs and examples about creating and executing INSERT sql statements.
  • Update Dataset - Docs and examples about creating and executing UPDATE sql statements.
  • Delete Dataset - Docs and examples about creating and executing DELETE sql statements.
  • Prepared Statements - Docs about interpolation and prepared statements in goqu.
  • Database - Docs and examples of using a Database to execute queries in goqu
  • Working with time.Time - Docs on how to use alternate time locations.

Quick Examples

Select

See the select dataset docs for more in depth examples

sql, _, _ := goqu.From("test").ToSQL()
fmt.Println(sql)

Output:

SELECT * FROM "test"
sql, _, _ := goqu.From("test").Where(goqu.Ex{
	"d": []string{"a", "b", "c"},
}).ToSQL()
fmt.Println(sql)

Output:

SELECT * FROM "test" WHERE ("d" IN ('a', 'b', 'c'))

Insert

See the insert dataset docs for more in depth examples

ds := goqu.Insert("user").
	Cols("first_name", "last_name").
	Vals(
		goqu.Vals{"Greg", "Farley"},
		goqu.Vals{"Jimmy", "Stewart"},
		goqu.Vals{"Jeff", "Jeffers"},
	)
insertSQL, args, _ := ds.ToSQL()
fmt.Println(insertSQL, args)

Output:

INSERT INTO "user" ("first_name", "last_name") VALUES ('Greg', 'Farley'), ('Jimmy', 'Stewart'), ('Jeff', 'Jeffers') []
ds := goqu.Insert("user").Rows(
	goqu.Record{"first_name": "Greg", "last_name": "Farley"},
	goqu.Record{"first_name": "Jimmy", "last_name": "Stewart"},
	goqu.Record{"first_name": "Jeff", "last_name": "Jeffers"},
)
insertSQL, args, _ := ds.ToSQL()
fmt.Println(insertSQL, args)

Output:

INSERT INTO "user" ("first_name", "last_name") VALUES ('Greg', 'Farley'), ('Jimmy', 'Stewart'), ('Jeff', 'Jeffers') []
type User struct {
	FirstName string `db:"first_name"`
	LastName  string `db:"last_name"`
}
ds := goqu.Insert("user").Rows(
	User{FirstName: "Greg", LastName: "Farley"},
	User{FirstName: "Jimmy", LastName: "Stewart"},
	User{FirstName: "Jeff", LastName: "Jeffers"},
)
insertSQL, args, _ := ds.ToSQL()
fmt.Println(insertSQL, args)

Output:

INSERT INTO "user" ("first_name", "last_name") VALUES ('Greg', 'Farley'), ('Jimmy', 'Stewart'), ('Jeff', 'Jeffers') []
ds := goqu.Insert("user").Prepared(true).
	FromQuery(goqu.From("other_table"))
insertSQL, args, _ := ds.ToSQL()
fmt.Println(insertSQL, args)

Output:

INSERT INTO "user" SELECT * FROM "other_table" []
ds := goqu.Insert("user").Prepared(true).
	Cols("first_name", "last_name").
	FromQuery(goqu.From("other_table").Select("fn", "ln"))
insertSQL, args, _ := ds.ToSQL()
fmt.Println(insertSQL, args)

Output:

INSERT INTO "user" ("first_name", "last_name") SELECT "fn", "ln" FROM "other_table" []

Update

See the update dataset docs for more in depth examples

sql, args, _ := goqu.Update("items").Set(
	goqu.Record{"name": "Test", "address": "111 Test Addr"},
).ToSQL()
fmt.Println(sql, args)

Output:

UPDATE "items" SET "address"='111 Test Addr',"name"='Test' []
type item struct {
	Address string `db:"address"`
	Name    string `db:"name" goqu:"skipupdate"`
}
sql, args, _ := goqu.Update("items").Set(
	item{Name: "Test", Address: "111 Test Addr"},
).ToSQL()
fmt.Println(sql, args)

Output:

UPDATE "items" SET "address"='111 Test Addr' []
sql, _, _ := goqu.Update("test").
	Set(goqu.Record{"foo": "bar"}).
	Where(goqu.Ex{
		"a": goqu.Op{"gt": 10}
	}).ToSQL()
fmt.Println(sql)

Output:

UPDATE "test" SET "foo"='bar' WHERE ("a" > 10)

Delete

See the delete dataset docs for more in depth examples

ds := goqu.Delete("items")

sql, args, _ := ds.ToSQL()
fmt.Println(sql, args)
sql, _, _ := goqu.Delete("test").Where(goqu.Ex{
		"c": nil
	}).ToSQL()
fmt.Println(sql)

Output:

DELETE FROM "test" WHERE ("c" IS NULL)

Contributions

I am always welcoming contributions of any type. Please open an issue or create a PR if you find an issue with any of the following.

  • An issue with Documentation
  • You found the documentation lacking in some way

If you have an issue with the package please include the following

  • The dialect you are using
  • A description of the problem
  • A short example of how to reproduce (if applicable)

Without those basics it can be difficult to reproduce your issue locally. You may be asked for more information but that is a good starting point.

New Features

New features and/or enhancements are great and I encourage you to either submit a PR or create an issue. In both cases include the following as the need/requirement may not be readily apparent.

  1. The use case
  2. A short example

If you are issuing a PR also also include the following

  1. Tests - otherwise the PR will not be merged
  2. Documentation - otherwise the PR will not be merged
  3. Examples - [If applicable] see example_test.go for examples

If you find an issue you want to work on please comment on it letting other people know you are looking at it and I will assign the issue to you.

If want to work on an issue but dont know where to start just leave a comment and I'll be more than happy to point you in the right direction.

Running tests

The test suite requires a postgres and mysql database. You can override the mysql/postgres connection strings with the MYSQL_URI and PG_URI environment variables*

go test -v -race ./...

You can also run the tests in a container using docker-compose.

GO_VERSION=latest docker-compose run goqu

License

goqu is released under the MIT License.

You can’t perform that action at this time.