Creats a DETS table (on disk!).

If no .dets file exists for the provided definition, creates one. Otherwise, just checks whether the file is accessible and not corrupted.

Example

pub fn start_database() {
  let table_decoder = {
    use name <- database.field(0, decode.string)
    use animal <- database.field(1, my_animal_decoder)
    decode.success(Pet(name:, animal:))
  }
  let table_name = atom.create("pets")
  database.create_dets_table(name: table_name, decode_with: table_decoder)
  // -> Ok(Table(Pet))
}

Creats a ETS table (in memory!).

Example

pub fn start_database() {
  let table_name = atom.create("pets")
  database.create_ets_table(name: table_name)
  // -> Table(a)
}

Deletes a value from a table.

Example

pub fn delete_pet(table: Table(Pet) pet_id: String) {
  use ref <- database.transaction(table)
  database.delete(ref, pet_id)
}

Deletes the entire table file

Example

pub fn destroy_all_pets(table: Table(Pet), password: String) {
  case password {
    "Yes, I am evil." -> {
      database.drop_table(table)
      Ok(Nil)
    }
    _ -> Error(WrongPassword)
  }
}

Enum decoder

Example

let decoder = {
  use name <- database.field(0, decode.string)
  use animal <- database.field(1, database.enum([Dog, Cat, Parrot], Dog))
  decode.success(Pet(name:, animal:))
}

Field decoder

Example

let decoder = {
  use name <- database.field(0, decode.string)
  use animal <- database.field(1, my_animal_decoder)
  decode.success(Pet(name:, animal:))
}

Finds a value by its index

Example

pub fn play_with_pluto(table: Table(Pet)) {
  use ref <- database.transaction(table)
  let resp = database.find(ref, known_pluto_id)
  case resp {
    Error(_) -> Error(PlutoNotFoundBlameTheAstronomers)
    Ok(pluto) -> Ok(play_with(pluto))
  }
}

Inserts a value into a table and return their generated id.

Example

pub fn new_pet(table: Table(Pet), animal: Animal, name: String) {
  let pet = Pet(name, animal)
  use ref <- database.transaction(table)
  database.insert(ref, pet)  
}

Migrates an DETS table to a new structure (does nothing to ETS tables, since those only exist in runtime). When the type stored in the table changes, this function allows you to update the table to the new structure.

This function will error if you try to use it on an ETS table.

Example

pub fn migrate_pets(table: Table(Pet)) {
  use value <- database.migrate(table)
  case decode.run(value, my_pet_decoder()) {
    Ok(pet) -> Update(pet)
    _ -> Delete
  } 
}

Searches for somethig on the table.

The native functions used to select values from tables (ets|dets:select|match_object) rely on Erlang’s extremely loose type system, which goes against both Gleam’s and this projects’s principles. So, in order to make it functional (and performatic), some compromises had to be done. Most notably, this function receives an untyped (unused generic) parameter, which is a tuple with the patterns to be matched, said patterns can be values to be pattern-matched or functions that return said values, as shown below. For more examples, access the database_test.gleam file

Don’t worry, while the parameters for the result might be a bit loosey, its return is perfectly type safe, as enforced by the Gleam compiler (on both ETS and DETS modes) and the decode API (only in DETS mode)

Example

pub fn fetch_all_parrots(table: Table(Pet)) {
  use ref <- database.transaction(table)
  let _ = database.insert(ref, Parrot("Kiwi"))
  let _ = database.insert(ref, Cat("Hulu"))
  let _ = database.insert(ref, Parrot("Tata"))
  let _ = database.insert(ref, Dog("Mina"))
  database.select(ref, #(Parrot(_)))
}

IMPORTANT

By default, DETS and ETS tables are not sorted in any deterministic way, so never assume that the last value inserted will be the last one on the table.

Allows you to interact with the table.

For DETS tables, it opens and locks the .dets file, then execute your operations. Once the operations are done, it writes the changes into the file, closes and releases it. For ETS tables, it freezes the content of the table, then execute your operations. Once the operations are done, it pushes the possible new changes (from other parts of your code) into it and releases it.

Example

pub fn is_pet_registered(table: Table(Pet), pet_id: String) {
  use ref <- database.transaction(table)
  case database.find(ref, pet_id) {
    Ok(_) -> True
    Error(_) -> False
  }
}

Updates a value in a table.

Example

pub fn rename_pet(table: Table(Pet) id: String, pet: Pet, new_name: String) {
  use transac <- database.transaction(table)
  let pet = Pet(new_name, pet.animal)
  database.update(transac, id, pet)
}

Inserts a value into a table with a specific id. If the id already exists, the value is overwritten.

Example

pub fn save_user(table: Table(User), user: User) {
  use ref <- database.transaction(table)
  database.upsert(ref, user.email, user)
}