IDBTransaction

Интерфейс IDBTransaction API IndexedDB предоставляет статический асинхронный транзакцию с базой данных, используя атрибуты обработчиков событий. Все чтение и запись данных выполняется в рамках транзакций. Вы используете IDBDatabase для запуска транзакций, IDBTransaction для задания режима транзакции (например, это readonly или readwrite), и вы получаете доступ к IDBObjectStore для выполнения запроса. Также вы можете использовать объект IDBTransaction для прерывания транзакций.

Транзакции запускаются при создании транзакции, а не при выполнении первого запроса; например, рассмотрите это:

const trans1 = db.transaction("foo", "readwrite");
const trans2 = db.transaction("foo", "readwrite");
const objectStore2 = trans2.objectStore("foo");
const objectStore1 = trans1.objectStore("foo");
objectStore2.put("2", "key");
objectStore1.put("1", "key");

После выполнения кода хранилище объектов должно содержать значение "2", поскольку trans2 должно выполняться после trans1.

Транзакция чередует состояния активный и неактивный между задачами цикла событий. Она активна в задаче при создании и в каждой задаче обработчиков событий success или error запросов. Она неактивна во всех других задачах, в этом случае размещение запросов завершится неудачей. Если новые запросы не выполняются, когда транзакция активна, и нет других незавершенных запросов, транзакция автоматически подтверждается.

Транзакции могут завершиться неудачей по нескольким причинам, все из которых (за исключением сбоя пользовательского агента) приведут к вызову обратного вызова прерывания:

• Прерывание из-за некорректных запросов, например, попытка add() одного и того же ключа дважды или put() с тем же ключом индекса с ограничением уникальности. Это приводит к ошибке в запросе, которая может привести к ошибке в транзакции, которая прерывает транзакцию. Это можно предотвратить, используя preventDefault() на событии об ошибке в запросе.
• Явный вызов abort() из скрипта.
• Необработанное исключение в обработчике событий success/error запроса.
• Ошибка ввода-вывода (например, фактическая ошибка записи на диск или другие ошибки ОС/аппаратного обеспечения).
• Превышение квоты.
• Сбой пользовательского агента.

Обратите внимание, что начиная с Firefox 40, транзакции IndexedDB имеют ослабленные гарантии живучести для повышения производительности (см. отчет об ошибке Firefox 1112702.) Раньше в транзакции readwrite событие complete срабатывало только тогда, когда все данные гарантированно были записаны на диск. В Firefox 40+ событие complete срабатывает после того, как ОС получила команду записать данные, но потенциально до того, как эти данные фактически будут записаны на диск. Таким образом, событие complete может быть доставлено быстрее, чем раньше, однако существует небольшой шанс, что вся транзакция будет потеряна, если ОС аварийно завершит работу или произойдет потеря электропитания до записи данных на диск. Поскольку такие катастрофические события редки, большинство потребителей не должны беспокоиться об этом дальше.

