sqlamble

For those who hate SQL inside the Go code.

The sqlamble tool allows you to embed your SQL queries into the Golang code in structural read-only way.

Why?

When you are looking for a golang sql embed in Google, the most popular answer is that kind of examples:

package mypkg

import _ "embed"

//go:embed sql/my_query.sql
var myQuery string

And there is nothing wrong with this way of embedding SQL queries, until you have tons of them:

sql
├── users
│   ├── get_list.sql
│   ├── get_user_data.sql
│   └── ... other 100500 queries
├── orders
│   └── ... other 100500 queries
└── ... other 100500 directories

The sqlamble takes all these files on the go generate stage and converts them into the structured set of the read-only strings. For example:

query := queries.Users().GetListQuery()

Installation

The go 1.24 is a minimal requirement for the sqlamble, so the go tool is a preferred way to install:

go get -tool github.com/kukymbr/sqlamble/cmd/sqlamble@latest

Usage

The sqlamble --help output:

Generates structured SQL getters in go code.
See https://github.com/kukymbr/sqlamble for info.

Usage:
  sqlamble [flags]

Flags:
      --ext strings           If set, source files will be filtered by these suffixes in names (default [.sql])
      --fmt string            Formatter used to format generated go files (gofmt|noop) (default "gofmt")
  -h, --help                  help for sqlamble
      --package string        Target package name of the generated code (default "queries")
      --query-suffix string   Suffix for query getter functions (default "Query")
  -s, --silent                Silent mode
      --source string         Directory containing SQL files (default ".")
      --target string         Directory for the generated Go files (default "internal/queries")
  -v, --version               version for sqlamble

1. Create sql files directory and put some SQL inside it (any level of subdirectories is supported), for example sql/.
2. Add the go file with a //go:generate directive, for example sql/generate.go:

    package sql  
   
   //go:generate go tool sqlamble --package=queries --target=../internal/queries

3. Run the go generate command:

   go generate ./sql

4. Use the types, generated into the queries package (see the generated internal/queries/ directory):

   package users
   
   func GetUsers() []User {
       query := queries.Users().GetListQuery()   
       // ... go fetch some users
   }
   
   func GetUser() User {
    query := queries.Users().SingleUser().GetUserDataQuery()
       // ... go fetch some user data
   }

See the example directory for a full example.

Hidden features

In fact, it's okay to embed any type of string content into the Go code using the sqlamble, because there is no parsing of the SQL syntax itself.

For example, you could embed set of YAMLs:

go tool sqlamble --package=configs --target=internal/configs --query-suffix=YAML --ext=.yaml,.yml

See the generator's testdata and test code for an example.

Comparing with sqlc

The sqlc is a powerful tool, generating code from the SQL queries. There is a principal difference with sqlamble: sqlamble is just an "embedder", generating constant queries getters. We don't parse any SQL, don't wrap execution logic and do not generate any data-related models or types. Just moving the SQL code away.

Contributing

Please refer to the CONTRIBUTING.md doc.

License

MIT.