Mongoose Timestamps

Jul 17, 2020

Mongoose schemas have a timestamps option that tells Mongoose to automatically manage createdAt and updatedAt properties on your documents. For example, here's how you can enable timestamps on a User model.

const userSchema = mongoose.Schema(
  {
    email: String,
  },
  { timestamps: true }
);

const User = mongoose.model("User", userSchema);

const doc = await User.create({ email: "test@google.com" });

doc.createdAt; // 2020-07-06T20:36:59.414Z
doc.updatedAt; // 2020-07-06T20:36:59.414Z

doc.createdAt instanceof Date; // true

When you enable timestamps, Mongoose adds createdAt and updatedAt properties to your schema. By default, createdAt and updatedAt are of type Date. When you update a document, Mongoose automatically increments updatedAt.

doc.email = "sergey@google.com";
await doc.save();

doc.createdAt; // 2020-07-06T20:36:59.414Z
doc.updatedAt; // 2020-07-06T20:37:09.071Z

Specific mongoose model write operations allow you to skip timestamps provided that timestamps were set in the schema. To do so, you must set timestamps to false and the time will not be updated on that operation.

const userSchema = mongoose.Schema({
  email: String
}, { timestamps: true });

const User = mongoose.model('User', userSchema);

const doc = await User.findOneAndUpdate({email: 'test@google.com'}, {email:'newtest@google.com'}, 
{new:true, upsert: true, timestamps:false});

If you want to prevent only one of those from updating, instead of setting timestamps to false as the value, create an object with key-value pairs. The key(s) being createdAt and/or updatedAt and the value(s) being true or false depending on what you need.

const userSchema = mongoose.Schema({
  email: String
}, { timestamps: true });

const User = mongoose.model('User', userSchema);

const doc = await User.findOneAndUpdate({email: 'test@google.com'}, {email:'newtest@google.com'}, 
{new:true, upsert: true, timestamps:{createdAt:false, updatedAt:true}});

Alternate Property Names

By default, Mongoose uses createdAt and updatedAt as the property names for timestamps. But you can make Mongoose use any property name you like. For example, if you prefer snake_case property names, you can make Mongoose use created_at and updated_at instead:

const opts = {
  timestamps: {
    createdAt: 'created_at',
    updatedAt: 'updated_at'
  }
};

const userSchema = mongoose.Schema({ email: String }, opts);
const User = mongoose.model('User', userSchema);

const doc = await User.create({ email: 'test@google.com' });
doc.updated_at; // 2020-07-06T20:38:52.917Z

With Unix Timestamps

Although date types are normally sufficient, you can also make Mongoose store timestamps as seconds since January 1, 1970 (the Unix epoch). Mongoose schemas support a timestamps.currentTime option that lets you pass a custom function to use for getting the current time.

const opts = {
  // Make Mongoose use Unix time (seconds since Jan 1, 1970)
  timestamps: { currentTime: () => Math.floor(Date.now() / 1000) },
};

const userSchema = mongoose.Schema(
  {
    email: String,
  },
  opts
);

Want to become your team's MongoDB expert? "Mastering Mongoose" distills 8 years of hard-earned lessons building Mongoose apps at scale into 153 pages. That means you can learn what you need to know to build production-ready full-stack apps with Node.js and MongoDB in a few days. Get your copy!

Did you find this tutorial useful? Say thanks by starring our repo on GitHub!

Mongoose Timestamps

Alternate Property Names

With Unix Timestamps

More Mongoose Tutorials