What is SQL to sqlc Generator?
sqlc takes a fundamentally different approach from traditional ORMs: instead of mapping objects to tables at runtime, it reads your SQL queries at build time and generates fully typed Go code that calls those queries. You write plain SQL with special comment annotations like -- name: GetUser :one, and sqlc produces Go structs for result rows, typed parameter structs, and a Querier interface that makes dependency injection and testing straightforward. This converter goes one step further by accepting raw CREATE TABLE statements alongside annotated queries and producing three files: a sqlc.yaml v2 configuration tuned to your chosen engine, a clean schema.sql containing only the DDL statements, and a query.sql.go file with model structs, query constants, function implementations, and the Querier interface. The result is production-ready Go code that eliminates an entire class of runtime SQL errors.
How to Use
- Set the Go package name (defaults to "db") and choose your database engine — PostgreSQL, MySQL, or SQLite
- Optionally toggle JSON struct tags and prepared query generation
- Paste your CREATE TABLE statements followed by annotated SQL queries using the -- name: convention
- Click Generate sqlc Code to produce sqlc.yaml, schema.sql, and query.sql.go in the output tabs
- Copy each file into the corresponding location within your Go module
Why Use This Tool?
Tips & Best Practices
- Use the :one suffix for queries returning a single row, :many for lists, :exec for fire-and-forget statements, and :execrows when you need the affected row count
- The converter infers parameter names from INSERT column order and WHERE clause column references, so name your placeholders consistently
- For PostgreSQL, use $1, $2 positional parameters; for MySQL and SQLite, use ? placeholders
- Add the sqlc-generated package to your go.mod by running go get github.com/google/uuid if your schema includes UUID columns
Frequently Asked Questions
How does sqlc map SQL types to Go types?
INTEGER and SERIAL map to int32, BIGINT and BIGSERIAL map to int64, SMALLINT maps to int16, TINYINT maps to int8, VARCHAR and TEXT map to string, BOOLEAN maps to bool, TIMESTAMP and TIMESTAMPTZ map to time.Time, DECIMAL and NUMERIC map to string (to preserve precision), FLOAT and REAL map to float32, DOUBLE maps to float64, UUID maps to uuid.UUID, and JSON/JSONB map to interface{}. Nullable columns use sql.Null* wrapper types.
When should I avoid sqlc and use a traditional ORM instead?
sqlc excels when you know your queries upfront and want compile-time safety. If your application requires dynamic query construction at runtime, ad-hoc filtering, or complex eager-loading of nested relationships, a full ORM like GORM or Ent may be more practical. sqlc also does not handle database migrations — pair it with golang-migrate or goose for schema management.
What do the sqlc query annotation suffixes mean?
:one returns a single struct (error if zero or multiple rows), :many returns a slice of structs, :exec runs the statement and returns only an error, and :execrows runs the statement and returns the number of affected rows as int64. These suffixes determine the Go function signature that sqlc generates.
How are nullable columns handled in the generated Go code?
Nullable columns that are not primary keys use sql.Null* types from the standard library — sql.NullString, sql.NullInt32, sql.NullInt64, sql.NullFloat64, sql.NullBool, and sql.NullTime. These types carry a Valid boolean alongside the value, letting you check for null without using Go pointers.
Is my SQL schema or query data transmitted to any server?
No. The parser and code generator run entirely within your browser. Your SQL statements, table definitions, and queries never leave your device during the conversion process.
Can I use the generated code with pgx instead of database/sql?
Yes. The sqlc.yaml configuration sets sql_package to pgx/v5/stdlib for PostgreSQL, which is compatible with both the standard database/sql interface and the native pgx driver. For direct pgx usage, adjust the sql_package setting to pgx/v5 after generating.
Real-world Examples
Building a REST API with typed SQL queries
A Go microservice exposes CRUD endpoints for an author resource. The developer writes the SQL queries with sqlc annotations, generates the typed Go code, and wires the Queries struct into HTTP handlers.
Analytics dashboard with aggregate queries
A dashboard service tracks daily active users and revenue. sqlc generates typed functions for each aggregate query, eliminating the risk of scanning the wrong column type.