github.com/mitranim/gos
Go SQL, tool for decoding results into Go structs. Supports streaming. NOT AN ORM, and should be used instead of an ORM, in combination with a simple query builder (see below). See the sibling library "github.com/mitranim/sqlb": a simple query builder that supports converting structs into named arguments. • Decodes SQL records into Go structs. See `Query()`. • Supports nested records/structs. • Supports nilable nested records/structs in outer joins. • Supports streaming. See `QueryScanner()`. When decoding a row into a struct, Gos observes the following rules. 1. Columns are matched to public struct fields whose `db` tag exactly matches the column name. Private fields or fields without `db` are completely ignored. Example: 2. Fields of embedded structs are treated as part of the enclosing struct. For example, the following two definitions are completely equivalent. Same as: 3. Fields of nested non-embedded structs are matched with columns whose aliases look like `"outer_field.inner_field.innermost_field"` with arbitrary nesting. Example: 4. If every column from a nested struct is null or missing, the entire nested struct is considered null. If the field is not nilable (struct, not pointer to struct), this will produce an error. Otherwise, the field is left nil and not allocated. This convention is extremely useful for outer joins, where nested records are often null. Example: Gos is somewhat similar to https://github.com/jmoiron/sqlx. Key differences: • Supports null records in outer joins, as nested struct pointers. • Selects fields explicitly, by reflecting on the output struct. This allows YOU to write `select *`, but if the struct is lacking some of the fields, the DB will optimize them out of the query. • Simpler API, does not wrap `database/sql`. • Explicit field-column mapping, no hidden renaming. • Has only one tiny dependency (most deps in `go.mod` are test-only). • ... probably more Gos doesn't specially support SQL arrays. Generally speaking, SQL arrays are usable only for primitive types such as numbers or strings. Some databases, such as Postgres, have their own implementations of multi-dimensional arrays, which are non-standard and have so many quirks and limitations that it's more practical to just use JSON. Arrays of primitives are already supported in adapters such as "github.com/lib/pq", which are orthogonal to Gos and used in combination with it.
Readme
Go ↔︎ SQL: tool for decoding results into Go structs. Supports streaming.
Not an ORM, and should be used instead of an ORM, in combination with a simple query builder (see below).
Key features:
See the full documentation at https://pkg.go.dev/github.com/mitranim/gos.
See the sibling library https://pkg.go.dev/github.com/mitranim/sqlb: a simple query builder that supports scanning structs into named arguments.
Gos is somewhat similar to jmoiron/sqlx. Key differences:
select *, but if the struct is lacking some of the fields, the DB will optimize them out of the query.database/sql.go.mod are test-only).Like many similar libraries, when selecting fields for nested records, Gos relies on column aliases like "column_name.column_name". With enough nesting, they can become too long. At the time of writing, Postgres 12 has an identifier length limit of 63 and will silently truncate the remainder, causing queries to fail, or worse. One solution is shorter aliases, such as "1.2.3" from struct field indexes. We still want to support long alises for manually-written queries, which means the library would have to support both alias types, which could potentially cause collisions. Unclear what's the best approach.
Improved how Query and Scanner handle previously-existing values in the output, especially in regards to pointers.
When a row contains null, the corresponding Go value is now zeroed rather than ignored. The old non-zeroing behavior was aligned with encoding/json. The new behavior diverges from it.
When a row contains non-null and the corresponding Go value is a non-nil pointer, the value is written to the pointer's target, without replacing the pointer.
Query allows nil output, using conn.ExecContext to discard the result.
Support streaming via QueryScanner and Scanner.
Dependency update.
Breaking: moved query generation utils into https://pkg.go.dev/github.com/mitranim/sqlb.
Fixed an oversight in queryStruct and queryScalar that could lead to shadowing DB errors with ErrNoRows in some edge cases.
Added SqlQuery.QueryAppend.
Changed the license to Unlicense.
Breaking changes in named args utils for symmetry with database/sql.
Named().SqlArg -> NamedArg.SqlArgs -> NamedArgs.StructSqlArgs -> StructNamedArgs.Also moved some reflection-related utils to a tiny dependency.
First tagged release. Added SqlArgs and SqlQuery for query building.
Issues and pull requests are welcome! The development setup is simple:
git clone https://github.com/mitranim/gos
cd gos
go test
Tests currently require a local instance of Postgres on the default port. They create a separate "database", make no persistent changes, and drop it at the end.
I'm receptive to suggestions. If this library almost satisfies you but needs changes, open an issue or chat me up. Contacts: https://mitranim.com/#contacts
FAQs
Go SQL, tool for decoding results into Go structs. Supports streaming. NOT AN ORM, and should be used instead of an ORM, in combination with a simple query builder (see below). See the sibling library "github.com/mitranim/sqlb": a simple query builder that supports converting structs into named arguments. • Decodes SQL records into Go structs. See `Query()`. • Supports nested records/structs. • Supports nilable nested records/structs in outer joins. • Supports streaming. See `QueryScanner()`. When decoding a row into a struct, Gos observes the following rules. 1. Columns are matched to public struct fields whose `db` tag exactly matches the column name. Private fields or fields without `db` are completely ignored. Example: 2. Fields of embedded structs are treated as part of the enclosing struct. For example, the following two definitions are completely equivalent. Same as: 3. Fields of nested non-embedded structs are matched with columns whose aliases look like `"outer_field.inner_field.innermost_field"` with arbitrary nesting. Example: 4. If every column from a nested struct is null or missing, the entire nested struct is considered null. If the field is not nilable (struct, not pointer to struct), this will produce an error. Otherwise, the field is left nil and not allocated. This convention is extremely useful for outer joins, where nested records are often null. Example: Gos is somewhat similar to https://github.com/jmoiron/sqlx. Key differences: • Supports null records in outer joins, as nested struct pointers. • Selects fields explicitly, by reflecting on the output struct. This allows YOU to write `select *`, but if the struct is lacking some of the fields, the DB will optimize them out of the query. • Simpler API, does not wrap `database/sql`. • Explicit field-column mapping, no hidden renaming. • Has only one tiny dependency (most deps in `go.mod` are test-only). • ... probably more Gos doesn't specially support SQL arrays. Generally speaking, SQL arrays are usable only for primitive types such as numbers or strings. Some databases, such as Postgres, have their own implementations of multi-dimensional arrays, which are non-standard and have so many quirks and limitations that it's more practical to just use JSON. Arrays of primitives are already supported in adapters such as "github.com/lib/pq", which are orthogonal to Gos and used in combination with it.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Results from the 2023 State of JavaScript Survey highlight key trends, including Vite's dominance, rising TypeScript adoption, and the enduring popularity of React. Discover more insights on developer preferences and technology usage.
Security News
The US Justice Department has penalized two consulting firms $11.3 million for failing to meet cybersecurity requirements on federally funded projects, emphasizing strict enforcement to protect sensitive government data.
Security News
ua-parser-js is set to drop the MIT license and adopt a controversial dual AGPLv3 + PRO licensing model in its upcoming v2.0 release, raising significant concerns among developers and enterprise users.