How do you implement sql.Scanner and driver.Valuer so a custom type round-trips a nullable column?

## Two interfaces, one per direction `database/sql` converts between driver values and Go values through two tiny interfaces: ```go type Scanner interface { Scan(src any) error } // database/sql type Valuer interface { Value() (Value, error) } // database/sql/driver ``` Implement `Scanner` and your type becomes a legal `Scan` destination. Implement `Valuer` and it becomes a legal query argument. Implement both consistently and the type round-trips. This is exactly how `sql.NullString` and friends are built; writing your own is how you get a domain type — a status enum, a money amount, a tri-state flag — to sit directly in your row structs instead of being unwrapped at every call site. ## The value types you must handle `driver.Value` is deliberately tiny. Drivers produce, and are given, only: - `int64` - `float64` - `bool` - `[]byte` - `string` - `time.Time` - `nil` — which is how SQL NULL is represented So `Scan` should type-switch over the cases the column can actually produce, and return an informative error for the rest. Two practical notes. First, be generous about `string` versus `[]byte`: which one a driver hands you for a text column varies, and code that handles only one breaks when the driver changes. Second, the default branch should include the offending type — `fmt.Errorf("scan status: unsupported source type %T", src)` — because a bare "cannot scan" tells nobody anything at 3am. ## The nil case is the whole point on a nullable column When the column is NULL, `src` is `nil`. Your `Scan` must decide what that means for your type and set it, usually by assigning the zero value or an explicit "unset" state. Forgetting the case is the classic bug: the type-switch falls to `default` and every NULL row fails with "unsupported source type <nil>", which reads like a driver problem and is not. In the other direction, `Value` returns `nil` to write a NULL. Anything else must be one of the types above — returning a custom struct, a `map`, or an `int` (rather than `int64`) is rejected. ## Receivers, and why they differ `Scan` **must** be on a pointer receiver: it stores a result, and a value receiver would mutate a copy. Callers then pass `&v`, and the method set rule means only `*T` satisfies `sql.Scanner`. `Value` should be on a **value** receiver. The reason is a nice piece of `database/sql` behaviour: when it is given a nil pointer whose element type implements `driver.Valuer`, it stores NULL directly instead of calling the method. If you declare `Value` only on the pointer receiver, that shortcut does not apply and your method is invoked with a nil receiver, which panics the moment it touches a field. A value receiver also means both `T` and `*T` can be used as arguments. Lock both down at compile time: ```go var _ driver.Valuer = Status{} var _ sql.Scanner = (*Status)(nil) ``` ## Never keep the bytes you were given When `src` is a `[]byte`, the memory belongs to the driver and may be reused for the next row. Converting with `string(v)` copies, and so does `bytes.Clone(v)`. What is **not** safe is storing the slice itself in your type and reading it later: by then it may hold another row's bytes, or nothing coherent at all. This is the same ownership rule that `sql.RawBytes` makes explicit, and it applies to every custom `Scanner` whether or not you ever mention that type. ## Round-trip fidelity The pair is only useful if it is symmetric. If `Value` writes an uppercase code, `Scan` must accept an uppercase code; if `Value` writes `nil` for the unset state, `Scan` must map `nil` back to that same unset state. The cheap way to keep them honest is a table-driven test that runs each interesting value through `Value` and back through `Scan` and asserts the result equals the original — including the NULL case, which is the one people forget precisely because it has no interesting value to check. ## When not to write one If all you need is "this column may be NULL", the standard wrappers or a pointer destination already do it, with no code to maintain. Write the pair when the type also carries conversion logic — a domain enum stored as text, a duration stored as an integer, a value with an invariant you want enforced at the boundary — so that the conversion lives in exactly one place instead of at every scan site.