You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 6-data-storage/03-indexeddb/article.md
+32-23Lines changed: 32 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,22 +5,22 @@ libs:
5
5
6
6
# IndexedDB
7
7
8
-
IndexedDB is a built-in database, much more powerful than `localStorage`.
8
+
IndexedDB is a database, that is built into browser, much more powerful than `localStorage`.
9
9
10
-
-Key/value storage: value can be (almost) anything, multiple key types.
10
+
-Stores almost any kind of values by keys, multiple key types.
11
11
- Supports transactions for reliability.
12
12
- Supports key range queries, indexes.
13
-
- Can store much more data than `localStorage`.
13
+
- Can store much bigger volumes of data than `localStorage`.
14
14
15
15
That power is usually excessive for traditional client-server apps. IndexedDB is intended for offline apps, to be combined with ServiceWorkers and other technologies.
16
16
17
17
The native interface to IndexedDB, described in the specification <https://www.w3.org/TR/IndexedDB>, is event-based.
18
18
19
-
We can also use `async/await` with the help of a promise-based wrapper, like <https://github.com/jakearchibald/idb>. That's pretty convenient, but the wrapper is not perfect, it can't replace events for all cases. So we'll start with events, and then, after we gain understanding of IndexedDb, we'll use the wrapper.
19
+
We can also use `async/await` with the help of a promise-based wrapper, like <https://github.com/jakearchibald/idb>. That's pretty convenient, but the wrapper is not perfect, it can't replace events for all cases. So we'll start with events, and then, after we gain understanding of IndexedDb, we'll use the wrapper.
20
20
21
21
## Open database
22
22
23
-
To start working with IndexedDB, we first need to open a database.
23
+
To start working with IndexedDB, we first need to `open` (connect to) a database.
24
24
25
25
The syntax:
26
26
@@ -33,20 +33,22 @@ let openRequest = indexedDB.open(name, version);
33
33
34
34
We can have many databases with different names, but all of them exist within the current origin (domain/protocol/port). Different websites can't access databases of each other.
35
35
36
-
After the call, we need to listen to events on `openRequest` object:
36
+
The call returns `openRequest` object, we should listen to events on it:
37
37
-`success`: database is ready, there's the "database object" in `openRequest.result`, that we should use it for further calls.
38
38
-`error`: opening failed.
39
39
-`upgradeneeded`: database is ready, but its version is outdated (see below).
40
40
41
41
**IndexedDB has a built-in mechanism of "schema versioning", absent in server-side databases.**
42
42
43
-
Unlike server-side databases, IndexedDB is client-side, the data is stored in the browser, so we, developers, don't have direct access to it. But when we publish a new version of our app, we may need to update the database.
43
+
Unlike server-side databases, IndexedDB is client-side, the data is stored in the browser, so we, developers, don't have "any time" access to it. So, when we published a new version of our app, and the user visits our webpage, we may need to update the database.
44
44
45
45
If the local database version is less than specified in `open`, then a special event `upgradeneeded` is triggered, and we can compare versions and upgrade data structures as needed.
46
46
47
-
The event also triggers when the database did not exist yet, so we can perform initialization.
47
+
The `upgradeneeded`event also triggers when the database did not exist yet (technically, it's version is `0`), so we can perform initialization.
48
48
49
-
When we first publish our app, we open it with version `1` and perform the initialization in `upgradeneeded` handler:
49
+
Let's say we published the first version of our app.
50
+
51
+
Then we can open the database with version `1` and perform the initialization in `upgradeneeded` handler like this:
50
52
51
53
```js
52
54
let openRequest =indexedDB.open("store", *!*1*/!*);
So, in `openRequest.onupgradeneeded`we update the database. Soon we'll see how it's done. And then, only if its handler finishes without errors, `openRequest.onsuccess` triggers.
92
+
Please note: as our current version is `2`, `onupgradeneeded`handler has a code branch for version `0`, suitable for users that come for the first time and have no database, and also for version `1`, for upgrades.
89
93
90
-
After `openRequest.onsuccess` we have the database object in `openRequest.result`, that we'll use for further operations.
94
+
And then, only if `onupgradeneeded` handler finishes without errors, `openRequest.onsuccess` triggers, and the database is considered successfully opened.
91
95
92
96
To delete a database:
93
97
@@ -96,29 +100,32 @@ let deleteRequest = indexedDB.deleteDatabase(name)
96
100
// deleteRequest.onsuccess/onerror tracks the result
97
101
```
98
102
99
-
```warn header="Can we open an old version?"
100
-
Now what if we try to open a database with a lower version than the current one? E.g. the existing DB version is 3, and we try to `open(...2)`.
103
+
```warn header="We can't open an older version of the database"
104
+
If the current user database has a higher version than in the `open` call, e.g. the existing DB version is `3`, and we try to `open(...2)`, then that's an error, `openRequest.onerror` triggers.
101
105
102
-
That's an error, `openRequest.onerror` triggers.
106
+
That's odd, but such thing may happen when a visitor loaded an outdated JavaScript code, e.g. from a proxy cache. So the code is old, but his database is new.
103
107
104
-
Such thing may happen if the visitor loaded an outdated code, e.g. from a proxy cache. We should check `db.version`, suggest him to reload the page. And also re-check our caching headers to ensure that the visitor never gets old code.
108
+
To protect from errors, we should check `db.version` and suggest him to reload the page. Use proper HTTP caching headers to avoid loading the old code, so that you'll never have such problem.
105
109
```
106
110
107
111
### Parallel update problem
108
112
109
113
As we're talking about versioning, let's tackle a small related problem.
110
114
111
-
Let's say, a visitor opened our site in a browser tab, with database version 1.
115
+
Let's say:
116
+
1. A visitor opened our site in a browser tab, with database version `1`.
117
+
2. Then we rolled out an update, so our code is newer.
118
+
3. And then the same visitor opens our site in another tab.
112
119
113
-
Then we rolled out an update, and the same visitor opens our site in another tab. So there are two tabs, both with our site, but one has an open connection with DB version 1, while the other one attempts to update it in`upgradeneeded` handler.
120
+
So there's a tab with an open connection to DB version `1`, while the second tab one attempts to update it to version `2` in its`upgradeneeded` handler.
114
121
115
-
The problem is that a database is shared between two tabs, as that's the same site, same origin. And it can't be both version 1 and 2. To perform the update to version 2, all connections to version 1 must be closed.
122
+
The problem is that a database is shared between two tabs, as it's the same site, same origin. And it can't be both version `1` and `2`. To perform the update to version `2`, all connections to version 1 must be closed, including the one in the first tab.
116
123
117
-
In order to organize that, the `versionchange` event triggers an open database object when a parallel upgrade is attempted. We should listen to it, so that we should close the database (and probably suggest the visitor to reload the page, to load the updated code).
124
+
In order to organize that, the `versionchange` event triggers in such case on the "outdated" database object. We should listen to it and close the old database connection (and probably suggest the visitor to reload the page, to load the updated code).
118
125
119
-
If we don't close it, then the second, new connection will be blocked with `blocked` event instead of `success`.
126
+
If we don't listen to `versionchange` event and don't close the old connection, then the second, new connection won't be made. The `openRequest` object will emit the `blocked` event instead of `success`. So the second tab won't work.
120
127
121
-
Here's the code to do that:
128
+
Here's the code to correctly handle the parallel upgrade:
0 commit comments