Dexie.on.populate-(old-version)
Syntax
db.on("populate", function (transaction) {});
Parameters
transaction: Transaction | Transaction object to work with |
Description
The populate event occurs only once in a database’ lifetime - in case the database was not present on the client when db.open() was called, and the object stores was needed to be created.
When upgrading database, on(“populate”) will NOT be called since it was already called before when database was created in the previous version. In case you change the code that subscribes to the populate event between versions, you should add an upgrade function to the new version that upgrades earlier populated data.
The populate event is fired during an onupgradeneeded event and before db.open() has been successfully committed. In case an exception is thrown or an error event happens during the populate event, the entire database creation will be aborted and db.open() will fail.
Sample
var db = new Dexie("MyDB");
db.version(1).stores({friends: "id++,name,gender"});
db.on("populate", function() {
db.friends.add({name: "Josephina", gender: "unisex"});
});
db.open();
Limitations
The transaction instance given to callback is an upgrade transaction and as all IndexedDB transactions, it will commit as soon as you stop using it. This means that if you call other async APIs, such as ajax calls or setTimeout(), the transaction object will automatically commit and you cannot continue populate data using that transaction.
If your aim is to populate the database from an ajax- or other asynchronous request, you can do so by using the on(‘ready’) event rather than on(‘populate’). See a working (and fully tested) sample below:
Ajax Populate Sample
This sample shows how to populate your database from an ajax call. Note that on(‘populate’) is not suitable for that and instead we are using on(‘ready’):
var db = new Dexie('someDB');
db.version(1).stores({
someTable: "++id,someIndex"
});
// Populate from AJAX:
db.on('ready', function () {
return db.someTable.count(function (count) {
if (count == 0) {
// DB empty. Populate.
return new Dexie.Promise(function (resolve, reject) {
$.ajax(url, {
type: 'get',
dataType: 'json',
error: function (xhr, textStatus) {
// Rejecting promise to make db.open() fail.
reject(textStatus);
},
success: function (data) {
resolve(data); // Resolving Promise will launch then() below.
}
});
}).then(function (data) {
return db.transaction('rw', db.someTable, function (someTable) {
data.someInitArrayOfObjects.forEach(function (item) {
someTable.add(item);
});
});
});
}
});
});
db.open(); // Will resolve when data is fully populated (or fail if error)
Same Sample with Comments And Logging
var db = new Dexie('someDB');
db.version(1).stores({
someTable: "++id,someIndex"
});
// Populate from AJAX:
db.on('ready', function () {
// on('ready') event will fire when database is open but before any
// other queued operations start executing.
// By returning a Promise from this event,
// the framework will wait until promise completes before
// resuming any queued database operations.
// Let's start by using the count() method to detect if database has already been
// populated.
return db.someTable.count(function (count) {
if (count > 0) {
console.log("Already populated");
} else {
console.log("Database is empty. Populating from ajax call...");
// We want framework to continue waiting, so we encapsulate the ajax call
// in a Dexie.Promise that we return here.
return new Dexie.Promise(function (resolve, reject) {
$.ajax(url, {
type: 'get',
dataType: 'json',
error: function (xhr, textStatus) {
// Rejecting promise to make db.open() fail.
reject(textStatus);
},
success: function (data) {
resolve(data); // Resolving Promise will launch then() below.
}
});
}).then(function (data) {
console.log("Got ajax response. We'll now add the objects.");
// By returning the db.transaction() promise, framework will keep
// waiting for this transaction to commit before resuming other
// db-operations.
return db.transaction('rw', db.someTable, function (someTable) {
data.someInitArrayOfObjects.forEach(function (item) {
console.log("Adding object: " + JSON.stringify(item));
someTable.add(item);
});
});
}).then(function () {
console.log ("Transaction committed");
});
}
});
});
db.open(); // Will resolve when data is fully populated (or fail if error)
// Following operation will be queued until we're finished populating data:
db.someTable.each(function (obj) {
// When we come here, data is fully populated and we can log all objects.
console.log("Found object: " + JSON.stringify(obj));
}).then(function () {
console.log("Finished.");
}).catch(function (error) {
// In our each() callback above fails, OR db.open() fails due to any reason,
// including our ajax call failed, this operation will fail and we will get
// the error here!
console.error(error.stack || error);
// Note that we could also have caught it on db.open() but in this sample,
// we show it here.
});
Console Output on first run:
Database is empty. Populating from ajax call...
Got ajax response. We'll now add the objects.
Adding object: {"someIndex":"item1"}
Adding object: {"someIndex":"item2"}
Transaction committed
Found object: {"someIndex":"item1","id":1}
Found object: {"someIndex":"item2","id":2}
Finished.
Console Output when data is already populated:
Already populated
Found object: {"someIndex":"item1","id":1}
Found object: {"someIndex":"item2","id":2}
Finished.
Watch the full HTML source, or view it in your browser
See Also
Table of Contents
- API Reference
- Access Control in Dexie Cloud
- Add demo users
- Add public data
- Authentication in Dexie Cloud
- Best Practices
- Building Addons
- Collection
- Collection.and()
- Collection.clone()
- Collection.count()
- Collection.delete()
- Collection.desc()
- Collection.distinct()
- Collection.each()
- Collection.eachKey()
- Collection.eachPrimaryKey()
- Collection.eachUniqueKey()
- Collection.filter()
- Collection.first()
- Collection.keys()
- Collection.last()
- Collection.limit()
- Collection.modify()
- Collection.offset()
- Collection.or()
- Collection.primaryKeys()
- Collection.raw()
- Collection.reverse()
- Collection.sortBy()
- Collection.toArray()
- Collection.uniqueKeys()
- Collection.until()
- Compound Index
- Consistency in Dexie Cloud
- Consistent add() operator
- Consistent remove() operator
- Consistent replacePrefix() operator
- Consuming Dexie as a module
- Custom Emails in Dexie Cloud
- DBCore
- DBCoreAddRequest
- DBCoreCountRequest
- DBCoreCursor
- DBCoreDeleteRangeRequest
- DBCoreDeleteRequest
- DBCoreGetManyRequest
- DBCoreGetRequest
- DBCoreIndex
- DBCoreKeyRange
- DBCoreMutateRequest
- DBCoreMutateResponse
- DBCoreOpenCursorRequest
- DBCorePutRequest
- DBCoreQuery
- DBCoreQueryRequest
- DBCoreQueryResponse
- DBCoreRangeType
- DBCoreSchema
- DBCoreTable
- DBCoreTableSchema
- DBCoreTransaction
- DBCoreTransactionMode
- DBPermissionSet
- Deprecations
- Derived Work
- Design
- Dexie Cloud API
- Dexie Cloud API Limits
- Dexie Cloud Best Practices
- Dexie Cloud CLI
- Dexie Cloud Docs
- Dexie Cloud REST API
- Dexie Cloud Web Hooks
- Dexie Constructor
- Dexie.AbortError
- Dexie.BulkError
- Dexie.ConstraintError
- Dexie.DataCloneError
- Dexie.DataError
- Dexie.DatabaseClosedError
- Dexie.IncompatiblePromiseError
- Dexie.InternalError
- Dexie.InvalidAccessError
- Dexie.InvalidArgumentError
- Dexie.InvalidStateError
- Dexie.InvalidTableError
- Dexie.MissingAPIError
- Dexie.ModifyError
- Dexie.NoSuchDatabaseErrorError
- Dexie.NotFoundError
- Dexie.Observable
- Dexie.Observable.DatabaseChange
- Dexie.OpenFailedError
- Dexie.PrematureCommitError
- Dexie.QuotaExceededError
- Dexie.ReadOnlyError
- Dexie.SchemaError
- Dexie.SubTransactionError
- Dexie.Syncable
- Dexie.Syncable.IDatabaseChange
- Dexie.Syncable.IPersistentContext
- Dexie.Syncable.ISyncProtocol
- Dexie.Syncable.StatusTexts
- Dexie.Syncable.Statuses
- Dexie.Syncable.registerSyncProtocol()
- Dexie.TimeoutError
- Dexie.TransactionInactiveError
- Dexie.UnknownError
- Dexie.UnsupportedError
- Dexie.UpgradeError()
- Dexie.VersionChangeError
- Dexie.VersionError
- Dexie.[table]
- Dexie.addons
- Dexie.async()
- Dexie.backendDB()
- Dexie.close()
- Dexie.currentTransaction
- Dexie.debug
- Dexie.deepClone()
- Dexie.defineClass()
- Dexie.delByKeyPath()
- Dexie.delete()
- Dexie.derive()
- Dexie.events()
- Dexie.exists()
- Dexie.extend()
- Dexie.fakeAutoComplete()
- Dexie.getByKeyPath()
- Dexie.getDatabaseNames()
- Dexie.hasFailed()
- Dexie.ignoreTransaction()
- Dexie.isOpen()
- Dexie.js
- Dexie.name
- Dexie.on()
- Dexie.on.blocked
- Dexie.on.close
- Dexie.on.error
- Dexie.on.populate
- Dexie.on.populate-(old-version)
- Dexie.on.ready
- Dexie.on.storagemutated
- Dexie.on.versionchange
- Dexie.open()
- Dexie.override()
- Dexie.semVer
- Dexie.setByKeyPath()
- Dexie.shallowClone()
- Dexie.spawn()
- Dexie.table()
- Dexie.tables
- Dexie.transaction()
- Dexie.transaction()-(old-version)
- Dexie.use()
- Dexie.verno
- Dexie.version
- Dexie.version()
- Dexie.vip()
- Dexie.waitFor()
- DexieCloudOptions
- DexieError
- Docs Home
- Download
- EntityTable
- Export and Import Database
- Get started with Dexie in Angular
- Get started with Dexie in React
- Get started with Dexie in Svelte
- Get started with Dexie in Vue
- Hello World
- How To Use the StorageManager API
- Inbound
- IndexSpec
- Indexable Type
- IndexedDB on Safari
- Invite
- Member
- Migrating existing DB to Dexie
- MultiEntry Index
- PersistedSyncState
- Privacy Policy
- Promise
- Promise.PSD
- Promise.catch()
- Promise.finally()
- Promise.on.error
- Promise.onuncatched
- Questions and Answers
- Realm
- Releasing Dexie
- Road Map
- Road Map: Dexie 5.0
- Road Map: Dexie Cloud
- Role
- Run Dexie Cloud on Own Servers
- Sharding and Scalability
- Simplify with yield
- Support Ukraine
- SyncState
- Table
- Table Schema
- Table.add()
- Table.bulkAdd()
- Table.bulkDelete()
- Table.bulkGet()
- Table.bulkPut()
- Table.bulkUpdate()
- Table.clear()
- Table.count()
- Table.defineClass()
- Table.delete()
- Table.each()
- Table.filter()
- Table.get()
- Table.hook('creating')
- Table.hook('deleting')
- Table.hook('reading')
- Table.hook('updating')
- Table.limit()
- Table.mapToClass()
- Table.name
- Table.offset()
- Table.orderBy()
- Table.put()
- Table.reverse()
- Table.schema
- Table.toArray()
- Table.toCollection()
- Table.update()
- Table.where()
- The main limitations of IndexedDB
- Transaction
- Transaction.abort()
- Transaction.on.abort
- Transaction.on.complete
- Transaction.on.error
- Transaction.table()
- Tutorial
- Typescript
- Typescript (old)
- Understanding the basics
- UserLogin
- Version
- Version.stores()
- Version.upgrade()
- WhereClause
- WhereClause.above()
- WhereClause.aboveOrEqual()
- WhereClause.anyOf()
- WhereClause.anyOfIgnoreCase()
- WhereClause.below()
- WhereClause.belowOrEqual()
- WhereClause.between()
- WhereClause.equals()
- WhereClause.equalsIgnoreCase()
- WhereClause.inAnyRange()
- WhereClause.noneOf()
- WhereClause.notEqual()
- WhereClause.startsWith()
- WhereClause.startsWithAnyOf()
- WhereClause.startsWithAnyOfIgnoreCase()
- WhereClause.startsWithIgnoreCase()
- db.cloud.configure()
- db.cloud.currentUser
- db.cloud.currentUserId
- db.cloud.events.syncComplete
- db.cloud.invites
- db.cloud.login()
- db.cloud.logout()
- db.cloud.options
- db.cloud.permissions()
- db.cloud.persistedSyncState
- db.cloud.roles
- db.cloud.schema
- db.cloud.sync()
- db.cloud.syncState
- db.cloud.userInteraction
- db.cloud.usingServiceWorker
- db.cloud.version
- db.cloud.webSocketStatus
- db.members
- db.realms
- db.roles
- db.syncable.connect()
- db.syncable.delete()
- db.syncable.disconnect()
- db.syncable.getOptions()
- db.syncable.getStatus()
- db.syncable.list()
- db.syncable.on('statusChanged')
- db.syncable.setFilter()
- dexie-cloud-addon
- dexie-react-hooks
- liveQuery()
- unhandledrejection-event
- useLiveQuery()
- useObservable()
- usePermissions()