LogoLogo
HomeAPIBlog
2.5.0
2.5.0
  • INTRODUCTION
    • Getting Started
      • Running Local Development servers
      • Beginner Tutorial: Hello World
      • Beginner Tutorial: Hello Database
      • Tutorial: CFWheels, AJAX, and You
    • Frameworks and CFWheels
    • Requirements
    • Manual Installation
    • Upgrading
    • Screencasts
  • Command Line Tools
    • CLI Commands
    • wheels - commands
    • wheels generate - commands
    • wheels dbmigrate - commands
    • wheels plugins - commands
  • Working with CFWheels
    • Conventions
    • Configuration and Defaults
    • Directory Structure
    • Switching Environments
    • Testing Your Application
    • Contributing to CFWheels
    • Documenting your Code
  • Handling Requests with Controllers
    • Request Handling
    • Rendering Content
    • Redirecting Users
    • Sending Files
    • Sending Email
    • Responding with Multiple Formats
    • Using the Flash
    • Using Filters
    • Verification
    • Event Handlers
    • Routing
    • URL Rewriting
      • Apache
      • IIS
      • Tomcat
      • Nginx
    • Obfuscating URLs
    • Caching
    • Nesting Controllers
    • CORS Requests
  • Displaying Views to Users
    • Pages
    • Partials
    • Linking Pages
    • Layouts
    • Form Helpers and Showing Errors
    • Displaying Links for Pagination
    • Date, Media, and Text Helpers
    • Creating Custom View Helpers
    • Localization
  • Database Interaction Through Models
    • Object Relational Mapping
    • Creating Records
    • Reading Records
    • Updating Records
    • Deleting Records
    • Column Statistics
    • Dynamic Finders
    • Getting Paginated Data
    • Associations
    • Nested Properties
    • Object Validation
    • Object Callbacks
    • Calculated Properties
    • Transactions
    • Dirty Records
    • Soft Delete
    • Automatic Time Stamps
    • Database Migrations
      • Migrations In Production
    • Using Multiple Data Sources
  • Plugins
    • Installing and Using Plugins
    • Developing Plugins
    • Publishing Plugins
  • External Links
    • Source Code
    • Issue Tracker
    • Sponsor Us
    • Community
Powered by GitBook
LogoLogo
On this page
  • A Practical Example
  • Updating Via struct Values
  • Combine Reading and Updating into a Single Call
  • The updateByKey() Method
  • Updating Multiple Rows with updateAll()

Was this helpful?

Edit on GitHub
Export as PDF
  1. Database Interaction Through Models

Updating Records

Updating records in your database tables.

PreviousReading RecordsNextDeleting Records

Last updated 1 year ago

Was this helpful?

When you have created or retrieved an object, you can save it to the database by calling its method. This method returns true if the object passes all validations and the object was saved to the database. Otherwise, it returns false.

This chapter will focus on how to update records. Read the chapter for more information about how to create new records.

A Practical Example

Let's start with an example of getting a blog post from the database, updating its title, and saving it back:

post = model("post").findByKey(33);
post.title = "New version of Wheels just released";
post.save();

You can also change the values of one or more properties and save them to the database in one single call using the update() method, like this:

post = model("post").findByKey(33);
post.update(title="New version of Wheels just released");

Updating Via struct Values

You can also pass in name/value pairs to update() as a struct. The main reason this method accepts a struct is to allow you to easily use it with forms.

This is how it would look if you wanted to update the properties for a post based on a submitted form.

post = model("post").findByKey(params.key);
post.update(params.post);

It's also possible to combine named arguments with a struct, but then you need to name the struct argument as properties.

Example:

post = model("post").findByKey(params.key);
post.update(title="New version of Wheels just released", properties=params.post);

Combine Reading and Updating into a Single Call

The updateByKey() Method

This method returns the object with the primary key value you specified. If the object does not pass validation, it will be returned anyway, but nothing will be saved to the database.

result = model("post").updateByKey(33, params.post);
result = model("post").updateByKey(id=33, title="New version of Wheels just released", published=1);

Updating Multiple Rows with updateAll()

The where argument is used exactly as you specify it in the WHERE clause of the query (with the exception that Wheels automatically wraps everything properly in cfqueryparam tags). So make sure that you place those commas and quotes correctly!

An example:

recordsReturned = model("post").updateAll(
        published=1, publishedAt=Now(), where="published=0"
);

To cut down even more on lines of code, you can also combine the reading and saving of the objects by using the class-level methods and .

Give the method a primary key value (or several if you use composite keys) in the key argument, and it will update the corresponding record in your table with the properties you give it. You can pass in the properties either as named arguments or as a struct to the properties argument.

By default, will fetch the object first and call the update() method on it, thus invoking any callbacks and validations you have specified for the model. You can change this behavior by passing in instantiate=false. Then it will just update the record from the table using a simple UPDATE query.

An example of using by passing a struct:

And an example of using by passing named arguments:

The method allows you to update more than one record in a single call. You specify what records to update with the where argument and tell Wheels what updates to make using named arguments for the properties.

Unlike , the method will not instantiate the objects by default. That could be really slow if you wanted to update a lot of records at once.

save()
Creating Records
updateByKey()
updateAll()
updateByKey()
updateByKey()
updateByKey()
updateByKey()
updateAll()
updateByKey()
updateAll()