Open-Source Databases · guregu

null

guregu/null is a Go library providing type-safe wrappers for nullable SQL and JSON values. It offers two packages—null (distinguishes null from zero) and zero (treats them equivalently)—allowing cleaner handling of optional database fields without Go's verbose sql.NullXXX types.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/guregu/null

2.1k

GitHub stars

248

Forks

Primary language

BSD-2-Clause

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	guregu/null
Owner	guregu
Primary language	Go
License	BSD-2-Clause — OSI-approved
Stars	2.1k
Forks	248
Open issues	11
Latest release	v6.0.0 (2025-03-05)
Last updated	2025-03-05
Source	https://github.com/guregu/null

What null is

The library implements sql.Scanner, driver.Valuer, json.Marshaler, and json.Unmarshaler interfaces for primitive types (String, Int variants, Float, Bool, Time) plus a generic Value[T]. The zero package marshals to Go zero values when null; the null package marshals to JSON null, enabling Go 1.24's ,omitzero struct tag for field omission.

Quickstart

Get the null source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/guregu/null.git2cd null3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Database-to-JSON API responses with nullable fields

Use null.String, null.Int, etc. to read from SQL and serialize to JSON cleanly, preserving null semantics without manual null-checking or nested structures.

Form/configuration parsing with optional inputs

Leverage zero package types to treat missing (blank string) and explicit nulls identically, simplifying validation and default-value logic in web handlers and config loaders.

Struct marshaling with ,omitzero for compact output

Combine the library's IsZero() implementation (Go 1.24+) with struct tags to omit null/empty fields from JSON, reducing payload size and API contract clarity.

Implementation considerations

Choose between null (null ≠ zero) and zero (null ≡ zero) packages upfront; mixing can lead to subtle marshaling inconsistencies in large codebases.
With Go 1.24+, use ,omitzero struct tags on null/zero fields to reduce JSON payload; verify all target Go versions support this before relying on it in APIs.
Implement ValueOr() method calls for safe defaults where a nil/zero value should trigger fallback logic, avoiding nil pointer or zero-value surprises.
Test JSON round-trip marshaling (SQL → JSON → SQL) to ensure null semantics are preserved, especially when null and zero must remain distinct.
Document which package (null vs. zero) and which types are used per data model to prevent confusion when new team members encounter nullable fields.

When to avoid it — and what to weigh

Need complex custom null semantics or domain types — Library is intentionally minimal and limited to driver.Value-compatible types. Custom nullability logic or bespoke serialization beyond primitives requires alternatives or forking.
Require encoding.TextMarshaler on generic Value[T] — The README explicitly states generic Value[T] does not implement TextMarshaler, limiting use in certain text-serialization scenarios; use concrete types or a different library.
Working primarily with non-SQL data sources or ORMs with built-in null handling — If using a full ORM (e.g., gorm, sqlc) that abstracts nullable types, this library may add redundant abstraction; evaluate whether the ORM's null handling suffices.
Go versions below 1.20 or need text marshaling on all types — Non-generic types lack TextMarshaler support; if Go <1.20, lack of module compatibility and missing newer features may cause friction.

License & commercial use

Licensed under BSD 2-Clause (Simplified). This is a permissive OSI-approved open-source license allowing commercial use, modification, and distribution with minimal restrictions (retain copyright/license notice and disclaimer).

BSD 2-Clause is a permissive open-source license that explicitly permits commercial use, proprietary modification, and redistribution. No proprietary license or commercial agreement is required; include a copy of the license in your distribution. Consult internal legal review if uncertain.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

No security-specific vulnerabilities disclosed. Library is a pure data-type wrapper around Go's standard library sql and json packages; no network I/O, cryptography, or privilege escalation surface. Standard code-review practices apply when marshaling untrusted JSON or SQL inputs. Ensure parent application validates null/zero semantics correctly to avoid logic bypasses.

Alternatives to consider

sql.NullXXX (Go standard library)

Built-in but verbose (requires .Valid checks, .String/.Int64 accessors); no JSON marshaling support. Adequate for simple cases, but less ergonomic than guregu/null.

GORM's NullString, NullInt64, etc.

Bundled with the GORM ORM; good if already using GORM. Requires GORM dependency and may impose schema assumptions; not suitable for non-GORM SQL codebases.

Custom types + json.Marshaler implementation

Full control over semantics and no external dependency. Higher up-front cost; consider only if null handling is highly domain-specific or if adding a dependency is forbidden.

Software development agency

Build on null with DEV.co software developers

If your Go services juggle nullable database fields and JSON APIs, we can help integrate guregu/null or build a custom null-handling strategy tailored to your schema and API contracts. Contact us for a technical review.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

scany rel go-starter

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Databases API Development Custom Software Development Talk to DEV.co

null FAQ

Can I use null.String in place of sql.NullString?

Yes. null.String implements sql.Scanner and driver.Valuer, so it works drop-in with database/sql. It also adds json.Marshaler/json.Unmarshaler for native JSON null support.

What is the difference between null and zero packages?

null distinguishes between null and zero values (e.g., null string vs. empty string); zero treats them as equivalent. Choose based on whether your API/database schema must preserve that distinction.

Does this library support custom types or slices?

No. The library intentionally supports only types compatible with database/sql's driver.Value. For custom types, implement sql.Scanner and driver.Valuer yourself or fork the library.

Is this library secure for production use?

The library itself is a straightforward wrapper around Go's standard library. Security depends on how your application validates and handles null/zero values; no inherent vulnerabilities are known. Follow standard secure coding practices for your consuming code.

Custom software development services

Need help beyond evaluating null? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source databases integrations — and maintain them long-term.

Simplify Your Go Nullable Data Handling

Talk to DEV.co Schedule a Consultation