Instance

An instance is an object that represents a row in your database. You get one when you use create(), find(), or query():get().

local player = User.find({ identifier = "license:abc" })
-- "player" is an OrvexInstance

You can access columns as normal properties:

print(player.identifier)  -- "license:abc"
print(player.money)        -- 500
print(player.job)          -- "police"

---

Methods

instance:update(data) → boolean

Updates this row in the database. The local object is also updated.

player:update({ money = 1000, job = "medic" })
print(player.money)  -- 1000 (updated locally as well)

Generated SQL:

UPDATE users SET job = ?, money = ? WHERE identifier = ?

---

instance:delete() → boolean

Deletes this row from the database.

player:delete()

Generated SQL:

DELETE FROM users WHERE identifier = ?

---

instance:get(relationName) → OrvexInstance | OrvexInstance[] | nil

Retrieves related data through a relation.

The return type depends on the relation:

Relation type	Return
hasOne	OrvexInstance or nil
hasMany	OrvexInstance[] (list)
belongsTo	OrvexInstance or nil
belongsToMany	OrvexInstance[] (list)

-- hasOne → a single instance
local profile = player:get("profile")

-- hasMany → a list
local vehicles = player:get("vehicles")

-- belongsTo → a single instance
local owner = car:get("owner")

-- belongsToMany → a list
local roles = player:get("roles")

caution

The name passed to :get() must match exactly the name used when defining the relation (hasOne("profile", ...) → :get("profile")).

---

instance:attach(relationName, relatedInstance) → boolean

Adds a link in the pivot table of a belongsToMany relation.

local adminRole = Role.find({ name = "admin" })
player:attach("roles", adminRole)

Generated SQL:

INSERT INTO user_roles (role_id, user_id) VALUES (?, ?)

caution

attach only works on belongsToMany relations. If you use it on another relation, an error will be thrown.

---

instance:detach(relationName, relatedInstance) → boolean

Removes a link from the pivot table of a belongsToMany relation.

player:detach("roles", adminRole)

Generated SQL:

DELETE FROM user_roles WHERE role_id = ? AND user_id = ?

---

instance:increment(column, amount?) → boolean

Increments a numeric column. amount is optional (default: 1).

player:increment("money", 100)
print(player.money)  -- updated locally as well

player:increment("kills")  -- +1 by default

Generated SQL:

UPDATE users SET money = money + 100 WHERE identifier = ?

---

instance:decrement(column, amount?) → boolean

Decrements a numeric column.

player:decrement("money", 50)

---

instance:forceDelete() → boolean

Permanently deletes the row, even if soft delete is enabled.

player:forceDelete()

---

instance:restore() → boolean

Restores a soft-deleted row. Requires softDelete = true.

player:restore()
print(player.deleted_at)  -- nil

---

instance:toTable() → table

Returns a plain copy of the instance, without internal fields (_tableName, _adapter, ...) or metatable. Eager-loaded relations are converted recursively.

The main use case: sending an instance to clients via TriggerClientEvent or serializing it with json.encode.

local player = User.find({ identifier = "license:abc" }, { include = { "vehicles" } })

-- Safe to send to the client
TriggerClientEvent("myresource:playerData", src, player:toTable())

-- Safe to serialize
local json = json.encode(player:toTable())

---

instance:refresh() → boolean

Reloads the instance's columns from the database. Returns false if the row no longer exists, true otherwise. JSON fields are re-decoded.

local player = User.find({ identifier = "license:abc" })

-- ... the row may have been modified elsewhere ...

if player:refresh() then
    print(player.money)  -- fresh value from the database
else
    print("Row no longer exists")
end