carautenbach / bun

SQL-first Golang ORM

SQL-first Golang ORM for PostgreSQL, MySQL, MSSQL, and SQLite

Bun is brought to you by ⭐ uptrace/uptrace. Uptrace is an open-source APM tool that supports distributed tracing, metrics, and logs. You can use it to monitor applications and set up automatic alerts to receive notifications via email, Slack, Telegram, and others.

See OpenTelemetry example which demonstrates how you can use Uptrace to monitor Bun.

Features

• Works with PostgreSQL, MySQL (including MariaDB), MSSQL, SQLite.
• ORM-like experience using good old SQL. Bun supports structs, map, scalars, and slices of map/structs/scalars.
• Bulk inserts.
• Bulk updates using common table expressions.
• Bulk deletes.
• Fixtures.
• Migrations.
• Soft deletes.

Resources

• Get started
• Examples
• Discussions
• Chat
• Reference
• Starter kit

Tutorials

Wrote a tutorial for Bun? Create a PR to add here and on Bun site.

Featured projects using Bun

• uptrace - Distributed tracing and metrics.
• paralus - All-in-one Kubernetes access manager.
• inovex/scrumlr.io - Webapp for collaborative online retrospectives.
• gotosocial - Golang fediverse server.
• lorawan-stack - The Things Stack, an Open Source LoRaWAN Network Server.
• anti-phishing-bot - Discord bot for deleting Steam/Discord phishing links.
• emerald-web3-gateway - Web3 Gateway for the Oasis Emerald paratime.
• lndhub.go - accounting wrapper for the Lightning Network.
• penguin-statistics - Penguin Statistics v3 Backend.
• And hundreds more.

Why another database client?

So you can elegantly write complex queries:

regionalSales := db.NewSelect().
	ColumnExpr("region").
	ColumnExpr("SUM(amount) AS total_sales").
	TableExpr("orders").
	GroupExpr("region")

topRegions := db.NewSelect().
	ColumnExpr("region").
	TableExpr("regional_sales").
	Where("total_sales > (SELECT SUM(total_sales) / 10 FROM regional_sales)")

var items []map[string]interface{}
err := db.NewSelect().
	With("regional_sales", regionalSales).
	With("top_regions", topRegions).
	ColumnExpr("region").
	ColumnExpr("product").
	ColumnExpr("SUM(quantity) AS product_units").
	ColumnExpr("SUM(amount) AS product_sales").
	TableExpr("orders").
	Where("region IN (SELECT region FROM top_regions)").
	GroupExpr("region").
	GroupExpr("product").
	Scan(ctx, &items)

WITH regional_sales AS (
    SELECT region, SUM(amount) AS total_sales
    FROM orders
    GROUP BY region
), top_regions AS (
    SELECT region
    FROM regional_sales
    WHERE total_sales > (SELECT SUM(total_sales)/10 FROM regional_sales)
)
SELECT region,
       product,
       SUM(quantity) AS product_units,
       SUM(amount) AS product_sales
FROM orders
WHERE region IN (SELECT region FROM top_regions)
GROUP BY region, product

And scan results into scalars, structs, maps, slices of structs/maps/scalars:

users := make([]User, 0)
if err := db.NewSelect().Model(&users).OrderExpr("id ASC").Scan(ctx); err != nil {
	panic(err)
}

user1 := new(User)
if err := db.NewSelect().Model(user1).Where("id = ?", 1).Scan(ctx); err != nil {
	panic(err)
}

See Getting started guide and check examples.

See also

• Golang HTTP router
• Golang ClickHouse ORM
• Golang msgpack

Contributing

See CONTRIBUTING.md for some hints.

And thanks to all the people who already contributed!