repository·main·Indexed 23 days ago
https://github.com/stephenafamo/bobA multi-layered Go SQL access toolkit providing a progressive path from a fluent query builder to a full type-safe ORM and factory code generation. Bob supports Postgres, MySQL/MariaDB, and SQLite, offering four layers of functionality: a dialect-specific query builder, ORM code generation based on database schemas, factory generation for testing relational data, and Go code generation for hand-crafted SQL queries.
Bob is a Go SQL access toolkit designed for correctness, convenience without magic, and cooperation with the standard library. It can be adopted progressively, starting from raw SQL strings and moving toward fully typed models and factories.
Bob provides full support (Queries, Models, ORM Gen, Factory Gen, and Query Gen) for:
Bob is a set of Go packages and tools designed for working with SQL databases. It is built on three core philosophies: Correctness (following specifications closely), Convenience (providing helpful tools without unexplainable magic), and Cooperation (working well with the standard library and other tools).
Bob allows for progressive adoption, starting from raw SQL query strings and moving towards fully typed queries with generated models and factories.
Bob intentionally excludes certain features to maintain simplicity and follow best practices:
createdAt/updatedAt): Bob does not implement these at the ORM level, as it is considered better practice to implement them at the database level.Bob includes several features that are either not supported or more difficult to implement in SQLBoiler:
has-one-through, has-many-through)Bob and GORM represent two different philosophies for SQL access in Go. Use Bob if you prefer a database-first approach with high type safety and incremental adoption. Use GORM if you prefer a code-first approach and require a large ecosystem of existing plugins.
| Feature | Bob | GORM |
|---|---|---|
| Source of Truth | Database-first: You manage your DB with SQL/migrations and generate models from it. | Code-first: You define models in Go and GORM manages the database schema. |
| Type Safety | High: Generates type-safe code for everything, including relationships. Errors are caught at compile time. | Low: Relies heavily on interface{} and magic strings, which can lead to runtime panics. |
| Query Building | Powerful: Supports almost any Select, Update, Insert, or Delete query supported by the dialect. | Limited: Restricted to a subset of common features across supported dialects. |
| Ecosystem | Standard Library: Works with *sql.DB, making it compatible with any standard library package. | Specialized: Requires specific drivers, though it has many community plugins. |
| Adoption | Incremental: You can use parts of Bob (like just the query builder) without full adoption. | All-or-nothing: Requires full adoption of the framework. |
| Testability | High: Includes generated factories (inspired by Ruby's FactoryBot) for easy model testing. | Low: Does not provide built-in testing helpers. |
Each model exposes an R.Loaded struct containing boolean flags for each relationship. This allows you to distinguish between a relationship that hasn't been loaded (Loaded.X == false) and one that was loaded but returned no results (Loaded.X == true and R.X == nil or len(R.X) == 0).
Important: If you manually assign to R (e.g., jet.R.Pilot = pilot), you are responsible for manually updating R.Loaded to keep it in sync. The generated APIs (LoadX, Preload, ThenLoad, AttachX, InsertX) handle this automatically.
jet, err := models.FindJet(ctx, db, 1)
if !jet.R.Loaded.Pilot {
// the pilot relationship has not been loaded
}
if err := jet.LoadPilot(ctx, db); err != nil {
return err
}
// jet.R.Loaded.Pilot is now true.
if jet.R.Loaded.Pilot && jet.R.Pilot == nil {
// definitively no pilot
}
// For to-many:
pilot, err := models.FindPilot(ctx, db, 1)
if err := pilot.LoadJets(ctx, db); err != nil {
return err
}
// pilot.R.Loaded.Jets is true even if the pilot has no jets.
if pilot.R.Loaded.Jets && len(pilot.R.Jets) == 0 {
// definitively zero jets
}Bob supports automatic nesting of related data by using specific naming patterns for returned columns:
related_table__column_name (double underscore): Indicates a to-one relationship.related_table.column_name (dot): Indicates a to-many relationship.When using the All() method, Bob transforms and nests the rows according to these patterns. You can use the --prefix annotation in your SQL to simplify column naming for joins.
-- Nested query example using --prefix
SELECT
users.*,
--prefix:videos.
videos.*,
--prefix:videos.sponsor__
sponsors.*
FROM users
LEFT JOIN videos ON videos.user_id = users.id
INNER JOIN sponsors ON videos.sponsor_id = sponsors.id
WHERE users.id IN ($1);Bob's code generation engine is entirely plugin-based. Every output produced by Bob—including models, factories, and enums—is implemented as a plugin. Custom plugins are treated as first-class citizens, utilizing the same interfaces and mechanisms as the built-in plugins.
Plugins are categorized into two types:
models, enums, or factory).where, loaders, and joins extend the models output).Bob factories are objects used to create templates for your models, which in turn can be used to generate model instances for testing. You can create a factory using factory.New() and then generate specific templates (e.g., NewJet) using mods to define how the models should be populated.
To speed up testing, you can set 'base mods' on the factory itself. These mods will be automatically applied to every new template generated by that factory instance.
f := factory.New()
// Set base mods that apply to ALL templates from this factory
f.AddBaseJetMods(
factory.JetMods.RandomID(),
factory.JetMods.RandomAirportID(),
)
// These templates will automatically include the base mods
jetTemplate1 := f.NewJet()
jetTemplate2 := f.NewJet()
// Clear base mods if needed
f.ClearBaseJetMods()Bob does not provide built-in support for automatic createdAt/updatedAt timestamps or soft deletes.
createdAt and updatedAt logic at the database level rather than within the ORM to avoid unnecessary complexity.squirrel or goqu.