starfield v1.0.0 is now available.

starfield is an sqlc plugin based on sqlc-gen-go, the official Go plugin for sqlc.

sqlc is a great way to bring build-time safety to your database queries. You define your database structure in SQL and write your Business Logic™ queries in simple SQL files. These are then compiled into actual Go code under a db package which can be called like any other code.

Build-time safety applies:

• When you run sqlc and it parses your database structure, migrations, and all defined queries. If you typo or reference a non-existent column, your build will fail.
• When you build your Go program. If you've changed your database structure or queries without updating the code that calls them, your build will fail.

So, what was wrong with sqlc-gen-go? Just that it didn't go far enough. I found myself swimming in queries whose existence was purely for CRUD operations. These queries all followed the same pattern, and that meant that helper functions could be generated for them, too.

I knew it was going to be a challenge to maintain support for Postgres, a database engine I don't generally use, so I made the decision to remove support for it.¹ I might regret that one day.

#We are the function generation

Compared to sqlc-gen-go the most notable change is the generation of a set of lookup and CRUD methods for each table in the schema. These are available without the need to define any queries yourself.

To illustrate, let's take the iconic sample table, authors. Given an authors table with columns id, deleted_at, name, email, and birthdate, the following functions would be generated for creating and finding records:

func GetAuthorTableStatus() (TableStatus, error)
func CreateAuthor(*Author) *Author
func FindAuthor(int) (*Author, bool)
func FindAuthorUnscoped(int) (*Author, bool)
func FindAuthors() []*Author
func FindAuthorsUnscoped() []*Author
func FindAuthorsByName(string) []*Author
func FindAuthorsByNameUnscoped(string) []*Author
func FindAuthorByName(string) (*Author, bool)
func FindAuthorsByEmail(string) []*Author
func FindAuthorsByEmailUnscoped(string) []*Author
func FindAuthorByEmail(string) (*Author, bool)
func FindAuthorsByBirthdate(sql.Null[time.Time]) []*Author
func FindAuthorsByBirthdateUnscoped(sql.Null[time.Time]) []*Author
func FindAuthorByBirthdate(time.Time) (*Author, bool)

And the following for managing an instance of Author²:

func (self *Author) Reload()
func (self *Author) Delete() bool
func (self *Author) Restore() bool
func (self *Author) HardDelete() bool
func (self *Author) UpdateName(string) bool
func (self *Author) UpdateEmail(string) bool
func (self *Author) UpdateBirthdate(time.Time) bool
func (self *Author) ClearBirthdate() bool

This has greatly reduced the need to define these (tbh) boring queries. In lighthouse each table only needs a handful to be defined as most interactions with the database can be done using with the generated functions above.

For full documentation and usage examples check out the readme.

You can download starfield as a prebuilt binary from GitHub releases or compile it from source.