Primitive Docs

Appearance

js-bao-wss-client

js-bao-wss-client / DatabasesAPI

Interface: DatabasesAPI ​

Client API for databases — schemaless record stores with registered operations, permissions, CSV import, and real-time change subscriptions. Accessed as client.databases.

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db and manages databases with ctx.api.databases (see the Working with Databases guide).

Methods ​

addManager() ​

addManager(databaseId, params): Promise<DatabasePermissionEntry>

Add a user as a manager of a database.

Parameters ​

databaseId ​

string

The unique identifier of the database

params ​

AddManagerParams

Manager details (userId)

Returns ​

Promise<DatabasePermissionEntry>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

connect() ​

connect(databaseId): DoDb

Connect to a database and get a DoDb instance for querying.

Parameters ​

databaseId ​

string

The unique identifier of the database to connect to

Returns ​

DoDb

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

create() ​

create(params): Promise<DatabaseInfo>

Create a new database.

Parameters ​

params ​

CreateDatabaseParams

Configuration for the new database

Returns ​

Promise<DatabaseInfo>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

createOperation() ​

createOperation(databaseId, params): Promise<DatabaseOperationInfo>

Create a new operation (query or mutation) on a database.

Parameters ​

databaseId ​

string

The unique identifier of the database to add the operation to

params ​

CreateOperationParams

Operation definition

Returns ​

Promise<DatabaseOperationInfo>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

delete() ​

delete(databaseId): Promise<{ success: boolean; }>

Delete a database.

Deliberately narrower than every other database route: only a direct owner grant or a console admin may delete. An app admin or app owner promoted in-app has full record access and sees the database in list() with permission: "owner", but still gets 403 here — destroying a database cascades its records, grants, and storage, and is not recoverable.

Parameters ​

databaseId ​

string

The unique identifier of the database to delete

Returns ​

Promise<{ success: boolean; }>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

deleteOperation() ​

deleteOperation(databaseId, name): Promise<{ success: boolean; }>

Delete an operation from a database.

Parameters ​

databaseId ​

string

The unique identifier of the database containing the operation

name ​

string

The name of the operation to delete

Returns ​

Promise<{ success: boolean; }>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

describe() ​

describe(databaseId, modelName): Promise<ModelFieldInfo[]>

Get the field schema for a model in a database.

Parameters ​

databaseId ​

string

The unique identifier of the database to inspect

modelName ​

string

The name of the model whose field schema to retrieve

Returns ​

Promise<ModelFieldInfo[]>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

executeBatch() ​

executeBatch<P>(databaseId, operationName, batch): Promise<{ failed: number; imported: number; }>

Execute a batch of records using a named mutation operation.

Type Parameters ​

P ​

P extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database to execute against

operationName ​

string

The name of the mutation operation to invoke for each record

batch ​

object[]

Array of parameter objects, each passed to the operation as a single invocation

Returns ​

Promise<{ failed: number; imported: number; }>

Object with imported and failed record counts

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

executeOperation() ​

executeOperation<R, P>(databaseId, name, options?): Promise<R>

Execute a registered operation by name, with optional parameters and pagination.

The optional type parameter R types the resolved result: pass the op's generated <Op>Result alias to get a typed response (executeOperation<GetXResult>(dbId, "getX", { params })). It defaults to any, so existing untyped callers keep the previous Promise<any> behavior (backward compatible). The generated <type>Ops factory supplies this type argument for you.

Type Parameters ​

R ​

R = unknown

P ​

P extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database containing the operation

name ​

string

The name of the operation to execute

options? ​

ExecuteOperationOptions<P>

Execution options for parameters, pagination, and diagnostics

Returns ​

Promise<R>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

get() ​

get(databaseId): Promise<DatabaseInfo>

Get database info by ID.

Access is granted when the caller is an app admin or app owner (whether promoted in-app or holding console access), holds a direct DatabasePermission (owner/manager), or has a matching DatabaseGroupPermission via one of their group memberships. Returns 403 "Access denied" for users whose only access is via CEL-gated operations.

