Tutorial: Acessando um banco de dados relacional
Este tutorial apresenta o básico de como acessar um banco de dados relacional
com Go e o pacote database/sql da sua biblioteca padrão.
Você vai aproveitar melhor este tutorial se já tiver uma familiaridade básica com Go e suas ferramentas. Se este for o seu primeiro contato com Go, veja Tutorial: Primeiros passos com Go para uma introdução rápida.
O pacote database/sql que você vai usar
inclui tipos e funções para conectar a bancos de dados, executar transações,
cancelar uma operação em andamento e mais. Para mais detalhes sobre como usar o
pacote, veja Acessando bancos de dados.
Neste tutorial, você vai criar um banco de dados e depois escrever código para acessá-lo. O seu projeto de exemplo será um repositório de dados sobre discos de jazz antigos.
Neste tutorial, você vai avançar pelas seguintes seções:
- Criar uma pasta para o seu código.
- Configurar um banco de dados.
- Importar o driver do banco de dados.
- Obter um handle do banco de dados e conectar.
- Consultar várias linhas.
- Consultar uma única linha.
- Adicionar dados.
Nota: Para outros tutoriais, veja Tutoriais.
Pré-requisitos
- Uma instalação do sistema de gerenciamento de banco de dados relacional MySQL (DBMS).
- Uma instalação do Go. Para as instruções de instalação, veja Instalando o Go.
- Uma ferramenta para editar seu código. Qualquer editor de texto que você tenha vai funcionar bem.
- Um terminal de comandos. O Go funciona bem em qualquer terminal no Linux e no Mac, e no PowerShell ou cmd no Windows.
Criar uma pasta para o seu código
Para começar, crie uma pasta para o código que você vai escrever.
-
Abra um prompt de comando e vá para o seu diretório home.
No Linux ou Mac:
$ cdNo Windows:
C:\> cd %HOMEPATH%Pelo resto do tutorial, vamos mostrar um $ como prompt. Os comandos que usamos também vão funcionar no Windows.
-
No prompt de comando, crie um diretório para o seu código chamado data-access.
$ mkdir data-access $ cd data-access -
Crie um módulo no qual você possa gerenciar as dependências que vai adicionar durante este tutorial.
Execute o comando
go mod init, informando o caminho do módulo do seu novo código.$ go mod init example/data-access go: creating new go.mod: module example/data-accessEste comando cria um arquivo go.mod no qual as dependências que você adicionar serão listadas para rastreamento. Para saber mais, veja Gerenciando dependências.
Nota: No desenvolvimento real, você especificaria um caminho de módulo mais específico para as suas próprias necessidades. Para saber mais, veja Gerenciando dependências.
Em seguida, você vai criar um banco de dados.
Configurar um banco de dados
Nesta etapa, você vai criar o banco de dados com o qual vai trabalhar. Você vai usar a CLI do próprio DBMS para criar o banco e a tabela, além de adicionar dados.
Você vai criar um banco de dados com dados sobre gravações de jazz antigas em vinil.
O código aqui usa a CLI do MySQL, mas a maioria dos DBMS tem a sua própria CLI com recursos semelhantes.
-
Abra um novo prompt de comando.
-
Na linha de comando, entre no seu DBMS, como no exemplo a seguir para o MySQL.
$ mysql -u root -p Enter password: mysql> -
No prompt de comando do
mysql, crie um banco de dados.mysql> create database recordings; -
Mude para o banco de dados que você acabou de criar para poder adicionar tabelas.
mysql> use recordings; Database changed -
No seu editor de texto, na pasta data-access, crie um arquivo chamado create-tables.sql para guardar o script SQL que adiciona as tabelas.
-
No arquivo, cole o código SQL a seguir e salve o arquivo.
DROP TABLE IF EXISTS album; CREATE TABLE album ( id INT AUTO_INCREMENT NOT NULL, title VARCHAR(128) NOT NULL, artist VARCHAR(255) NOT NULL, price DECIMAL(5,2) NOT NULL, PRIMARY KEY (`id`) ); INSERT INTO album (title, artist, price) VALUES ('Blue Train', 'John Coltrane', 56.99), ('Giant Steps', 'John Coltrane', 63.99), ('Jeru', 'Gerry Mulligan', 17.99), ('Sarah Vaughan', 'Sarah Vaughan', 34.98);Neste código SQL, você:
-
Exclui (drop) uma tabela chamada
album. Executar este comando primeiro facilita rodar o script de novo mais tarde, se você quiser recomeçar com a tabela. -
Cria uma tabela
albumcom quatro colunas:title,artisteprice. O valor deidde cada linha é criado automaticamente pelo DBMS. -
Adiciona quatro linhas com valores.
-
-
No prompt de comando do
mysql, execute o script que você acabou de criar.Você vai usar o comando
sourcena seguinte forma:mysql> source /caminho/para/create-tables.sql -
No prompt de comando do seu DBMS, use uma instrução
SELECTpara verificar se você criou a tabela com os dados com sucesso.mysql> select * from album; +----+---------------+----------------+-------+ | id | title | artist | price | +----+---------------+----------------+-------+ | 1 | Blue Train | John Coltrane | 56.99 | | 2 | Giant Steps | John Coltrane | 63.99 | | 3 | Jeru | Gerry Mulligan | 17.99 | | 4 | Sarah Vaughan | Sarah Vaughan | 34.98 | +----+---------------+----------------+-------+ 4 rows in set (0.00 sec)
Em seguida, você vai escrever um código em Go para conectar e poder fazer consultas.
Encontrar e importar um driver de banco de dados
Agora que você tem um banco de dados com alguns dados, vamos começar o seu código em Go.
Encontre e importe um driver de banco de dados que vai traduzir as requisições
que você faz pelas funções do pacote database/sql em requisições que o banco
de dados entende.
-
No seu navegador, acesse a página da wiki SQLDrivers para identificar um driver que você possa usar.
Use a lista da página para identificar o driver que você vai usar. Para acessar o MySQL neste tutorial, você vai usar o Go-MySQL-Driver.
-
Anote o nome do pacote do driver – aqui,
github.com/go-sql-driver/mysql. -
Usando o seu editor de texto, crie um arquivo no qual escrever o seu código em Go e salve o arquivo como main.go na pasta data-access que você criou antes.
-
No main.go, cole o código a seguir para importar o pacote do driver.
package main import "github.com/go-sql-driver/mysql"Neste código, você:
-
Adiciona o seu código a um pacote
mainpara poder executá-lo de forma independente. -
Importa o driver do MySQL
github.com/go-sql-driver/mysql.
-
Com o driver importado, você vai começar a escrever o código para acessar o banco de dados.
Obter um handle do banco de dados e conectar
Agora escreva um código em Go que dê acesso ao banco de dados por meio de um handle.
Você vai usar um ponteiro para uma struct sql.DB, que representa o acesso a um
banco de dados específico.
Escrever o código
-
No main.go, abaixo do código
importque você acabou de adicionar, cole o código Go a seguir para criar um handle do banco de dados.var db *sql.DB func main() { // Capture connection properties. cfg := mysql.NewConfig() cfg.User = os.Getenv("DBUSER") cfg.Passwd = os.Getenv("DBPASS") cfg.Net = "tcp" cfg.Addr = "127.0.0.1:3306" cfg.DBName = "recordings" // Get a database handle. var err error db, err = sql.Open("mysql", cfg.FormatDSN()) if err != nil { log.Fatal(err) } pingErr := db.Ping() if pingErr != nil { log.Fatal(pingErr) } fmt.Println("Connected!") }Neste código, você:
-
Declara uma variável
dbdo tipo*sql.DB. Este é o seu handle do banco de dados.Tornar
dbuma variável global simplifica este exemplo. Em produção, você evitaria a variável global, por exemplo passando a variável para as funções que precisam dela ou encapsulando-a em uma struct. -
Usa o
Configdo driver MySQL – e o métodoFormatDSNdo tipo – para reunir as propriedades de conexão e formatá-las em um DSN para uma string de conexão.A struct
Configdeixa o código mais fácil de ler do que uma string de conexão seria. -
Chama
sql.Openpara inicializar a variáveldb, passando o valor retornado porFormatDSN. -
Verifica se há um erro de
sql.Open. Ele poderia falhar se, por exemplo, os detalhes da conexão com o banco não estivessem bem formados.Para simplificar o código, você está chamando
log.Fatalpara encerrar a execução e imprimir o erro no console. Em código de produção, você vai querer tratar os erros de forma mais elegante. -
Chama
DB.Pingpara confirmar que a conexão com o banco de dados funciona. Em tempo de execução, osql.Openpode não conectar imediatamente, dependendo do driver. Você está usandoPingaqui para confirmar que o pacotedatabase/sqlconsegue conectar quando precisar. -
Verifica se há um erro de
Ping, caso a conexão tenha falhado. -
Imprime uma mensagem se
Pingconectar com sucesso.
-
-
Perto do topo do arquivo main.go, logo abaixo da declaração do pacote, importe os pacotes de que você vai precisar para dar suporte ao código que acabou de escrever.
O topo do arquivo deve ficar assim:
package main import ( "database/sql" "fmt" "log" "os" "github.com/go-sql-driver/mysql" ) -
Salve o main.go.
Executar o código
-
Comece a rastrear o módulo do driver MySQL como dependência.
Use o
go getpara adicionar o módulo github.com/go-sql-driver/mysql como dependência do seu próprio módulo. Use o argumento ponto para significar “obter as dependências do código no diretório atual”.$ go get . go: added filippo.io/edwards25519 v1.1.0 go: added github.com/go-sql-driver/mysql v1.8.1O Go baixou essa dependência porque você a adicionou à declaração
importna etapa anterior. Para saber mais sobre o rastreamento de dependências, veja Adicionando uma dependência. -
No prompt de comando, defina as variáveis de ambiente
DBUSEReDBPASSpara uso pelo programa em Go.No Linux ou Mac:
$ export DBUSER=username $ export DBPASS=passwordNo Windows:
C:\Users\you\data-access> set DBUSER=username C:\Users\you\data-access> set DBPASS=password -
Na linha de comando, no diretório que contém o main.go, execute o código digitando
go runcom um argumento ponto para significar “execute o pacote no diretório atual”.$ go run . Connected!
Você consegue conectar! Em seguida, vamos consultar alguns dados.
Consultar várias linhas
Nesta seção, você vai usar Go para executar uma consulta SQL projetada para retornar várias linhas.
Para instruções SQL que podem retornar várias linhas, você usa o método Query
do pacote database/sql e depois percorre as linhas retornadas. (Você vai
aprender a consultar uma única linha mais adiante, na seção
Consultar uma única linha.)
Escrever o código
-
No main.go, logo acima de
func main, cole a definição a seguir de uma structAlbum. Você vai usá-la para guardar os dados das linhas retornadas pela consulta.type Album struct { ID int64 Title string Artist string Price float32 } -
Abaixo de
func main, cole a funçãoalbumsByArtista seguir para consultar o banco de dados.// albumsByArtist queries for albums that have the specified artist name. func albumsByArtist(name string) ([]Album, error) { // An albums slice to hold data from returned rows. var albums []Album rows, err := db.Query("SELECT * FROM album WHERE artist = ?", name) if err != nil { return nil, fmt.Errorf("albumsByArtist %q: %v", name, err) } defer rows.Close() // Loop through rows, using Scan to assign column data to struct fields. for rows.Next() { var alb Album if err := rows.Scan(&alb.ID, &alb.Title, &alb.Artist, &alb.Price); err != nil { return nil, fmt.Errorf("albumsByArtist %q: %v", name, err) } albums = append(albums, alb) } if err := rows.Err(); err != nil { return nil, fmt.Errorf("albumsByArtist %q: %v", name, err) } return albums, nil }Neste código, você:
-
Declara uma fatia
albumsdo tipoAlbumque você definiu. Ela vai guardar os dados das linhas retornadas. Os nomes e tipos dos campos da struct correspondem aos nomes e tipos das colunas do banco de dados. -
Usa
DB.Querypara executar uma instruçãoSELECTque consulta os álbuns com o nome de artista especificado.O primeiro parâmetro de
Queryé a instrução SQL. Depois dele, você pode passar zero ou mais parâmetros de qualquer tipo. Eles servem de lugar para você informar os valores dos parâmetros na sua instrução SQL. Ao separar a instrução SQL dos valores dos parâmetros (em vez de concatená- los com, por exemplo,fmt.Sprintf), você permite que o pacotedatabase/sqlenvie os valores separados do texto SQL, eliminando qualquer risco de injeção de SQL. -
Adia o fechamento de
rows(comdefer) para que os recursos que ele mantém sejam liberados quando a função terminar. -
Percorre as linhas retornadas, usando
Rows.Scanpara atribuir os valores das colunas de cada linha aos campos da structAlbum.Scanrecebe uma lista de ponteiros para valores Go, onde os valores das colunas serão escritos. Aqui, você passa ponteiros para os campos da variávelalb, criada com o operador&.Scanescreve por meio dos ponteiros para atualizar os campos da struct. -
Dentro do laço, verifica se há um erro ao copiar os valores das colunas para os campos da struct.
-
Dentro do laço, adiciona o novo
albà fatiaalbums. -
Depois do laço, verifica se há um erro na consulta como um todo, usando
rows.Err. Repare que, se a própria consulta falhar, verificar o erro aqui é a única forma de descobrir que os resultados estão incompletos.
-
-
Atualize a sua função
mainpara chamaralbumsByArtist.No final de
func main, adicione o código a seguir.albums, err := albumsByArtist("John Coltrane") if err != nil { log.Fatal(err) } fmt.Printf("Albums found: %v\n", albums)No código novo, você agora:
-
Chama a função
albumsByArtistque você adicionou, atribuindo o valor retornado a uma nova variávelalbums. -
Imprime o resultado.
-
Executar o código
Na linha de comando, no diretório que contém o main.go, execute o código.
$ go run .
Connected!
Albums found: [{1 Blue Train John Coltrane 56.99} {2 Giant Steps John Coltrane 63.99}]
Em seguida, você vai consultar uma única linha.
Consultar uma única linha
Nesta seção, você vai usar Go para consultar uma única linha no banco de dados.
Para instruções SQL que você sabe que vão retornar no máximo uma linha, você pode
usar QueryRow, que é mais simples do que usar um laço com Query.
Escrever o código
-
Abaixo de
albumsByArtist, cole a funçãoalbumByIDa seguir.// albumByID queries for the album with the specified ID. func albumByID(id int64) (Album, error) { // An album to hold data from the returned row. var alb Album row := db.QueryRow("SELECT * FROM album WHERE id = ?", id) if err := row.Scan(&alb.ID, &alb.Title, &alb.Artist, &alb.Price); err != nil { if err == sql.ErrNoRows { return alb, fmt.Errorf("albumsById %d: no such album", id) } return alb, fmt.Errorf("albumsById %d: %v", id, err) } return alb, nil }Neste código, você:
-
Usa
DB.QueryRowpara executar uma instruçãoSELECTque consulta um álbum com o ID especificado.Ele retorna um
sql.Row. Para simplificar o código que chama a função (o seu código!),QueryRownão retorna um erro. Em vez disso, ele se encarrega de devolver qualquer erro da consulta (comosql.ErrNoRows) depois, a partir deRows.Scan. -
Usa
Row.Scanpara copiar os valores das colunas para os campos da struct. -
Verifica se há um erro de
Scan.O erro especial
sql.ErrNoRowsindica que a consulta não retornou linhas. Normalmente, vale a pena substituir esse erro por um texto mais específico, como “no such album” aqui.
-
-
Atualize
mainpara chamaralbumByID.No final de
func main, adicione o código a seguir.// Hard-code ID 2 here to test the query. alb, err := albumByID(2) if err != nil { log.Fatal(err) } fmt.Printf("Album found: %v\n", alb)No código novo, você agora:
-
Chama a função
albumByIDque você adicionou. -
Imprime o ID do álbum retornado.
-
Executar o código
Na linha de comando, no diretório que contém o main.go, execute o código.
$ go run .
Connected!
Albums found: [{1 Blue Train John Coltrane 56.99} {2 Giant Steps John Coltrane 63.99}]
Album found: {2 Giant Steps John Coltrane 63.99}
Em seguida, você vai adicionar um álbum ao banco de dados.
Adicionar dados
Nesta seção, você vai usar Go para executar uma instrução SQL INSERT que
adiciona uma nova linha ao banco de dados.
Você já viu como usar Query e QueryRow com instruções SQL que retornam
dados. Para executar instruções SQL que não retornam dados, você usa Exec.
Escrever o código
-
Abaixo de
albumByID, cole a funçãoaddAlbuma seguir para inserir um novo álbum no banco de dados e, em seguida, salve o main.go.// addAlbum adds the specified album to the database, // returning the album ID of the new entry func addAlbum(alb Album) (int64, error) { result, err := db.Exec("INSERT INTO album (title, artist, price) VALUES (?, ?, ?)", alb.Title, alb.Artist, alb.Price) if err != nil { return 0, fmt.Errorf("addAlbum: %v", err) } id, err := result.LastInsertId() if err != nil { return 0, fmt.Errorf("addAlbum: %v", err) } return id, nil }Neste código, você:
-
Usa
DB.Execpara executar uma instruçãoINSERT.Assim como
Query,Execrecebe uma instrução SQL seguida dos valores dos parâmetros da instrução. -
Verifica se há erro na tentativa de
INSERT. -
Obtém o ID da linha inserida no banco de dados usando
Result.LastInsertId. -
Verifica se há erro na tentativa de obter o ID.
-
-
Atualize
mainpara chamar a nova funçãoaddAlbum.No final de
func main, adicione o código a seguir.albID, err := addAlbum(Album{ Title: "The Modern Sound of Betty Carter", Artist: "Betty Carter", Price: 49.99, }) if err != nil { log.Fatal(err) } fmt.Printf("ID of added album: %v\n", albID)No código novo, você agora:
- Chama
addAlbumcom um novo álbum, atribuindo o ID do álbum que você está adicionando a uma variávelalbID.
- Chama
Executar o código
Na linha de comando, no diretório que contém o main.go, execute o código.
$ go run .
Connected!
Albums found: [{1 Blue Train John Coltrane 56.99} {2 Giant Steps John Coltrane 63.99}]
Album found: {2 Giant Steps John Coltrane 63.99}
ID of added album: 5
Conclusão
Parabéns! Você acabou de usar Go para executar ações simples com um banco de dados relacional.
Próximos tópicos sugeridos:
-
Dê uma olhada no guia de acesso a dados, que inclui mais informações sobre os assuntos apenas tocados aqui.
-
Se você é novo em Go, vai encontrar boas práticas úteis descritas em Effective Go e Como escrever código Go.
-
O Go Tour é uma ótima introdução passo a passo aos fundamentos do Go.
Código completo
Esta seção contém o código da aplicação que você constrói com este tutorial.
package main
import (
"database/sql"
"fmt"
"log"
"os"
"github.com/go-sql-driver/mysql"
)
var db *sql.DB
type Album struct {
ID int64
Title string
Artist string
Price float32
}
func main() {
// Capture connection properties.
cfg := mysql.NewConfig()
cfg.User = os.Getenv("DBUSER")
cfg.Passwd = os.Getenv("DBPASS")
cfg.Net = "tcp"
cfg.Addr = "127.0.0.1:3306"
cfg.DBName = "recordings"
// Get a database handle.
var err error
db, err = sql.Open("mysql", cfg.FormatDSN())
if err != nil {
log.Fatal(err)
}
pingErr := db.Ping()
if pingErr != nil {
log.Fatal(pingErr)
}
fmt.Println("Connected!")
albums, err := albumsByArtist("John Coltrane")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Albums found: %v\n", albums)
// Hard-code ID 2 here to test the query.
alb, err := albumByID(2)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Album found: %v\n", alb)
albID, err := addAlbum(Album{
Title: "The Modern Sound of Betty Carter",
Artist: "Betty Carter",
Price: 49.99,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("ID of added album: %v\n", albID)
}
// albumsByArtist queries for albums that have the specified artist name.
func albumsByArtist(name string) ([]Album, error) {
// An albums slice to hold data from returned rows.
var albums []Album
rows, err := db.Query("SELECT * FROM album WHERE artist = ?", name)
if err != nil {
return nil, fmt.Errorf("albumsByArtist %q: %v", name, err)
}
defer rows.Close()
// Loop through rows, using Scan to assign column data to struct fields.
for rows.Next() {
var alb Album
if err := rows.Scan(&alb.ID, &alb.Title, &alb.Artist, &alb.Price); err != nil {
return nil, fmt.Errorf("albumsByArtist %q: %v", name, err)
}
albums = append(albums, alb)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("albumsByArtist %q: %v", name, err)
}
return albums, nil
}
// albumByID queries for the album with the specified ID.
func albumByID(id int64) (Album, error) {
// An album to hold data from the returned row.
var alb Album
row := db.QueryRow("SELECT * FROM album WHERE id = ?", id)
if err := row.Scan(&alb.ID, &alb.Title, &alb.Artist, &alb.Price); err != nil {
if err == sql.ErrNoRows {
return alb, fmt.Errorf("albumsById %d: no such album", id)
}
return alb, fmt.Errorf("albumsById %d: %v", id, err)
}
return alb, nil
}
// addAlbum adds the specified album to the database,
// returning the album ID of the new entry
func addAlbum(alb Album) (int64, error) {
result, err := db.Exec("INSERT INTO album (title, artist, price) VALUES (?, ?, ?)", alb.Title, alb.Artist, alb.Price)
if err != nil {
return 0, fmt.Errorf("addAlbum: %v", err)
}
id, err := result.LastInsertId()
if err != nil {
return 0, fmt.Errorf("addAlbum: %v", err)
}
return id, nil
}