Skip to main content

Interface: GenericDatabaseWriter<DataModel>

server.GenericDatabaseWriter

An interface to read from and write to the database within Convex mutation functions.

Convex guarantees that all writes within a single mutation are executed atomically, so you never have to worry about partial writes leaving your data in an inconsistent state. See the Convex Guide for the guarantees Convex provides your functions.

If you're using code generation, use the DatabaseReader type in convex/_generated/server.d.ts which is typed for your data model.

Type parameters

NameType
DataModelextends GenericDataModel

Hierarchy

Properties

system

system: BaseDatabaseReader<SystemDataModel>

An interface to read from the system tables within Convex query functions

The two entry points are:

  • get, which fetches a single document by its GenericId.
  • query, which starts building a query.

Inherited from

DatabaseWriter.system

Defined in

server/database.ts:93

Methods

get

get<TableName>(id): Promise<null | DocumentByName<DataModel, TableName>>

Fetch a single document from the database by its GenericId.

Type parameters

NameType
TableNameextends string

Parameters

NameTypeDescription
idGenericId<TableName>The GenericId of the document to fetch from the database.

Returns

Promise<null | DocumentByName<DataModel, TableName>>

Inherited from

DatabaseWriter.get

Defined in

server/database.ts:33


query

query<TableName>(tableName): QueryInitializer<NamedTableInfo<DataModel, TableName>>

Begin a query for the given table name.

Queries don't execute immediately, so calling this method and extending its query are free until the results are actually used.

Type parameters

NameType
TableNameextends string

Parameters

NameTypeDescription
tableNameTableNameThe name of the table to query.

Returns

QueryInitializer<NamedTableInfo<DataModel, TableName>>

Inherited from

DatabaseWriter.query

Defined in

server/database.ts:46


normalizeId

normalizeId<TableName>(tableName, id): null | GenericId<TableName>

Returns the string ID format for the ID in a given table, or null if the ID is from a different table or is not a valid ID.

This accepts the string ID format as well as the .toString() representation of the legacy class-based ID format.

This does not guarantee that the ID exists (i.e. db.get(id) may return null).

Type parameters

NameType
TableNameextends string

Parameters

NameTypeDescription
tableNameTableNameThe name of the table.
idstringThe ID string.

Returns

null | GenericId<TableName>

Inherited from

DatabaseWriter.normalizeId

Defined in

server/database.ts:62


insert

insert<TableName>(table, value): Promise<GenericId<TableName>>

Insert a new document into a table.

Type parameters

NameType
TableNameextends string

Parameters

NameTypeDescription
tableTableNameThe name of the table to insert a new document into.
valueExpand<BetterOmit<DocumentByName<DataModel, TableName>, "_creationTime" | "_id">>The Value to insert into the given table.

Returns

Promise<GenericId<TableName>>

Inherited from

DatabaseWriter.insert

Defined in

server/database.ts:112


patch

patch<TableName>(id, value): Promise<void>

Patch an existing document, shallow merging it with the given partial document.

New fields are added. Existing fields are overwritten. Fields set to undefined are removed.

Type parameters

NameType
TableNameextends string

Parameters

NameTypeDescription
idGenericId<TableName>The GenericId of the document to patch.
valuePartial<DocumentByName<DataModel, TableName>>The partial GenericDocument to merge into the specified document. If this new value specifies system fields like _id, they must match the document's existing field values.

Returns

Promise<void>

Inherited from

DatabaseWriter.patch

Defined in

server/database.ts:128


replace

replace<TableName>(id, value): Promise<void>

Replace the value of an existing document, overwriting its old value.

Type parameters

NameType
TableNameextends string

Parameters

NameTypeDescription
idGenericId<TableName>The GenericId of the document to replace.
valueExpand<Expand<BetterOmit<DocumentByName<DataModel, TableName>, "_creationTime" | "_id">> & Partial<Pick<DocumentByName<DataModel, TableName>, "_creationTime" | "_id">>>The new GenericDocument for the document. This value can omit the system fields, and the database will fill them in.

Returns

Promise<void>

Inherited from

DatabaseWriter.replace

Defined in

server/database.ts:140


delete

delete(id): Promise<void>

Delete an existing document.

Parameters

NameTypeDescription
idGenericId<TableNamesInDataModel<DataModel>>The GenericId of the document to remove.

Returns

Promise<void>

Inherited from

DatabaseWriter.delete

Defined in

server/database.ts:150