Repository navigation
Feature: Nullability Type Hints #4340
Description
What do you want to change?
Nullability Type Hints
Queries such as the following fail if calling a function which can return a null value.
select foo::text from bar();
Workaround
One workaround, for Postgres at least, is to create a domain type in the database.
create domain text_nullable AS text;
And then add an override for this type in the sqlc config.
overrides:
- db_type: text_nullable
go_type:
type: string
pointer: true
Then this works:
select foo::text_nullable from bar();
Nullability Hints - Potential Proposals
I wonder if there's a reasonable way to modify sqlc to pass in a nullability hint within a query?
A couple of ideas...
Create a new sqlc macro.
select sql.nullable(foo::text) as foo from bar();
Add comment based hinting.
select
foo::text -- sqlc:nullable
from bar();
Create an option which recognises specific suffixes (This would conflict if these names do exist in the database).
select foo::text_nullable from call_a_function();
Question mark syntax. Harder to implement, but this may be nicer to read. Would probably require a change to
pg_query_go. Though it may be possible to extract the question marks using a simple scanner pass before passing to pg_query_go.
select foo::text? as foo from call_a_function();
Another option is putting detailed type and parameter information in the header comment. i.e. the @param proposal.
Personally, I think I actually prefer type casts and hints in the queries.
Related Issues
Many of these can be fixed by better nullability inference, but adding nullability hints, could solve these in the
meantime.
#4121
#3274
#4336
#2284
#4262
#2800
Implementation Notes
In a nutshell, I'm looking for a way to strip something out of the query, in a way which doesn't affect the database,
and then pass it through to compiler.Column.NotNull. See: sqlc/internal/compiler/to_column.go.
func toColumn(n *ast.TypeName) *Column {
if n == nil {
panic("can't build column for nil type name")
}
typ, err := ParseTypeName(n)
if err != nil {
panic("toColumn: " + err.Error())
}
arrayDims := arrayDims(n)
return &Column{
Type: typ,
DataType: strings.TrimPrefix(astutils.Join(n.Names, "."), "."),
NotNull: true, // XXX: How do we know if this should be null?
IsArray: arrayDims > 0,
ArrayDims: arrayDims,
}
}
Happy to have a crack at this, if others think it has value.
What database engines need to be changed?
No response
What programming language backends need to be changed?
No response
Activity
WIP feat: nullhinter: prototype implementation of null hints (sqlc-de…
WIP feat: nullhinter: prototype implementation of null hints (sqlc-de…
kyleconroy commentedon Apr 17, 2026
I agree we need nullability hints, but I don't think inline is the right approach. I'm thinking something more like a doc comment.
greg-blackcurrent commentedon Apr 19, 2026
The reason I wonder if inline is a better fit, is I already need to write the type hints inline.
So a doc comment requires repeating the results list twice.
Here's a simple example with one column in the result, but once you have 10 or so columns keeping the two lists synced up is a pain.
If I do the nullable hints inline then I only have one result list and don't have to keep the lists in sync.
Thinking outside the box...
The ideal solution would be:
Perhaps there's a way to change how I implement postgres functions/procedures so that sqlc is able to infer the result type and nullability?
I can return a composite type, which sqlc may be able to infer. While these don't support nullable hints directly, perhaps I could use a hint in the a comment annotation.
giovannibonetti-jota commentedon Apr 23, 2026
I get the impression #4280 fixes half of the bugs motivating this discussion. Perhaps merging it would be a good 80/20 for now?
kolypto commentedon May 19, 2026
@giovannibonetti-jota there's a whole category of nullability inference issues when it comes to functions:
both are inferred as
any.We could have fixed them with type casts:
but now they become non-nullable and panic on Scan.
Upvoting the issue! 👍 👍
@kyleconroy I'd really love to see it fixed! Nullability is THE biggest pain point with sqlc :)