glindex - v1.0.0

glindex/database

Open and manage IndexedDB databases.

Use new to create a builder, chain add_version calls to register incremental migrations, then call open to connect. Each migration runs only when upgrading from a lower version, so it is safe to add new versions as your schema evolves without touching earlier ones.

Example

import glindex/database
import glindex/upgrade

database.new("MyApp", 2)
|> 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
})
|> 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
})
|> database.open()

Types

DatabaseBuilder

opaque </> 
pub opaque type DatabaseBuilder

DatabaseError

</>

Errors that can occur when opening or deleting a database.

  • Blocked - the open request was blocked by an existing connection that has not been closed or upgraded yet.
  • VersionError - the requested version is invalid (<= 0) or a migration was registered with a duplicate or invalid version number.
  • UnknownError - an unexpected browser error occurred.
pub type DatabaseError {
  Blocked
  UnknownError(String)
  VersionError
}

Constructors 

  • Blocked
  • UnknownError(String)
  • VersionError

DatabaseInfo

</>

Metadata about an existing IndexedDB database on this origin.

pub type DatabaseInfo {
  DatabaseInfo(name: String, version: Int)
}

Constructors 

  • DatabaseInfo(name: String, version: Int)

DatabaseMigration

opaque </> 
pub opaque type DatabaseMigration

Values

add_version

</> 
pub fn add_version(
  builder: DatabaseBuilder,
  version: Int,
  migrate: fn(
    transaction.Transaction(
      @internal ReadWrite,
      @internal VersionChange,
    ),
  ) -> Nil,
) -> DatabaseBuilder

Register a migration for a specific schema version.

The migrate callback receives a VersionChange transaction and is only called when the database is being upgraded past version.

Register one call per version number, starting at 1.

close

</> 
pub fn close(db: glindex.Database) -> Nil

Close the database connection.

Any in-progress transactions will complete before the connection is actually closed. After calling this, the Database handle must not be used again.

databases

</> 
pub fn databases() -> promise.Promise(
  Result(List(DatabaseInfo), DatabaseError),
)

List all IndexedDB databases available on the current origin.

delete

</> 
pub fn delete(
  name: String,
) -> promise.Promise(Result(Nil, DatabaseError))

Delete the named IndexedDB database entirely.

Returns Error(Blocked) if an existing connection is preventing deletion.

new

</> 
pub fn new(name: String, version: Int) -> DatabaseBuilder

Create a new database builder for the given name and target version.

The version must be a non zero positive integer. Use add_version to register migrations before calling open.

on_blocked

</> 
pub fn on_blocked(
  builder: DatabaseBuilder,
  handler: fn(Int, Int) -> a,
) -> DatabaseBuilder

Register a handler called when the open request is blocked by an existing connection that has not closed yet.

The handler receives the old version and the new target version.

on_blocking

</> 
pub fn on_blocking(
  builder: DatabaseBuilder,
  handler: fn(Int, Int) -> a,
) -> DatabaseBuilder

Register a handler called when this connection is blocking another open request that needs a higher version.

The handler receives the current version and the requested version. Close the database inside this handler to unblock the pending upgrade.

on_close

</> 
pub fn on_close(
  builder: DatabaseBuilder,
  handler: fn() -> a,
) -> DatabaseBuilder

Register a handler called when the database connection is terminated unexpectedly by the browser (e.g. the storage is deleted externally).

open

</> 
pub fn open(
  builder: DatabaseBuilder,
) -> promise.Promise(Result(glindex.Database, DatabaseError))

Open the database, running any pending migrations, and return a Promise.

Resolves to Error(VersionError) immediately without touching the browser if the target version is <= 0 or any migration has an invalid or duplicate version number.

✨ Search Document