////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////


== save



=== Purpose


Saves a new domain class instance or updates a modified persistent instance in the database, cascading updates to child instances if required.


=== Examples


[source,groovy]
----
def b = new Book(title: "The Shining")
b.save()
----


=== Description


The `save` method informs the persistence context that an instance should be saved or updated. The object will not be persisted immediately unless the `flush` argument is used:

[source,groovy]
----
b.save(flush: true)
----

The `save` method returns `null` if link:{guidePath}validation.html[validation] failed and the instance was not persisted, or the instance itself if successful. This lets you use "Groovy truth" (`null` is considered `false`) to write code like the following:

[source,groovy]
----
if (!b.save()) {
    b.errors.allErrors.each {
        println it
    }
}
----

Parameters:

* `validate` (optional) - Set to `false` if validation should be skipped
* `flush` (optional) - When set to `true` flushes the persistence context, persisting the object immediately and updating the `version` column for  link:{hibernate5GuideFromRef}index.html#locking[optimistic locking]
* `insert` (optional) - When set to `true` will force Hibernate to do a SQL INSERT; this is useful in certain situations (for example when using assigned ids) and Hibernate cannot detect whether to do an INSERT or an UPDATE
* `failOnError` (optional) - When set to `true` the `save` method with throw a `grails.validation.ValidationException` if link:{guidePath}validation.html[validation] fails. This behavior may also be triggered by setting the `grails.gorm.failOnError` property in `grails-app/conf/application.groovy`. If the Config property is set and the argument is passed to the method, the method argument will always take precedence.  For more details about the config property and other GORM config options, see the link:{guidePath}conf.html#configGORM[GORM Configuration Options] section of The User Guide.

[source,groovy]
----
grails.gorm.failOnError = true
----

Or the equivalent in `application.yml`:

[source,yaml]
----
grails:
    gorm:
        failOnError: true
----
* `deepValidate` (optional) - Determines whether associations of the domain instance should also be validated, i.e. whether validation cascades. This is `true` by default - set to `false` to disable cascading validation.

NOTE: By default GORM classes are configured for  link:{hibernate5GuideFromRef}index.html#locking[optimistic locking], which is a feature of Hibernate that involves storing an incrementing version in the table. This value is only updated in the database when the Hibernate session is flushed.
