glindex/upgrade

Schema migration operations for IndexedDB.

All functions in this module are only meaningful inside a VersionChange transaction, which is provided to each callback registered with glindex/database.add_version.

All store and index operations of glindex/transaction do work inside a VersionChange

A typical migration creates stores and indexes:

database.add_version(1, fn(tx) {
  let assert Ok(store) =
    upgrade.create_store(
      tx,
      "tracks",
      upgrade.StoreOptions(
        key_path: upgrade.KeyPath("id"),
        auto_increment: True,
      ),
    )
  let assert Ok(_) =
    upgrade.create_index(
      tx,
      upgrade.index(store, "tracks_artist"),
      upgrade.KeyPath("artist"),
      upgrade.index_options(),
    )
  Nil
})

Later versions can modify the schema without touching earlier migrations:

database.add_version(2, fn(tx) {
  let store = upgrade.store(tx, "tracks")
  let assert Ok(_) =
    upgrade.delete_index(tx, upgrade.index(store, "tracks_artist"))
  let assert Ok(_) =
    upgrade.create_index(
      tx,
      upgrade.index(store, "tracks_artist_and_album"),
      upgrade.CompositeKeyPath(["artist", "album"]),
      upgrade.index_options(),
    )
  Nil
})

Types

IndexOptions

</>

Options passed to create_index.

unique - when True, IndexedDB rejects records whose indexed value duplicates an existing key.
multi_entry - when True and the indexed property is an array, each element of the array is indexed separately.

pub type IndexOptions {
  IndexOptions(unique: Bool, multi_entry: Bool)
}

Constructors

IndexOptions(unique: Bool, multi_entry: Bool)

KeyPath

</>

Describes how the primary key is extracted from a stored object.

OutOfLineKey - the key is stored separately and must be supplied explicitly via store_add_with_out_of_line_key / store_put_with_out_of_line_key.
KeyPath(field) - the key is a property of the stored object.
CompositeKeyPath(fields) - the key is an array built from multiple properties, useful for compound indexes.

pub type KeyPath {
  OutOfLineKey
  KeyPath(String)
  CompositeKeyPath(List(String))
}

Constructors

```
OutOfLineKey
```
```
KeyPath(String)
```
```
CompositeKeyPath(List(String))
```

StoreOptions

</>

Options passed to create_store.

key_path - see KeyPath.
auto_increment - when True, IndexedDB generates an integer key automatically for each new record. Usually combined with KeyPath("id").

pub type StoreOptions {
  StoreOptions(key_path: KeyPath, auto_increment: Bool)
}

Constructors

StoreOptions(key_path: KeyPath, auto_increment: Bool)

UpgradeError

</>

Errors that can occur during schema migration operations.

ConstraintError - a store or index with that name already exists.
InvalidStateError - the transaction is not in a valid state for this operation.
NotFoundError - the store or index does not exist.
UnknownError - an unexpected browser error occurred.

pub type UpgradeError {
  ConstraintError
  InvalidStateError
  NotFoundError
  UnknownError(String)
}

Constructors

```
ConstraintError
```
```
InvalidStateError
```
```
NotFoundError
```
```
UnknownError(String)
```

Values

create_index

</>

pub fn create_index(
  tx: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  index: transaction.TransactionIndex(t, k, i),
  key_path: KeyPath,
  options: IndexOptions,
) -> Result(transaction.TransactionIndex(t, k, i), UpgradeError)

Create a new index on an object store and return a handle to it.

The index argument is a TransactionIndex obtained from upgrade.index with the desired name, not from transaction.index.

create_store

</>

pub fn create_store(
  tx: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  name: String,
  options: StoreOptions,
) -> Result(
  transaction.TransactionStore(Nil, key_mode, t, k),
  UpgradeError,
)

Create a new object store and return a handle to it.

Must be called inside a VersionChange transaction. The name must be unique among all stores in the database.

delete_index

</>

pub fn delete_index(
  tx: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  index: transaction.TransactionIndex(t, k, i),
) -> Result(Nil, UpgradeError)

Delete an existing index from its object store.

delete_store

</>

pub fn delete_store(
  tx: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  name: String,
) -> Result(Nil, UpgradeError)

Delete an existing object store and all records it contains.

index

</>

pub fn index(
  store: transaction.TransactionStore(store_type, key_mode, t, k),
  name: String,
) -> transaction.TransactionIndex(t, k, i)

Get a handle to an existing index by name on the given store.

index_key_path

</>

pub fn index_key_path(
  tx: transaction.Transaction(rw, upgrade),
  index: transaction.TransactionIndex(t, k, i),
) -> Result(KeyPath, UpgradeError)

Return the key path configuration of an index.

index_multi_entry

</>

pub fn index_multi_entry(
  tx: transaction.Transaction(rw, upgrade),
  index: transaction.TransactionIndex(t, k, i),
) -> Result(Bool, UpgradeError)

Return whether the index uses multi-entry mode.

index_names

</>

pub fn index_names(
  tx: transaction.Transaction(rw, upgrade),
  store: transaction.TransactionStore(any, key_mode, t, k),
) -> Result(List(String), UpgradeError)

Return the names of all indexes on the given store.

index_options

</>

pub fn index_options() -> IndexOptions

Default IndexOptions: non-unique, single-entry.

index_unique

</>

pub fn index_unique(
  tx: transaction.Transaction(rw, upgrade),
  index: transaction.TransactionIndex(t, k, i),
) -> Result(Bool, UpgradeError)

Return whether the index enforces uniqueness.

object_store_names

</>

pub fn object_store_names(
  tx: transaction.Transaction(rw, upgrade),
) -> List(String)

Return the names of all object stores in the database.

rename_index

</>

pub fn rename_index(
  tx: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  index: transaction.TransactionIndex(t, k, i),
  new_name: String,
) -> Result(transaction.TransactionIndex(t, k, i), UpgradeError)

Rename an index. Returns a handle with the new name.

rename_store

</>

pub fn rename_store(
  tx: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  store: transaction.TransactionStore(any, key_mode, t, k),
  new_name: String,
) -> Result(
  transaction.TransactionStore(Nil, key_mode, t, k),
  UpgradeError,
)

Rename an object store. Returns a handle with the new name.

store

</>

pub fn store(
  arg: transaction.Transaction(
    @internal ReadWrite,
    @internal VersionChange,
  ),
  name: String,
) -> transaction.TransactionStore(Nil, key_mode, Nil, Nil)

Get a handle to an existing object store by name inside a migration.

Use this in later version migrations to access a store that was created in an earlier migration so you can modify its indexes.

store_auto_increment

</>

pub fn store_auto_increment(
  tx: transaction.Transaction(rw, upgrade),
  store: transaction.TransactionStore(any, key_mode, t, k),
) -> Result(Bool, UpgradeError)

Return whether the store uses auto-incrementing keys.

store_key_path

</>

pub fn store_key_path(
  tx: transaction.Transaction(rw, upgrade),
  store: transaction.TransactionStore(any, key_mode, t, k),
) -> Result(KeyPath, UpgradeError)

Return the key path configuration of a store.

store_options

</>

pub fn store_options() -> StoreOptions

Default StoreOptions: out-of-line key, no auto-increment.