As in list(), the returned permission is "owner" for any caller with app-wide authority — it reports capability, not ownership.

Parameters ​

databaseId ​

string

The unique identifier of the database to retrieve

Returns ​

Promise<DatabaseInfo>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

getCelContext() ​

getCelContext<C>(databaseId): Promise<CelContextResult<C>>

Read a database's CEL context dict.

Owners, managers, and callers with app-wide authority (an app admin or app owner, whether promoted in-app or holding console access) always have access. Everyone else needs a metadataAccess CEL rule on the database type config.

The returned payload includes the same dict under both metadata (legacy wire name) and celContext (new user-facing name).

Type Parameters ​

C ​

C extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database to read

Returns ​

Promise<CelContextResult<C>>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide). Prefer resource metadata categories. The metadataAccess gate that controls this read uses one CEL expression to gate read AND update, so granting read also grants update. A metadata category has separate readRule/writeRule; read its values from CEL as md.self.<category>.<key>.

getMetadata() ​

getMetadata<C>(databaseId): Promise<CelContextResult<C>>

Read a database's CEL context dict.

Type Parameters ​

C ​

C extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database to read

Returns ​

Promise<CelContextResult<C>>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide). Prefer resource metadata categories — a category has separate readRule/writeRule (read no longer implies update) and is read from CEL as md.self.<category>.<key>. An alias of the (also-deprecated) getCelContext.

getOperation() ​

getOperation(databaseId, name): Promise<DatabaseOperationInfo>

Get a single operation by name.

Parameters ​

databaseId ​

string

The unique identifier of the database containing the operation

name ​

string

The name of the operation to retrieve

Returns ​

Promise<DatabaseOperationInfo>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

grantGroupPermission() ​

grantGroupPermission(databaseId, params): Promise<DatabaseGroupPermissionEntry>

Grant a group permission on a database. Members of the specified group will gain the specified permission level on the database.

Parameters ​

databaseId ​

string

The unique identifier of the database to grant access to

params ​

GrantDatabaseGroupPermissionParams

The group permission to grant

Returns ​

Promise<DatabaseGroupPermissionEntry>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

grantPermission() ​

grantPermission(databaseId, params): Promise<DatabasePermissionEntry>

Grant a user permission to access a database.

Parameters ​

databaseId ​

string

The unique identifier of the database to grant access to

params ​

GrantPermissionParams

Permission grant details

Returns ​

Promise<DatabasePermissionEntry>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide). An alias of addManager.

importBulk() ​

importBulk<P>(databaseId, operationName, batch): Promise<{ failed: number; imported: number; }>

Type Parameters ​

P ​

P extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

operationName ​

string

batch ​

object[]

Returns ​

Promise<{ failed: number; imported: number; }>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide). An alias of executeBatch.

importCsv() ​

importCsv<T>(databaseId, options): Promise<CsvImportResult>

Import data from a CSV string into a database.

Type Parameters ​

T ​

T extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database to import into

options ​

CsvImportOptions<T>

Import configuration (see CsvImportOptions for full details)

Returns ​

Promise<CsvImportResult>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

list() ​

Call Signature ​

list(options): Promise<DatabaseListPage>

List all databases the current user can access.

Returns databases where the user has any of:

  • A direct DatabasePermission (owner or manager)
  • A DatabaseGroupPermission matching one of the user's group memberships

App admins and app owners see every database in the app — the same app-wide authority that grants them direct record access, whether they were promoted in-app or hold console access. Databases the user can only access via CEL-gated operations are not included in this list.

Each entry carries a permission field reflecting the highest permission level the caller has on that database. For a caller with app-wide authority that is always "owner", on every row — the field describes what the caller may do, not who owns the database. Do not use permission === "owner" to pick out "my" databases; compare createdBy against the caller's own user id instead.

