Ent API: insert*()
Ent Framework exposes an opinionated API which allows to write and read data from the microsharded database.
There are several versions of insert*
static methods on each Ent class.
insertIfNotExists(vc, { field: "...", ... }): string | null
inserts a new Ent and returns its ID or null if the Ent violates unique index constraints. This is a low-level method, all other methods use it internally.
insert(vc, { field: "...", ... }): string
Inserts a new Ent and returns its ID.
Throws EntUniqueKeyError
if it violates unique index constraints. Always returns an ID of just-inserted Ent.
insertReturning(vc, { field: "...", ... }): Ent
Same as insert()
, but immediately loads the just-inserted Ent back from the database and returns it. The reasoning is that the database may have fields with default values or even PG triggers, so we always need 2 round-trips to get the actual data.
VC Embedding
When some Ent is loaded in a VC, its ent.vc
is assigned to that VC. In the above example, we use req.vc
and topic.vc
interchangeably.
Embedding a VC into each Ent is a crucial aspect of Ent Framework. It allows to remove lots of boilerplate from the code. Instead of passing an instance of some VC everywhere from function to function, we can just pass Ents, and we'll always have an up-to-date VC:
You almost never need to pass a VC from function to function: pass Ent instances instead. Having an explicit vc
argument somewhere is a smell.
Last updated
Was this helpful?