Voltar

Banco de Dados

O Kyrux não importa nenhum driver. Você adiciona o que precisar.

1. Adicionar o driver

go get github.com/lib/pq                    # PostgreSQL
go get github.com/go-sql-driver/mysql       # MySQL / MariaDB
go get modernc.org/sqlite                   # SQLite (sem CGO)
go get github.com/jackc/pgx/v5/stdlib       # PostgreSQL (pgx)
go get github.com/microsoft/go-mssqldb      # SQL Server
go get github.com/sijms/go-ora/v2           # Oracle (puro Go)

2. Importar com blank identifier no main.go

import _ "github.com/lib/pq"

3. Configurar o .env

Cada bloco iniciado por DB_NAME define um banco. O primeiro é o padrão (Use()). Adicione quantos blocos precisar — sem numeração, sem chaves extras.

DB_NAME=principal
DB_ENABLED=true
DB_DRIVER=postgres
DB_DSN=postgres://user:password@localhost:5432/meudb?sslmode=disable

DB_NAME=analytics
DB_ENABLED=true
DB_DRIVER=postgres
DB_DSN=postgres://user:password@localhost:5432/analytics?sslmode=disable

DB_NAME=legado
DB_ENABLED=true
DB_DRIVER=mysql
DB_DSN=user:password@tcp(localhost:3306)/legado

Usar a conexão nas views

As views recebem fw via closure no routes.go. Dentro da view, escolha o banco pelo nome definido em DB_NAME:

func MinhaView(fw *bootstrap.Framework) router.HandlerFunc {
    return func(ctx *router.Context) {
        db          := fw.DB.Use()               // primeiro banco do .env (padrão)
        dbAnalytics := fw.DB.Use("analytics")    // banco cujo DB_NAME=analytics
        dbLegado    := fw.DB.Use("legado")        // banco cujo DB_NAME=legado

        posts, err := orm.FromDB[models.Post](db).All()
        stats, err := orm.FromDB[models.Stat](dbAnalytics).All()
        _ = dbLegado
    }
}

Use() sem argumento é equivalente a Use("default") e sempre retorna o primeiro banco habilitado no .env.

Múltiplas conexões em runtime

Para adicionar conexões fora do .env (ex: multi-tenant dinâmico):

fw.DB.Add("tenant_xyz", "postgres", dsn)
db := fw.DB.Use("tenant_xyz")

Transações

O callback recebe *database.Tx — commit se retornar nil, rollback caso contrário (inclusive em panic). O ORM funciona dentro da transação via orm.FromTx e orm.CreateTx (equivalente ao transaction.atomic() do Django):

import "kyrux/core/database"

err := fw.DB.Use().Transaction(func(tx *database.Tx) error {
    pedido := Pedido{Total: 99.90}
    if err := orm.CreateTx(tx, &pedido); err != nil {
        return err // rollback automático
    }
    // SQL cru também funciona — tx embute *sql.Tx:
    _, err := tx.Exec("UPDATE stats SET total = total + 1")
    if err != nil {
        return err
    }
    return orm.FromTx[Saldo](tx).
        Where("id = ?", 1).
        Update(map[string]any{"valor": 100}) // commit se nil
})

Multi-tenant com schema

// Retorna uma cópia da conexão com o schema definido — a original não é alterada.
db := fw.DB.Use().WithSchema("tenant_abc")

Todas as queries executadas com essa conexão usarão tenant_abc.<tabela> automaticamente. Veja a seção ORM para uso completo com multi-tenant.

Drivers suportados

Driver	Módulo Go	Observação
postgres	github.com/lib/pq
pgx	github.com/jackc/pgx/v5/stdlib	Mais moderno, mas ~15-25% mais lento que postgres via database/sql (medido)
mysql	github.com/go-sql-driver/mysql	Também MariaDB
sqlite	modernc.org/sqlite	Sem CGO
sqlite3	github.com/mattn/go-sqlite3	Requer CGO
sqlserver	github.com/microsoft/go-mssqldb
oracle	github.com/sijms/go-ora/v2	Puro Go, sem CGO

Esta página cobre só SQL. Para MongoDB, Redis, Cassandra, Elasticsearch e DynamoDB, veja a página de NoSQL — clients próprios, experimentais, com API nativa de cada banco (sem ORM único).