Database

This class provides methods to interact with the database. It supports both MongoDB and SQLite backends and offers operations for creating, updating, deleting, and querying user and level-role documents. Methods set createdAt and lastUpdated timestamps when creating or updating records.

Methods

Database.getCollection()

Returns a collection from the database.

caution

This function can only be used with MongoDB databases.

Parameters

Parameter	Type	Required	Description
collection	string	✅	The name of the collection to get.

Returns Collection - MongoDB Collection

---

Database.createOne()

caution

ALL query properties are required here.

Creates a new document in the database. The method automatically adds createdAt and lastUpdated ISO timestamps. Many fields in the data object are optional (for example name, user, level, xp, and flags for simply-xps). The method supports both MongoDB and SQLite backends.

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	The options for user or level role.

Returns Promise<UserResult | LevelRoleResult> - User or Level Role

---

Database.deleteMany()

Deletes multiple documents from the database. Returns true when the underlying driver reports a result object (for SQLite the run() result is treated as truthy when successful).

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	The options for user or level role.

Returns Promise<boolean> - true if documents were deleted, otherwise false

---

Database.deleteOne()

Deletes a single document from the database.

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	The options for user or level role.

Returns Promise<boolean> - true if a document was deleted, otherwise false

---

Database.findOne()

Finds a document from the database.

Parameters

Parameter	Type	Required	Description
query	UserOptions LevelRoleOptions	✅	The options for user or level role.

Returns Promise<UserResult | LevelRoleResult> - User or Level Role

---

Database.find()

Finds documents from the database for a given guild. For SQLite simply-xps rows will have the flags column parsed from JSON back into an array. The collection parameter must be either simply-xps or simply-xp-levelroles.

Parameters

Parameter	Type	Required	Description
collection	simply-xps simply-xp-levelroles	✅	The name of the collection to get.
guild	string	✅	The guild ID.
limit	number	❌	Optional max number of documents to return.

Returns Promise< UserResult[] | LevelRoleResult[] > - User or Level Role

---

Database.findAll()

Finds all documents from the database.

Parameters

Parameter	Type	Required	Description
collection	simply-xps simply-xp-levelroles	✅	The name of the collection to get.
limit	number	❌	Optional max number of documents to return.

Returns Promise< UserResult[] | LevelRoleResult[] > - User or Level Role

---

Database.findGlobalLeaderboard()

Finds the global leaderboard across every guild, keeping one row per user: whichever of their guild rows has the highest XP (ties broken by most recently updated, then most recently created). Used internally by leaderboard() when called without a guildId.

Parameters

Parameter	Type	Required	Description
limit	number	❌	Optional max number of users to return.

Returns Promise< UserResult[] > - One row per user, sorted by XP descending.

---

Database.updateOne()

Updates a document in the database.

Parameters

Parameter	Type	Required	Description
filter	UserOptions LevelRoleOptions	✅	The options for user or level role.
update	UserOptions LevelRoleOptions	✅	The update to apply to the document.
options	{ upsert?: boolean }	❌	MongoDB upsert options.

Returns Promise<UserResult | LevelRoleResult> - User or Level Role

---

Database.namespace()

Returns a private key/value store for a plugin, so plugins can persist their own data without touching xp.database or the simply-xp tables directly.

Works on both MongoDB and SQLite. Storage is created lazily on the first write, so plugins that never store anything add nothing to your database.

Parameters

Parameter	Type	Required	Description
name	string	✅	Namespace, usually your plugin's package name.

Returns PluginStore

Method	Returns	Description
get(key)	Promise<T | null>	Reads a value, or null when the key is not set.
set(key, value)	Promise<void>	Writes a value. Anything JSON-serialisable is accepted.
delete(key)	Promise<boolean>	Removes a key, returning whether it existed.
keys()	Promise<string[]>	Lists every key in this namespace.
clear()	Promise<number>	Removes every key in this namespace, returning how many.

Throws

• XpFatal - If no name is provided, or if there is no database connection.

Example

const { Database } = require("simply-xp");

const store = Database.namespace("simply-xp-rate-limits");

await store.set(`cooldown:${userId}`, { until: Date.now() + 60_000 });

const cooldown = await store.get(`cooldown:${userId}`);
if (cooldown && cooldown.until > Date.now()) return; // still cooling down

tip

Namespaces are isolated from each other, so two plugins can safely use the same key names.

---

Database.countUsersWithMoreXp()

Counts users in a guild with strictly more XP than a given value. Used internally by fetch() and rankCard() to compute a user's leaderboard position without loading the full guild into memory.

Parameters

Parameter	Type	Required	Description
guildId	string	✅	The guild ID.
xpValue	number	✅	Count users with XP greater than this value.

Returns Promise<number> - The number of users with more XP.