--- title: How to Handle NULL Values from Databases in Rust summary: Use the Option enum and pattern matching to safely handle missing values instead of NULL in Rust. lang: en slug: how-to-handle-null-values-from-databases-in-rust published: 2026-04-17T12:05:42+00:00 updated: 2026-04-25T22:00:13+00:00 canonical: https://www.rustfaq.org/en/how-to-handle-null-values-from-databases-in-rust/ --- # How to Handle NULL Values from Databases in Rust ## The database hands you nothing Your application queries the users table for a profile picture URL. The database returns a row. The `avatar_url` column is NULL. In JavaScript, you call `.length` on it and the server crashes with a TypeError. In Python, you get an AttributeError. Rust refuses to let that happen. The type system forces you to acknowledge the missing value before you can touch it. ## Option replaces the null pointer Rust replaces the null pointer with `Option`. The name describes exactly what it does. It is an enumeration with two variants: `Some(T)` wraps a present value, and `None` represents absence. Think of it like a ticket dispenser at a venue. You either get a ticket with a seat number printed on it, or you get a blank slip that says sold out. You cannot walk into the arena with the blank slip. You cannot assume the seat number is there. The machine forces you to check what you got before you proceed. In Rust, `Option` is not a runtime trick. It is a compile-time contract. When a database driver maps a nullable column, it hands you `Option`, not `String`. The compiler treats those two types as completely different. You cannot pass an `Option` to a function expecting a `String`. You must explicitly extract the value or provide a fallback. The language removes the entire category of null pointer dereferences by making absence a first-class type. ## A minimal example Here is the simplest way to handle a nullable database field. ```rust /// Fetches a user's age from the database, returning None if the column is NULL. fn get_user_age(user_id: i32) -> Option { // Simulate a database lookup that returns NULL for missing data if user_id == 42 { Some(28) } else { None } } fn main() { let age_result = get_user_age(42); // The compiler forces you to handle both possible states match age_result { Some(age) => println!("User is {} years old", age), None => println!("Age is not recorded in the database"), } } ``` The compiler reads the return type `Option` and locks the variable behind a gate. The `match` statement is the key. It requires you to handle both `Some` and `None`. If you leave out the `None` arm, the compiler emits E0004 (non-exhaustive patterns). You cannot accidentally ignore the missing value. At runtime, the match evaluates the discriminant, a tiny hidden flag that tells the CPU which variant holds the data. It branches instantly. No exceptions. No hidden allocations. ## How database drivers translate NULL Database drivers in Rust do not guess. They read the schema metadata and map columns directly to Rust types. If a column is declared `NOT NULL`, the driver returns `T`. If the column allows NULL, the driver returns `Option`. This strict mapping means your Rust code stays perfectly synchronized with your database schema. When you change a column from `NOT NULL` to `NULL` in a migration, the driver suddenly returns `Option` instead of `T`. Your code breaks at compile time. That is a feature. It forces you to update your application logic alongside your schema migration. You cannot deploy a schema change that silently breaks your type assumptions. Drivers like `sqlx` and `diesel` also provide type-safe query builders. You write the query in Rust, and the compiler checks that the selected columns match the struct you are trying to populate. If you select a nullable column but try to map it to a non-optional field, the compiler rejects the query before it ever reaches the database. ## Mapping rows without nesting matches Database queries rarely return a single integer. They return rows with multiple nullable columns. You will map those rows into Rust structs. The pattern stays the same, but the syntax shifts toward combinators to avoid nested matches. ```rust /// Represents a user row with optional profile fields. struct UserProfile { username: String, email: Option, bio: Option, avatar_url: Option, } /// Maps a raw database row into a UserProfile struct. fn map_user_row(username: String, email: Option, bio: Option, avatar: Option) -> UserProfile { UserProfile { username, // Provide a fallback domain if the email is missing email: email.map(|e| e.trim().to_lowercase()), // Replace NULL bios with a default placeholder bio: bio.or(Some("No bio provided.".to_string())), // Keep avatar as Option since it's truly optional avatar_url: avatar, } } fn main() { let profile = map_user_row( "alice_dev".to_string(), Some("ALICE@EXAMPLE.COM".to_string()), None, Some("https://cdn.example.com/avatars/alice.png".to_string()), ); println!("Username: {}", profile.username); println!("Email: {}", profile.email.unwrap_or("N/A".to_string())); println!("Bio: {}", profile.bio.as_deref().unwrap_or("Empty")); } ``` Notice the `Option::map` and `Option::or` calls. The community prefers these combinators over deep `match` blocks when you are transforming or providing defaults. `map` runs a closure only if the value is `Some`. `or` falls back to another `Option` if the current one is `None`. This keeps the control flow flat. You are telling the compiler exactly how to handle absence at each step. When working with database rows, name your nullable fields clearly. The type signature `Option` usually carries enough weight, but adding a suffix like `_nullable` or a clear domain name helps when reading generated code. The community also favors `Option::as_deref()` when you need to pass a `&str` to a function but hold an `Option`. It avoids cloning just to check a value. Another convention: use `let _ = row.optional_field;` when you intentionally ignore a nullable column. It signals to readers that you considered the value and chose to drop it. ## When the compiler catches you The compiler will catch most mistakes, but a few patterns trip up developers coming from dynamic languages. First, confusing `Option` with `Result`. A missing column value is `Option`. A failed query or connection drop is `Result`. Mixing them up triggers E0308 (mismatched types) because the compiler expects a success/error wrapper, not a present/absent wrapper. Keep them separate. Map the database error to `Result`, then extract the nullable fields into `Option`. Second, calling `.unwrap()` in production code. `unwrap()` extracts the value if it is `Some`, but panics the entire thread if it is `None`. Use it only in tests or when you have mathematically proven the value cannot be missing. In application code, prefer `expect("reason")` for a clearer panic message, or handle the `None` case gracefully with a default or an early return. Third, forgetting that `Option` implements `Copy` only when `T` implements `Copy`. An `Option` copies freely. An `Option` moves. If you try to use an `Option` after passing it to a function, the compiler rejects you with E0382 (use of moved value). Clone it if you need to keep the original, or borrow it with `&`. Fourth, assuming the database driver will auto-convert types. Rust drivers are strict. If your schema says `VARCHAR(255) NOT NULL`, the driver returns `String`. If you change the schema to allow NULL, the driver suddenly returns `Option`. Your code breaks at compile time. That is a feature. It forces you to update your application logic alongside your schema migration. Fifth, trying to compare `Option` values directly with `==`. `Option` implements `PartialEq` only when `T` does. Comparing `Option` works, but comparing `Option<&[u8]>` requires extra trait bounds. If you need to check presence without caring about the inner value, use `is_some()` or `is_none()`. If you need to extract and compare, use `map` or `match`. Trust the borrow checker here. It usually has a point. ## Choosing your null strategy Use `Option` when the database column allows NULL and the absence is a normal, expected state in your domain. Use `T` without `Option` when the column is `NOT NULL` in the schema and your application logic guarantees a value. Use `Result` when the absence of an entire row means a query failed or a lookup missed, not when a specific column is NULL. Use `Option>` only when you need to distinguish between a database NULL and a serialized null representation inside a JSONB or text column. Reach for `Option::map` and `Option::and_then` when chaining transformations, and reserve `match` for cases where the `None` branch requires complex control flow or multiple fallback strategies. ## Where to go next - [How to handle database errors in Rust](/en/how-to-handle-database-errors-in-rust/) - [How to Handle Database Transactions in Rust](/en/how-to-handle-database-transactions-in-rust/) - [How to Use Connection Pooling in Rust](/en/how-to-use-connection-pooling-in-rust/)