Pular para o conteúdo principal

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
O sqlc gera structs e métodos de consulta em Go diretamente a partir do SQL, de modo que o código da sua aplicação chama funções Go comuns em vez de construir consultas em tempo de execução. Não há uma camada de ORM entre o seu código e o SQL que você escreveu. Este guia configura uma pequena tabela posts, gera código com o sqlc para o MySQL e o executa em um servidor ativo.

Instalando o sqlc

Instale o sqlc com o Homebrew, ou com go install se preferir gerenciá-lo como uma ferramenta Go:
Confirme a versão:

Estrutura do Projeto

Crie um módulo Go e três arquivos: um schema, um arquivo de consultas e um arquivo de configuração do sqlc.
schema.sql define a tabela a partir da qual o sqlc vai gerar os tipos. body não tem a restrição NOT NULL, o que importa mais adiante:

Escrevendo Consultas Anotadas

O sqlc lê arquivos SQL comuns e transforma um comentário -- name: acima de cada instrução em um método Go gerado. A palavra após o nome da consulta define a forma do retorno: :one para uma única linha, :many para um slice, :exec para nenhum valor de retorno, :execresult para o sql.Result bruto e :execrows para a contagem de linhas afetadas. As instruções INSERT do MySQL não suportam RETURNING, então obter o ID de uma nova linha exige uma anotação dedicada. :execlastid chama sql.Result.LastInsertId() para você e o retorna diretamente:

Configurando o sqlc.yaml

sqlc.yaml aponta o sqlc para os arquivos de schema e de consultas e define o engine MySQL. Os caminhos são resolvidos em relação à localização do sqlc.yaml, não ao diretório de onde você executa o sqlc:
package e out nomeiam o pacote Go gerado e o diretório em que ele é gravado. sql_package: "database/sql" diz ao sqlc para gerar código para o database/sql da biblioteca padrão, que é o que o go-sql-driver/mysql implementa.

Gerando o Código

Isso produz três arquivos em posts/: db.go (a struct Queries e seu construtor), models.go (a struct Post) e query.sql.go (um método por consulta anotada). models.go é onde a coluna anulável body aparece:

Colunas Anuláveis Geram sql.NullString, Não um Pointer

Como body TEXT não tem a restrição NOT NULL, o sqlc gerou sql.NullString para ela, em vez de uma string simples ou um *string. A mesma regra se aplica a CreatePostParams, gerada a partir da lista de parâmetros da instrução INSERT:
Isso significa que cada inserção precisa construir um sql.NullString explicitamente, mesmo para passar um valor:
Para inserir uma linha sem body, defina Valid: false em vez de deixar o campo como uma string vazia. O valor zero de um sql.NullString{} vazio já tem Valid: false, então ele é equivalente a escrever sql.NullString{Valid: false} explicitamente:
Ler uma coluna anulável de volta exige verificar .Valid antes de confiar em .String:
Se uma coluna precisa permitir NULL, faça disso uma decisão deliberada de schema. Adicionar NOT NULL a body em schema.sql e executar sqlc generate novamente muda o campo gerado de sql.NullString para uma string simples em todos os lugares em que ele aparece, o que remove a verificação de .Valid de cada ponto de chamada.

Conectando e Executando Migrações

Crie o banco de dados e um usuário de aplicação com uma senha real, restrito a esse único banco de dados:
Aplique o schema.sql com o cliente mysql antes de executar a aplicação:
Adicione o driver e conecte-se por TCP com parseTime=true, que é necessário para que as colunas TIMESTAMP e DATETIME do MySQL sejam lidas como time.Time do Go em vez de []byte:

CreatePost Retorna int64, GetPost Recebe uint64

id BIGINT UNSIGNED é mapeado para uint64 em todos os lugares em que o sqlc o gera como coluna, incluindo o parâmetro id de GetPost. Mas CreatePost, gerado com :execlastid, retorna um int64 simples. Isso vem de sql.Result.LastInsertId(), que a biblioteca padrão define como int64 independentemente de a coluna ter sinal ou não. Passar um ID recém-criado para GetPost exige uma conversão explícita:
Executando o programa completo de ponta a ponta em um servidor ativo:
Verificado diretamente no banco de dados, independentemente da saída do próprio programa:

Ajustando o Pool de Conexões

O database/sql gerencia seu próprio pool de conexões por baixo de sql.Open, e a struct Queries gerada pelo sqlc usa qualquer pool que o *sql.DB passado a ela já tenha. Duas configurações importam especificamente para um backend MySQL:
SetConnMaxLifetime deve ser definido abaixo do wait_timeout do MySQL, cujo padrão neste servidor é 28800 segundos (8 horas). Sem isso, conexões que o MySQL já fechou do lado do servidor permanecem no pool do Go como entradas ociosas até que uma consulta em uma delas falhe.

Perguntas Frequentes

O sqlc executa contra um banco de dados ativo?

Somente quando você habilita isso explicitamente. sqlc generate analisa schema.sql e query.sql estaticamente e não precisa de um servidor em execução. sqlc vet e sqlc push podem se conectar a um banco de dados real para verificações adicionais, mas o fluxo básico de generate deste guia nunca abre uma conexão.

O que acontece se uma consulta em query.sql tiver um erro de sintaxe?

sqlc generate falha com um erro de análise que nomeia o arquivo e a linha antes de gerar qualquer coisa. Nada é gravado no diretório de saída em caso de falha, então uma consulta quebrada nunca produz código gerado obsoleto ou parcial.

O sqlc pode gerar código para INSERT … ON DUPLICATE KEY UPDATE?

Sim. O sqlc o analisa como uma instrução INSERT normal. Anote-a com :exec, :execresult, :execrows ou :execlastid, dependendo de qual parte do resultado você precisa, da mesma forma que qualquer outra inserção.

Solução de Problemas

Veja também

  • MySQL e ORMs — a abordagem de construção de consultas em tempo de execução à qual o sqlc é uma alternativa
  • Migrações de Schema no MySQL — versionar as mudanças de schema.sql com segurança depois que a tabela está em produção
  • Pool de Conexões no MySQL — dimensionamento do pool e conexões persistentes além dos padrões do database/sql