README.md (5560B)
1 # SQL-first Golang ORM for PostgreSQL, MySQL, MSSQL, and SQLite 2 3 [](https://github.com/uptrace/bun/actions) 4 [](https://pkg.go.dev/github.com/uptrace/bun) 5 [](https://bun.uptrace.dev/) 6 [](https://discord.gg/rWtp5Aj) 7 8 > Bun is brought to you by :star: [**uptrace/uptrace**](https://github.com/uptrace/uptrace). Uptrace 9 > is an open-source APM tool that supports distributed tracing, metrics, and logs. You can use it to 10 > monitor applications and set up automatic alerts to receive notifications via email, Slack, 11 > Telegram, and others. 12 > 13 > See [OpenTelemetry](example/opentelemetry) example which demonstrates how you can use Uptrace to 14 > monitor Bun. 15 16 ## Features 17 18 - Works with [PostgreSQL](https://bun.uptrace.dev/guide/drivers.html#postgresql), 19 [MySQL](https://bun.uptrace.dev/guide/drivers.html#mysql) (including MariaDB), 20 [MSSQL](https://bun.uptrace.dev/guide/drivers.html#mssql), 21 [SQLite](https://bun.uptrace.dev/guide/drivers.html#sqlite). 22 - [ORM-like](/example/basic/) experience using good old SQL. Bun supports structs, map, scalars, and 23 slices of map/structs/scalars. 24 - [Bulk inserts](https://bun.uptrace.dev/guide/query-insert.html). 25 - [Bulk updates](https://bun.uptrace.dev/guide/query-update.html) using common table expressions. 26 - [Bulk deletes](https://bun.uptrace.dev/guide/query-delete.html). 27 - [Fixtures](https://bun.uptrace.dev/guide/fixtures.html). 28 - [Migrations](https://bun.uptrace.dev/guide/migrations.html). 29 - [Soft deletes](https://bun.uptrace.dev/guide/soft-deletes.html). 30 31 ### Resources 32 33 - [**Get started**](https://bun.uptrace.dev/guide/golang-orm.html) 34 - [Examples](https://github.com/uptrace/bun/tree/master/example) 35 - [Discussions](https://github.com/uptrace/bun/discussions) 36 - [Chat](https://discord.gg/rWtp5Aj) 37 - [Reference](https://pkg.go.dev/github.com/uptrace/bun) 38 - [Starter kit](https://github.com/go-bun/bun-starter-kit) 39 40 ### Tutorials 41 42 Wrote a tutorial for Bun? Create a PR to add here and on [Bun](https://bun.uptrace.dev/) site. 43 44 ### Featured projects using Bun 45 46 - [uptrace](https://github.com/uptrace/uptrace) - Distributed tracing and metrics. 47 - [paralus](https://github.com/paralus/paralus) - All-in-one Kubernetes access manager. 48 - [inovex/scrumlr.io](https://github.com/inovex/scrumlr.io) - Webapp for collaborative online 49 retrospectives. 50 - [gotosocial](https://github.com/superseriousbusiness/gotosocial) - Golang fediverse server. 51 - [lorawan-stack](https://github.com/TheThingsNetwork/lorawan-stack) - The Things Stack, an Open 52 Source LoRaWAN Network Server. 53 - [anti-phishing-bot](https://github.com/Benricheson101/anti-phishing-bot) - Discord bot for 54 deleting Steam/Discord phishing links. 55 - [emerald-web3-gateway](https://github.com/oasisprotocol/emerald-web3-gateway) - Web3 Gateway for 56 the Oasis Emerald paratime. 57 - [lndhub.go](https://github.com/getAlby/lndhub.go) - accounting wrapper for the Lightning Network. 58 - [penguin-statistics](https://github.com/penguin-statistics/backend-next) - Penguin Statistics v3 59 Backend. 60 - And 61 [hundreds more](https://github.com/uptrace/bun/network/dependents?package_id=UGFja2FnZS0yMjkxOTc4OTA4). 62 63 ## Why another database client? 64 65 So you can elegantly write complex queries: 66 67 ```go 68 regionalSales := db.NewSelect(). 69 ColumnExpr("region"). 70 ColumnExpr("SUM(amount) AS total_sales"). 71 TableExpr("orders"). 72 GroupExpr("region") 73 74 topRegions := db.NewSelect(). 75 ColumnExpr("region"). 76 TableExpr("regional_sales"). 77 Where("total_sales > (SELECT SUM(total_sales) / 10 FROM regional_sales)") 78 79 var items []map[string]interface{} 80 err := db.NewSelect(). 81 With("regional_sales", regionalSales). 82 With("top_regions", topRegions). 83 ColumnExpr("region"). 84 ColumnExpr("product"). 85 ColumnExpr("SUM(quantity) AS product_units"). 86 ColumnExpr("SUM(amount) AS product_sales"). 87 TableExpr("orders"). 88 Where("region IN (SELECT region FROM top_regions)"). 89 GroupExpr("region"). 90 GroupExpr("product"). 91 Scan(ctx, &items) 92 ``` 93 94 ```sql 95 WITH regional_sales AS ( 96 SELECT region, SUM(amount) AS total_sales 97 FROM orders 98 GROUP BY region 99 ), top_regions AS ( 100 SELECT region 101 FROM regional_sales 102 WHERE total_sales > (SELECT SUM(total_sales)/10 FROM regional_sales) 103 ) 104 SELECT region, 105 product, 106 SUM(quantity) AS product_units, 107 SUM(amount) AS product_sales 108 FROM orders 109 WHERE region IN (SELECT region FROM top_regions) 110 GROUP BY region, product 111 ``` 112 113 And scan results into scalars, structs, maps, slices of structs/maps/scalars: 114 115 ```go 116 users := make([]User, 0) 117 if err := db.NewSelect().Model(&users).OrderExpr("id ASC").Scan(ctx); err != nil { 118 panic(err) 119 } 120 121 user1 := new(User) 122 if err := db.NewSelect().Model(user1).Where("id = ?", 1).Scan(ctx); err != nil { 123 panic(err) 124 } 125 ``` 126 127 See [**Getting started**](https://bun.uptrace.dev/guide/golang-orm.html) guide and check 128 [examples](example). 129 130 ## See also 131 132 - [Golang HTTP router](https://github.com/uptrace/bunrouter) 133 - [Golang ClickHouse ORM](https://github.com/uptrace/go-clickhouse) 134 - [Golang msgpack](https://github.com/vmihailenco/msgpack) 135 136 ## Contributing 137 138 See [CONTRIBUTING.md](CONTRIBUTING.md) for some hints. 139 140 And thanks to all the people who already contributed! 141 142 <a href="https://github.com/uptrace/bun/graphs/contributors"> 143 <img src="https://contributors-img.web.app/image?repo=uptrace/bun" /> 144 </a>