Class Database<ADAPTER>

Creates a new database session. This is the preferred way of working with the database and to enjoy all ORM features. Call DatabaseSession.commit to persist changes all at once in the most performant way possible. The creation of a DatabaseSession is very low cost, so creating many or often is the preferred way. * All entity instances fetched/stored during this session are cached and tracked automatically.

Note: This is not equal to a database transaction. A session means a work block where you need to fetch, change, and save entity instances. Every instance fetched stays in the identity-map of that session and keeps it alive, so make sure to not keep a session for too long (especially not cross requests).

Example

const database = new Database(...);

express.on('request', async (req) => {
    const session = database.createSession();
    const user = session.query(User).filter({id: req.params.id}).findOne();
    user.name = req.params.name;
    await session.commit(); //session will be garbage collected and should NOT be stored for the next request
});

Tells the adapter to disconnect. It reconnects automatically when necessary.

Creates a new reference.

If you work with a DatabaseSession, use DatabaseSession.getReference instead to maintain object identity.

const user = database.getReference(User, 1);

Makes sure the schemas types, indices, uniques, etc are reflected in the database.

WARNING: DON'T USE THIS IN PRODUCTION AS THIS CAN CAUSE EASILY DATA LOSS. SEE THE MIGRATION DOCUMENTATION TO UNDERSTAND ITS IMPLICATIONS.

Simple direct persist. The persistence layer (batch) inserts or updates the record depending on the state of the given items. This is different to createSession()+add() in a way that DatabaseSession.add adds the given items to the queue (which is then committed using commit()) while this database.persist just simply inserts/updates the given items immediately, completely bypassing the advantages of the unit of work for multiple items.

You should prefer the add/remove and commit() workflow to fully utilizing database performance.

Registers a new entity to this database. This is mainly used for db migration utilities and active record. If you want to use active record, you have to assign your entities first to a database using this method.

Simple direct remove. The persistence layer (batch) removes all given items. This is different to createSession()+remove() in a way that DatabaseSession.remove adds the given items to the queue (which is then committed using commit()) while this database.remove just simply removes the given items immediately, completely bypassing the advantages of the unit of work for multiple items.

You should prefer the add/remove and commit() workflow to fully utilizing database performance.

Executes given callback in a new session and automatically commits it when executed successfully. This has the same semantics as createSession.

Executes an async callback inside of a new transactional session. If the callback succeeds (not throwing), the session is automatically committed (and thus its transaction committed and all changes flushed). If the callback throws, the session executes rollback() automatically, and the error is rethrown.

await database.transaction(async (session) => {
    await session.query(...);
    session.add(...);

    //...
});