Если вы должны обеспечить живучесть по какой-либо причине (например, вы храните критические данные, которые нельзя повторно вычислить позже), вы можете принудительно записать транзакцию на диск перед доставкой события complete, создав транзакцию с экспериментальным (нестандартным) режимом readwriteflush (см. IDBDatabase.transaction.

IDBTransaction.db Только для чтения

Подключение к базе данных, с которой связана эта транзакция.

IDBTransaction.durability Только для чтения

Возвращает подсказку о живучести, с которой была создана транзакция.

IDBTransaction.error Только для чтения

Возвращает DOMException, указывающий на тип ошибки, возникшей при неудачной транзакции. Это свойство null , если транзакция не завершена, завершена успешно или прервана с помощью функции IDBTransaction.abort().

IDBTransaction.mode Только для чтения

Режим изоляции доступа к данным в хранилищах объектов, которые находятся в области действия транзакции. Значение по умолчанию — readonly.

IDBTransaction.objectStoreNames Только для чтения

Возвращает DOMStringList с именами объектов IDBObjectStore, связанных с транзакцией.

Унаследовано от: EventTarget

IDBTransaction.abort()

Откатывает все изменения в объектах базы данных, связанных с этой транзакцией. Если эта транзакция была прервана или завершена, этот метод вызывает событие об ошибке.

IDBTransaction.objectStore()

Возвращает объект IDBObjectStore, представляющий хранилище объектов, которое входит в область действия этой транзакции.

IDBTransaction.commit()

Для активной транзакции подтверждает транзакцию. Обратите внимание, что это обычно не нужно вызывать — транзакция автоматически подтверждается, когда все ожидающие запросы удовлетворены и новые запросы не отправляются. commit() можно использовать для запуска процесса подтверждения без ожидания событий от незавершенных запросов.

Присоединяйтесь к этим событиям с помощью addEventListener() или назначив обработчик события свойству oneventname этого интерфейса.

abort

Событие, которое срабатывает, когда транзакция IndexedDB прерывается. Также доступно через свойство onabort; это событие распространяется на IDBDatabase.

complete

Событие, которое срабатывает, когда транзакция успешно завершается. Также доступно через свойство oncomplete.

error

Событие, которое срабатывает, когда запрос возвращает ошибку, и событие распространяется до объекта подключения (IDBDatabase). Также доступно через свойство onerror.

Транзакции могут иметь один из трёх режимов:

Даже если эти константы устарели, вы по-прежнему можете использовать их для обеспечения обратной совместимости, если это необходимо (в Chrome изменение было внесено в версии 21). Вы должны писать код с защитой на случай, если объект больше недоступен:

const myIDBTransaction = window.IDBTransaction ||
  window.webkitIDBTransaction || { READ_WRITE: "readwrite" };

В следующем фрагменте кода мы открываем транзакцию чтения/записи в нашей базе данных и добавляем некоторые данные в хранилище объектов. Обратите внимание также на функции, прикрепленные к обработчикам событий транзакций, для сообщения о результате открытия транзакции в случае успеха или неудачи. Для полного рабочего примера см. наше приложение To-do Notifications (смотреть пример в действии).

const note = document.getElementById("notifications");

// an instance of a db object for us to store the IDB data in
let db;

// Let us open our database
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = (event) => {
  note.appendChild(document.createElement("li")).textContent =
    "Database initialized.";

  // store the result of opening the database in the db
  // variable. This is used a lot below
  db = DBOpenRequest.result;

  // Add the data to the database
  addData();
};

function addData() {
  // Create a new object to insert into the IDB
  const newItem = [
    {
      taskTitle: "Walk dog",
      hours: 19,
      minutes: 30,
      day: 24,
      month: "December",
      year: 2013,
      notified: "no",
    },
  ];

  // open a read/write db transaction, ready to add data
  const transaction = db.transaction(["toDoList"], "readwrite");

  // report on the success of opening the transaction
  transaction.oncomplete = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Transaction completed: database modification finished.";
  };

  transaction.onerror = (event) => {
    note.appendChild(document.createElement("li")).textContent =
      "Transaction not opened due to error. Duplicate items not allowed.";
  };

  // create an object store on the transaction
  const objectStore = transaction.objectStore("toDoList");

  // add our newItem object to the object store
  const objectStoreRequest = objectStore.add(newItem[0]);

  objectStoreRequest.onsuccess = (event) => {
    // report the success of the request (this does not mean the item
    // has been stored successfully in the DB - for that you need transaction.oncomplete)
    note.appendChild(document.createElement("li")).textContent =
      "Request successful.";
  };
}

• Использование IndexedDB
• Начало транзакций: IDBDatabase
• Установка диапазона ключей: IDBKeyRange
• Извлечение и внесение изменений в ваши данные: IDBObjectStore
• Использование курсоров: IDBCursor
• Пример для справки: To-do Notifications (Посмотреть пример в действии).