Banco de dados

O pacote sqlDB usa database/sql com PostgreSQL e integra as operações ao monitoramento do SDK.

Configurar e inicializar

SQL_DB_HOST=localhost
SQL_DB_PORT=5432
SQL_DB_NAME=app
SQL_DB_USER=postgres
SQL_DB_PASSWORD=postgres
SQL_DB_SSL_MODE=disable

colibri.InitializeApp()
sqlDB.Initialize()

Initialize() abre e testa a conexão, configura o pool e registra o fechamento seguro.

Consultar um item

type User struct {
	ID    string
	Name  string
	Email string
}

user, err := sqlDB.NewQuery[User](
	ctx,
	"SELECT id, name, email FROM users WHERE id = $1",
	id,
).One()
if err != nil {
	return nil, err
}
if user == nil {
	return nil, ErrUserNotFound
}

One() retorna nil, nil quando a consulta não encontra registros.

Consultar vários itens

users, err := sqlDB.NewQuery[User](
	ctx,
	"SELECT id, name, email FROM users WHERE active = $1",
	true,
).Many()

Os valores são mapeados pela ordem das colunas e campos. Selecione apenas as colunas necessárias e mantenha essa ordem compatível com a struct.

Executar statement

err := sqlDB.NewStatement(
	ctx,
	"UPDATE users SET name = $1 WHERE id = $2",
	name,
	id,
).Execute()

Use NewStatement para INSERT, UPDATE e DELETE quando não for necessário retornar uma linha.

Paginação

pageRequest := types.NewPageRequest(
	1,
	20,
	[]types.Sort{types.NewSort(types.ASC, "name")},
)

page, err := sqlDB.NewPageQuery[User](
	ctx,
	pageRequest,
	"SELECT id, name, email FROM users WHERE active = $1",
	true,
).Execute()

O resultado expõe:

page.Items      // []User
page.TotalItems // uint64

cuidado

O nome do campo de ordenação entra na SQL gerada. Não aceite um valor arbitrário da requisição; converta opções conhecidas para colunas permitidas.

Query com cache

userCache := cacheDB.NewCache[User]("user-"+id, 15*time.Minute)
user, err := sqlDB.NewCachedQuery[User](
	ctx,
	userCache,
	"SELECT id, name, email FROM users WHERE id = $1",
	id,
).One()

Inicialize cacheDB antes de executar queries com cache.

Migrações

SQL_DB_MIGRATION=true
MIGRATION_SOURCE_URL=./migrations

Os arquivos seguem o formato aceito por golang-migrate:

migrations/
  000001_create_users.up.sql
  000001_create_users.down.sql

As migrações up são executadas por sqlDB.Initialize(). O diretório padrão é ./migrations.

Pool

Variável	Padrão
SQL_DB_MAX_OPEN_CONNS	10
SQL_DB_MAX_IDLE_CONNS	3

Para múltiplas operações atômicas, consulte Transações.