In IndexedDB, what is an object store, what does a store's keyPath do, and what changes when the store is created with autoIncrement: true?

## What IndexedDB actually is IndexedDB is the browser's real database: an asynchronous, transactional, origin-scoped store designed for large structured data. It has no query language and no tables. A named database contains named **object stores**, and each object store contains **records**, where a record is a (primary key, value) pair. The mental model closest to the truth is an ordered map: keys are sorted, and every read is either "give me the record at this key" or "walk the keys in this range". A database also carries an integer **version**. Object stores can only be created or destroyed while a version upgrade is running, which is why store definitions live inside the `upgradeneeded` handler of `indexedDB.open(name, version)` and nowhere else. ## Object stores ```js const req = indexedDB.open('shop', 1); req.onupgradeneeded = (event) => { const db = event.target.result; db.createObjectStore('orders', { keyPath: 'id' }); }; ``` `IDBDatabase.createObjectStore(name, options)` takes exactly two interesting options: `keyPath` and `autoIncrement`. Together they decide where a record's primary key comes from. That decision is permanent for the life of the store — changing it means creating a differently-configured store in a later version and copying the data across. ## In-line keys: keyPath When `keyPath` is set, the key is **in-line**: it lives inside the value, and the browser extracts it on every write. `keyPath: 'id'` reads the `id` property. A dotted path such as `'user.id'` reaches into a nested object. An array key path such as `['userId', 'createdAt']` builds a **compound key**, which sorts by the first component, then the second. Two consequences follow. First, a record that is missing the key path property is rejected — the write request fails with a `DataError`. Second, you must *not* also pass an explicit key: `store.put(value, 42)` against a store that has a `keyPath` is also a `DataError`, because the store already knows where the key comes from. ## Out-of-line keys With no `keyPath`, the key lives outside the value and you provide it yourself: ```js const store = tx.objectStore('blobs'); store.put(someBlob, 'avatar/42'); // key is the second argument ``` This is the right shape when the stored value is not a plain object you control — a `Blob`, an `ArrayBuffer`, a number — or when the natural key is not a property of the data. ## autoIncrement and the key generator `autoIncrement: true` gives the store a **key generator**. Each generated key is an integer, starting at 1 and increasing. If the store also has a `keyPath` and the record you write lacks that property, the generated key is written into the stored record at that path — so after `store.add({ total: 30 })` on a `{ keyPath: 'id', autoIncrement: true }` store, the record you read back has `id: 1`. You may still supply your own key; an explicit larger numeric key pushes the generator up, so later generated keys stay above it. Auto-increment is convenient for local-only data. It is a poor choice for records that also exist on a server, because two devices working offline will both mint key 1 for different records; a server-assigned id or a UUID as an in-line `keyPath` avoids that collision entirely. ## Keys are typed and ordered Valid key types are: numbers, strings, `Date`, `ArrayBuffer` and typed arrays, and arrays of those. Booleans, `null`, `undefined`, and plain objects are not valid keys and produce a `DataError`. Keys have a total order defined across types (numbers before dates before strings before binary before arrays), which is exactly what makes ordered iteration and range queries possible: without a defined order there is no "next key". ## add versus put `store.add(value)` is insert-only: if a record already exists at that key, the request fails with a `ConstraintError`. `store.put(value)` is an upsert: it replaces any existing record at that key. Reaching for `put` everywhere is common and usually fine, but `add` is how you assert "this must be new" and get told when it is not. ## What people get wrong Treating a store like a SQL table and expecting to query arbitrary fields is the big one — an object store is only queryable by its primary key until you add a secondary index. Assuming `keyPath` validates or reshapes the record is another: it only locates the key. And assuming auto-increment keys are stable identities across devices leads directly to sync collisions.