Hibernate @NotNull vs @Column(nullable = false)

1. Introduction

At first glance, it may seem like both the @NotNull and @Column(nullable = false) annotations serve the same purpose and can be used interchangeably. However, as we’ll soon see, this isn’t entirely true.

Even though, when used on the JPA entity, both of them essentially prevent storing null values in the underlying database, there are significant differences between these two approaches.

In this quick tutorial, we’ll compare the @NotNull and @Column(nullable = false) constraints.

2. Dependencies

For all the presented examples, we’ll use a simple Spring Boot application.

Here’s a relevant section of the pom.xml file that shows needed dependencies:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
    </dependency>
</dependencies>

2.1. Sample Entity

Let’s also define a very simple entity that we’ll be using throughout this tutorial:

@Entity
public class Item {

    @Id
    @GeneratedValue
    private Long id;

    private BigDecimal price;
}

3. The @NotNull Annotation

The @NotNull annotation is defined in the Bean Validation specification. This means its usage isn’t limited only to the entities. On the contrary, we can use @NotNull on any other bean as well.

Let’s stick with our use case though and add the @NotNull annotation to the Item‘s price field:

@Entity
public class Item {

    @Id
    @GeneratedValue
    private Long id;

    @NotNull
    private BigDecimal price;
}

Now, let’s try to persist an item with a null price:

@SpringBootTest
public class ItemIntegrationTest {

    @Autowired
    private ItemRepository itemRepository;

    @Test
    public void shouldNotAllowToPersistNullItemsPrice() {
        itemRepository.save(new Item());
    }
}

And let’s see Hibernate’s output:

2019-11-14 12:31:15.070 ERROR 10980 --- [ main] o.h.i.ExceptionMapperStandardImpl : 
HHH000346: Error during managed flush [Validation failed for classes 
[com.baeldung.h2db.springboot.models.Item] during persist time for groups 
[javax.validation.groups.Default,] List of constraint violations:[
ConstraintViolationImpl{interpolatedMessage='must not be null', propertyPath=price, rootBeanClass=class 
com.baeldung.h2db.springboot.models.Item, 
messageTemplate='{javax.validation.constraints.NotNull.message}'}]]
 
(...)
 
Caused by: javax.validation.ConstraintViolationException: Validation failed for classes 
[com.baeldung.h2db.springboot.models.Item] during persist time for groups 
[javax.validation.groups.Default,] List of constraint violations:[
ConstraintViolationImpl{interpolatedMessage='must not be null', propertyPath=price, rootBeanClass=class 
com.baeldung.h2db.springboot.models.Item, 
messageTemplate='{javax.validation.constraints.NotNull.message}'}]

As we can see, in this case, our system threw javax.validation.ConstraintViolationException.

It’s important to notice that Hibernate didn’t trigger the SQL insert statement. Consequently, invalid data wasn’t saved to the database.

This is because the pre-persist entity lifecycle event triggered the bean validation just before sending the query to the database.

3.1. Schema Generation

In the previous section, we’ve presented how the @NotNull validation works.

Let’s now find out what happens if we let Hibernate generate the database schema for us.

For that reason, we’ll set a couple of properties in our application.properties file:

spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true

If we now start our application, we’ll see the DDL statement:

create table item (
   id bigint not null,
    price decimal(19,2) not null,
    primary key (id)
)

Surprisingly, Hibernate automatically adds the not null constraint to the price column definition.

How’s that possible?

As it turns out, out of the box, Hibernate translates the bean validation annotations applied to the entities into the DDL schema metadata.

This is pretty convenient and makes a lot of sense. If we apply @NotNull to the entity, we most probably want to make the corresponding database column not null as well.

However, if, for any reason, we want to disable this Hibernate feature, all we need to do is to set hibernate.validator.apply_to_ddl property to false.

In order to test this let’s update our application.properties:

spring.jpa.hibernate.ddl-auto=create-drop
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.validator.apply_to_ddl=false

Let’s run the application and see the DDL statement:

create table item (
   id bigint not null,
    price decimal(19,2),
    primary key (id)
)

As expected, this time Hibernate didn’t add the not null constraint to the price column.

4. The @Column(nullable = false) Annotation

The @Column annotation is defined as a part of the Java Persistence API specification.

It’s used mainly in the DDL schema metadata generation. This means that if we let Hibernate generate the database schema automatically, it applies the not null constraint to the particular database column.

Let’s update our Item entity with the @Column(nullable = false) and see how this works in action:

@Entity
public class Item {

    @Id
    @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private BigDecimal price;
}

We can now try to persist a null price value:

@SpringBootTest
public class ItemIntegrationTest {

    @Autowired
    private ItemRepository itemRepository;

    @Test
    public void shouldNotAllowToPersistNullItemsPrice() {
        itemRepository.save(new Item());
    }
}

Here’s the snippet of Hibernate’s output:

Hibernate: 
    
    create table item (
       id bigint not null,
        price decimal(19,2) not null,
        primary key (id)
    )

(...)

Hibernate: 
    insert 
    into
        item
        (price, id) 
    values
        (?, ?)
2019-11-14 13:23:03.000  WARN 14580 --- [main] o.h.engine.jdbc.spi.SqlExceptionHelper   : 
SQL Error: 23502, SQLState: 23502
2019-11-14 13:23:03.000 ERROR 14580 --- [main] o.h.engine.jdbc.spi.SqlExceptionHelper   : 
NULL not allowed for column "PRICE"

First of all, we can notice that Hibernate generated the price column with the not null constraint as we anticipated.

Additionally, it was able to create the SQL insert query and pass it through. As a result, it’s the underlying database that triggered the error.

4.1. Validation

Almost all the sources emphasize that @Column(nullable = false) is used only for schema DDL generation.

Hibernate, however, is able to perform the validation of the entity against the possible null values, even if the corresponding field is annotated only with @Column(nullable = false).

In order to activate this Hibernate feature, we need to explicitly set the hibernate.check_nullability property to true:

spring.jpa.show-sql=true
spring.jpa.properties.hibernate.check_nullability=true

Let’s now execute our test case again and examine the output:

org.springframework.dao.DataIntegrityViolationException: 
not-null property references a null or transient value : com.baeldung.h2db.springboot.models.Item.price; 
nested exception is org.hibernate.PropertyValueException: 
not-null property references a null or transient value : com.baeldung.h2db.springboot.models.Item.price

This time, our test case threw the org.hibernate.PropertyValueException.

It’s crucial to notice that, in this case, Hibernate didn’t send the insert SQL query to the database.

5. Summary

In this article, we’ve described how the @NotNull and @Column(nullable – false) annotations work.

Even though both of them prevent us from storing null values in the database, they take different approaches.

As a rule of thumb, we should prefer the @NotNull annotation over the @Column(nullable = false) annotation. This way, we make sure the validation takes place before Hibernate sends any insert or update SQL queries to the database.

Also, it’s usually better to rely on the standard rules defined in the Bean Validation, rather than letting the database handle the validation logic.

But, even if we let Hibernate generate the database schema, it’ll translate the @NotNull annotation into the database constraints. We must then only make sure that hibernate.validator.apply_to_ddl property is set to true.