---
title: "What happens during the onupgradeneeded event?"  
description: "What happens during the onupgradeneeded event?"  
author: "ICSM Computer"  
published: 2025-07-02  
updated: 2025-07-02  
canonical: https://www.mindstick.com/interview/34305/what-happens-during-the-onupgradeneeded-event  
category: "database"  
tags: ["database", "indexeddb"]  
reading_time: 3 minutes  

---

# What happens during the onupgradeneeded event?

The `**onupgradeneeded**` event in **IndexedDB** is triggered when:

- A database is **created for the first time**, or
- You **open the database with a higher version number** than the existing one.

It’s the only place where you can **safely define or update the database schema**, such as:

- [Creating **object stores**](https://www.mindstick.com/interview/34301/what-is-an-object-store-in-indexeddb)
- [Adding or modifying **indexes**](https://www.mindstick.com/interview/34303/what-is-a-keypath-and-how-is-it-used-in-indexeddb)
- Migrating or transforming **existing data**

## When Does `onupgradeneeded` Run?

| Scenario | Triggered? |
| --- | --- |
| First time opening the DB | Yes |
| Opening DB with higher version number | Yes |
| Opening DB with same version number | No |

## What Can You Do in `onupgradeneeded`?

### Typical Tasks:

- Create object stores:

```javascript
db.createObjectStore('users', { keyPath: 'id' });
```

- Create indexes:

```javascript
store.createIndex('emailIndex', 'email', { unique: true });
```

- Rename or migrate data (for upgrades)
- Delete or recreate outdated object stores

## Example

```javascript
const request = indexedDB.open('MyAppDB', 2); // version 2 triggers upgrade

request.onupgradeneeded = function(event) {
    const db = event.target.result;

    if (!db.objectStoreNames.contains('users')) {
        db.createObjectStore('users', { keyPath: 'id' });
    }

    const userStore = event.target.transaction.objectStore('users');

    if (!userStore.indexNames.contains('emailIndex')) {
        userStore.createIndex('emailIndex', 'email', { unique: true });
    }

    console.log('Upgrade complete.');
};
```

## Important Notes

- This event is **mandatory** for schema upgrades — it’s the only place you can alter the structure.
- You **must not read/write outside of transactions** in this event — use the `event.target.transaction`.

## Summary

| Feature | Description |
| --- | --- |
| When it triggers | On first open or version upgrade |
| What it does | Schema creation or modification (stores, indexes) |
| Access object stores | Via `event.target.result` and `event.target.transaction` |
| Transaction type | Auto-created **versionchange** transaction (read/write) |

\

## Answers

### Answer by ICSM Computer

The `**onupgradeneeded**` event in **IndexedDB** is triggered when:

- A database is **created for the first time**, or
- You **open the database with a higher version number** than the existing one.

It’s the only place where you can **safely define or update the database schema**, such as:

- [Creating **object stores**](https://www.mindstick.com/interview/34301/what-is-an-object-store-in-indexeddb)
- [Adding or modifying **indexes**](https://www.mindstick.com/interview/34303/what-is-a-keypath-and-how-is-it-used-in-indexeddb)
- Migrating or transforming **existing data**

## When Does `onupgradeneeded` Run?

| Scenario | Triggered? |
| --- | --- |
| First time opening the DB | Yes |
| Opening DB with higher version number | Yes |
| Opening DB with same version number | No |

## What Can You Do in `onupgradeneeded`?

### Typical Tasks:

- Create object stores:

```javascript
db.createObjectStore('users', { keyPath: 'id' });
```

- Create indexes:

```javascript
store.createIndex('emailIndex', 'email', { unique: true });
```

- Rename or migrate data (for upgrades)
- Delete or recreate outdated object stores

## Example

```javascript
const request = indexedDB.open('MyAppDB', 2); // version 2 triggers upgrade

request.onupgradeneeded = function(event) {
    const db = event.target.result;

    if (!db.objectStoreNames.contains('users')) {
        db.createObjectStore('users', { keyPath: 'id' });
    }

    const userStore = event.target.transaction.objectStore('users');

    if (!userStore.indexNames.contains('emailIndex')) {
        userStore.createIndex('emailIndex', 'email', { unique: true });
    }

    console.log('Upgrade complete.');
};
```

## Important Notes

- This event is **mandatory** for schema upgrades — it’s the only place you can alter the structure.
- You **must not read/write outside of transactions** in this event — use the `event.target.transaction`.

## Summary

| Feature | Description |
| --- | --- |
| When it triggers | On first open or version upgrade |
| What it does | Schema creation or modification (stores, indexes) |
| Access object stores | Via `event.target.result` and `event.target.transaction` |
| Transaction type | Auto-created **versionchange** transaction (read/write) |

\


---

Original Source: https://www.mindstick.com/interview/34305/what-happens-during-the-onupgradeneeded-event

Copyright © MindStick Software Pvt. Ltd. This Markdown version is provided for developers, AI systems, and offline reading.