Bun: дружественный к SQL Golang ORM

Bun это дружественный к SQL Golang ORM для PostgreSQL, MySQL/MariaDB, MSSQL, и SQLite. Данная статья призвана познакомить вас с базовыми возможностями этой ORM.

Работа с SQL

Дружественный к SQL означает что вы можете элегантно писать стандартные SQL запросы используя язык Go. К примеру, следующий Bun запрос:

var num int err := db.NewSelect().     TableExpr("generate_series(1, 3)").     Where("generate_series = ?", 3).     Limit(10).     Scan(ctx, &num)

Генерирует такой SQL:

SELECT * FROM generate_series(1, 3) WHERE generate_series = 123 LIMIT 10

Как вы можете видеть, Bun запросы все еще содержат узнаваемый SQL, который к тому еще защищен от SQL инъекций благодаря использованию специальных ? placeholders:

Where("id = ?", 123)     // WHERE id = 123 Where("id >= ?", 123)    // WHERE id >= 123 Where("id = ?", "hello") // WHERE id = 'hello'  Where("id IN (?)", bun.In([]int{1, 2, 3})) // WHERE id IN (1, 2, 3)  Where("? = ?", bun.Ident("column"), "value") // WHERE "column" = 'value'

Используя Bun, вы можете писать действительно сложные запросы, к примеру, следующий Bun запрос:

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)

Генерирует такой SQL:

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

Структуры и таблицы

Bun позволяет отображать Go структуры и SQL таблицы используя модели, к примеру, следующий код:

type Model struct {     ID        int64 `bun:",pk,autoincrement"`     Name      string `bun:",notnull"`     CreatedAt time.Time `bun:",nullzero,default:now()"` }  err := db.ResetModel(ctx, &Model{})

Генерирует такую таблицу:

CREATE TABLE "models" (   "id" BIGSERIAL NOT NULL,   "name" VARCHAR NOT NULL,   "created_at" TIMESTAMPTZ DEFAULT now(),   PRIMARY KEY ("id"), )

Используя объявленную модель, вы можете генерировать select/insert/update/delete запросы:

model := new(Model) err := db.NewSelect().Model().Where("id = ?", 123).Scan(ctx)  model.ID = 0 res, err := db.NewInsert().Model(model).Exec(ctx)  res, err := db.NewUpdate().     Model(model).     Set("name = ?", "updated name").     WherePK().     Exec(ctx)  res, err := db.NewDelete().Model(model).WherePK().Exec(ctx)

Обращайтесь к Bun документации за подробностями.

Golang ORM

Как насчет части про Golang ORM? Bun позволяет объявлять популярные отношения между таблицами используя Go структуры. К примеру, вы можете описать Author принадлежит к Book таким образом:

type Book struct { ID int64 AuthorID int64 Author Author `bun:"rel:belongs-to,join:author_id=id"` }  type Author struct { ID int64 }

А затем использовать Relation метод для джойна таблицы:

err := db.NewSelect(). Model(book). Relation("Author"). Where("id = ?", 123). Scan(ctx)

SELECT   "book"."id", "book"."title", "book"."text",   "author"."id" AS "author__id", "author"."name" AS "author__name" FROM "books" LEFT JOIN "users" AS "author" ON "author"."id" = "book"."author_id" WHERE id = 1

За подробностями обращайтесь к ORM: Table relationships.

Соединение с базой данных

Bun работает поверх database/sql и поддерживает PostgreSQL, MySQL/MariaDB, MSSQL, и SQLite.

Для соединения с PostgreSQL базой данных:

import ( "github.com/uptrace/bun" "github.com/uptrace/bun/dialect/pgdialect"     "github.com/uptrace/bun/driver/pgdriver" )  dsn := "postgres://postgres:@localhost:5432/test?sslmode=disable" sqldb := sql.OpenDB(pgdriver.NewConnector(pgdriver.WithDSN(dsn)))  db := bun.NewDB(sqldb, pgdialect.New())

Для соединения с MySQL базой данных:

import ( "github.com/uptrace/bun" "github.com/uptrace/bun/dialect/mysqldialect" _ "github.com/go-sql-driver/mysql" )  sqldb, err := sql.Open("mysql", "root:pass@/test") if err != nil { panic(err) }  db := bun.NewDB(sqldb, mysqldialect.New())

Для логгирования всех обработанных запросов, вы можете установить bundebug плагин:

import "github.com/uptrace/bun/extra/bundebug"  db.AddQueryHook(bundebug.NewQueryHook( bundebug.WithVerbose(true), // log everything ))

Выполнение запросов

После того как вы объявили модель, вы можете начинать выполнять запросы:

// Select a user by a primary key. user := new(User) err := db.NewSelect().Model(user).Where("id = ?", 1).Scan(ctx)  // Select first 10 users. var users []User err := db.NewSelect().Model(&users).OrderExpr("id ASC").Limit(10).Scan(ctx)

Когда речь идет о сканировании результатов запросов, Bun очень гибок и позволяет работать со структурами:

user := new(User) err := db.NewSelect().Model(user).Limit(1).Scan(ctx)

Скалярами:

var id int64 var name string err := db.NewSelect().Model((*User)(nil)).Column("id", "name").Limit(1).Scan(ctx, &id, &name)

Хэш таблицами типа map[string]interface{}:

var m map[string]interface{} err := db.NewSelect().Model((*User)(nil)).Limit(1).Scan(ctx, &m)

И массивами всех ранее упомянутых типов:

var users []User err := db.NewSelect().Model(&users).Limit(1).Scan(ctx)  var ids []int64 var names []string err := db.NewSelect().Model((*User)(nil)).Column("id", "name").Limit(1).Scan(ctx, &ids, &names)  var ms []map[string]interface{} err := db.NewSelect().Model((*User)(nil)).Scan(ctx, &ms)

Вы также можете сканировать результаты insert/update/delete запросов:

var ids []int64 res, err := db.NewDelete().Model((*User)(nil)).Returning("id").Exec(ctx, &ids)

Мониторинг производетельности

Bun имеет множество плагинов включая OpenTelemetry инструментацию позволяющую использовать distributed tracing и метрики.

Трэйсинг позволяет вам мониторить производительность БД используя множество open source tracing tools поддерживающих OpenTelemetry. Многие платные DataDog competitors также поддерживают OpenTelemetry.

Кроме того, вы можете экспортировать OpenTelemetry метрики в Prometheus используя Grafana или другие популярные альтернативы.

Что дальше

Чтобы начать работать с Bun, используйте документацию и запустите примеры c GitHub.

Если вы уже используете database/sql, то вы можете начать использовать Bun не изменяя существующий код. Bun также поддерживает Go и SQL миграции, fixtures, хуки, и многое другое.