Results are paged: at most 100 databases come back per call. Pass returnPage: true to receive the continuation token and follow it with cursor until nextCursor is absent.

Parameters ​
options ​

ListDatabasesOptions & object

Optional filters and paging (databaseType to limit to one type, limit/cursor to page, returnPage to get the page object)

Returns ​

Promise<DatabaseListPage>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

Call Signature ​

list(options?): Promise<DatabaseInfo[]>

List all databases the current user can access.

Returns databases where the user has any of:

  • A direct DatabasePermission (owner or manager)
  • A DatabaseGroupPermission matching one of the user's group memberships

App admins and app owners see every database in the app — the same app-wide authority that grants them direct record access, whether they were promoted in-app or hold console access. Databases the user can only access via CEL-gated operations are not included in this list.

Each entry carries a permission field reflecting the highest permission level the caller has on that database. For a caller with app-wide authority that is always "owner", on every row — the field describes what the caller may do, not who owns the database. Do not use permission === "owner" to pick out "my" databases; compare createdBy against the caller's own user id instead.

Results are paged: at most 100 databases come back per call. Pass returnPage: true to receive the continuation token and follow it with cursor until nextCursor is absent.

Parameters ​
options? ​

ListDatabasesOptions

Optional filters and paging (databaseType to limit to one type, limit/cursor to page, returnPage to get the page object)

Returns ​

Promise<DatabaseInfo[]>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

listGroupPermissions() ​

listGroupPermissions(databaseId, options?): Promise<DatabaseGroupPermissionEntry[]>

List all group-based permissions for a database.

By default, platform-managed internal groups (those whose groupType is prefixed with _) are excluded. Pass { includeSystem: true } to include them (typically only useful for admin tooling).

Parameters ​

databaseId ​

string

The unique identifier of the database whose group permissions to list

options? ​

Optional list options. Set includeSystem to true to include platform-managed internal groups in the result.

includeSystem? ​

boolean

Returns ​

Promise<DatabaseGroupPermissionEntry[]>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

listOperations() ​

listOperations(databaseId): Promise<DatabaseOperationInfo[]>

List all operations registered on a database.

Parameters ​

databaseId ​

string

The unique identifier of the database whose operations to list

Returns ​

Promise<DatabaseOperationInfo[]>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

listPermissions() ​

listPermissions(databaseId): Promise<DatabasePermissionEntry[]>

List all permission entries for a database.

Parameters ​

databaseId ​

string

The unique identifier of the database whose permissions to list

Returns ​

Promise<DatabasePermissionEntry[]>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

removeManager() ​

removeManager(databaseId, userId): Promise<{ success: boolean; }>

Remove a manager from a database.

Parameters ​

databaseId ​

string

The unique identifier of the database

userId ​

string

The user ID of the manager to remove

Returns ​

Promise<{ success: boolean; }>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

revokeGroupPermission() ​

revokeGroupPermission(databaseId, groupType, groupId): Promise<{ success: boolean; }>

Revoke a group's permission on a database.

Parameters ​

databaseId ​

string

The unique identifier of the database to revoke access from

groupType ​

string

The type of group whose permission to revoke

groupId ​

string

The identifier of the group whose permission to revoke

Returns ​

Promise<{ success: boolean; }>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

revokePermission() ​

revokePermission(databaseId, userId): Promise<{ success: boolean; }>

Revoke a user's permission to a database.

Parameters ​

databaseId ​

string

The unique identifier of the database to revoke access from

userId ​

string

The user whose permission should be removed

Returns ​

Promise<{ success: boolean; }>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide). An alias of removeManager.

subscribe() ​

subscribe<T, P>(databaseId, subscriptionKey, options): () => void

Subscribe to real-time database changes for a server-registered subscription (created via the /databases/:id/subscriptions admin endpoint). The server filters events by the subscription's CEL filter and access rule, so the callback only fires for rows the subscriber is allowed to see.

Sends db.subscribe over the active WebSocket; inbound db.change frames are routed back to this callback. On reconnect, the client automatically re-issues db.subscribe for every active subscription (matches the existing doc-subscription reconnect behavior).

Type Parameters ​

T ​

T = unknown

P ​

P extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The database the subscription is registered on.

subscriptionKey ​

string

The subscription key (admin-defined).

options ​

DatabaseSubscribeOptions<T, P>

params forwarded to the server's filter CEL, plus the onChange callback.

Returns ​

unsub() — removes the callback and sends db.unsubscribe.

() => void

Example ​

ts
const unsub = client.databases.subscribe(dbId, "my-tasks", {
  params: { userId: currentUserId },
  onChange: (event) => {
    for (const change of event.changes) {
      console.log(change.op, change.id, change.data);
    }
  },
});
// Later:
unsub();

Deprecated ​

Subscribe to a channel instead: a server function authorizes it with ctx.channels.authorize and publishes to it with ctx.channels.publish, and the client joins it with client.subscribeToChannel (see the Server Functions guide).

transferOwnership() ​

transferOwnership(databaseId, newOwnerId): Promise<DatabaseOwnershipTransferResult>

Transfer database ownership to another user.

Parameters ​

databaseId ​

string

The unique identifier of the database to transfer

newOwnerId ​

string

The user ID of the new owner

Returns ​

Promise<DatabaseOwnershipTransferResult>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

update() ​

update(databaseId, params): Promise<DatabaseInfo>

Update a database's title or type.

Parameters ​

databaseId ​

string

The unique identifier of the database to update

params ​

UpdateDatabaseParams

Fields to update on the database

Returns ​

Promise<DatabaseInfo>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide).

updateCelContext() ​

updateCelContext<C>(databaseId, celContext): Promise<DatabaseInfo>

Update a database's CEL context dict (merge with existing).

Values set here are referenced from CEL access rules as database.celContext.<key> (or legacy database.metadata.<key>) and from filter JSON as $database.celContext.<key>.

Type Parameters ​

C ​

C extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database to update

celContext ​

C

Key-value pairs to merge into the database's existing CEL context

Returns ​

Promise<DatabaseInfo>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide). Prefer resource metadata categories. Writing here is gated by the same single metadataAccess expression that gates reads, so anyone allowed to read can also update. A metadata category has separate readRule/writeRule; write its values with resourceMetadata / initialMetadata and read them from CEL as md.self.<category>.<key>.

updateMetadata() ​

updateMetadata<C>(databaseId, metadata): Promise<DatabaseInfo>

Update a database's CEL context dict (merge with existing).

Type Parameters ​

C ​

C extends object = Record<string, unknown>

Parameters ​

databaseId ​

string

The unique identifier of the database to update

metadata ​

C

Key-value pairs to merge into the database's existing CEL context

Returns ​

Promise<DatabaseInfo>

Deprecated ​

Call a server function instead: it manages databases with ctx.api.databases (see the Working with Databases guide). Prefer resource metadata categories — a category has separate readRule/writeRule, so a writer no longer inherits update from read access. Write category values with resourceMetadata / initialMetadata and read them from CEL as md.self.<category>.<key>. This is the legacy wire-name alias of the (also-deprecated) updateCelContext.

updateOperation() ​

updateOperation(databaseId, name, params): Promise<DatabaseOperationInfo>

Update an existing operation's definition or access level.

Parameters ​

databaseId ​

string

The unique identifier of the database containing the operation

name ​

string

The name of the operation to update

params ​

UpdateOperationParams

Fields to update on the operation

Returns ​

Promise<DatabaseOperationInfo>

Deprecated ​

Call a server function instead: it reads and writes records with ctx.db (see the Working with Databases guide).

Documentation validated against js-bao-wss-client 3.4.0 · js-bao 0.11.0 · primitive-admin 1.0.62 · primitive-app 3.1.0 — 2026-09-30