Nocobase App Plugin Database Explorer Skill for Cursor

Database Explorer

Use this Skill when

Someone needs to see what databases an application talks to, which collections live on each one, or what fields and physical columns a collection has — and when a role other than System Administrator should be able to see that.

It is not for changing anything. The plugin has no write endpoint, and creating or altering a collection belongs to migrations.

Public surfaces

Four read endpoints:

| Method and path | Returns |

| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |

| GET /api/databaseExplorer/connections | Every configured connection; the default one has isDefault: true |

| GET /api/databaseExplorer/connections/:connection/collections | One page of collections; pageSize is 1–100 (default 20), pageToken opaque |

| GET /api/databaseExplorer/connections/:connection/collections/:collection | The resolved definition, its fields, and resolution warnings |

| GET /api/databaseExplorer/connections/:connection/collections/:collection/physicalSchema | Physical columns, indexes, keys, and constraints |

Success is { data }; the connection list is { data, meta: { total } } and the collection list { data, meta: { nextPageToken? } }. Failures use the standard /api error body with domain databaseExplorer; branch on reason: DATABASE_EXPLORER_FORBIDDEN (403), CONNECTION_NOT_FOUND and COLLECTION_NOT_FOUND (404), INVALID_CURSOR and INVALID_LIST_OPTIONS (400), and DATABASE_UNAVAILABLE, CONNECTION_UNAVAILABLE, CONNECTION_UNREACHABLE and SCHEMA_READ_DENIED (503). A malformed pageSize or pageToken is 400 INVALID_INPUT in the app domain.

The running application documents these routes under the DatabaseExplorer tag at /api/swagger/docs (JSON at /api/swagger, signed in); their operationIds are databaseExplorerListConnections, databaseExplorerListCollections, databaseExplorerGetCollection and databaseExplorerGetPhysicalSchema.

The client entry exports DatabaseExplorerClient, a typed client for these endpoints, and DATABASE_EXPLORER_ACCESS, the grant they check. The plugin contributes no pages; an application that wants one builds it on the client and declares it among its own routes with that grant. The server entry also exports the read functions (listConnections, listCollections, readCollection, readPhysicalCollection), the DATABASE_EXPLORER_PAGE constant, and the response types.

Prerequisites

Register @nocobase/app-plugin-authentication and @nocobase/app-plugin-authorization before this plugin on both runtimes. An application configured with database.default: none gets 503 DATABASE_UNAVAILABLE from every endpoint.

App workflow

Add the plugin to both composition roots and to the application's dependencies:

// server/plugins.ts
import databaseExplorer from '@nocobase/app-plugin-database-explorer/server';

// client/plugins.ts
import databaseExplorer from '@nocobase/app-plugin-database-explorer/client';
// then call it: databaseExplorer()

A System Administrator can already read the endpoints, because that permission set grants page:*/access. To let another role in, add one grant to its permission set:

{
  "resource": { "type": "page", "id": "database-explorer" },
  "actions": [{ "action": "access" }]
}

An application page built on the endpoints declares its route with the same grant (DATABASE_EXPLORER_ACCESS), so the navigation entry and the endpoints never disagree.

Ownership

The plugin owns the access resource, its endpoints and their response shapes, and the rule about what a connection may reveal. Applications own whether the plugin is registered, any page built on it, and who is granted access.

Connection responses never carry a password, user name, host, port, socket path, SQLite filename, TLS material, driver options, or pool settings. That list is enforced as an allow-list in server/connection-summary.ts, so a field a new dialect adds stays inside by default. Do not turn it into a deny-list, and do not add a locator to it because a screen looks sparse. The same restraint applies to logs: a driver error is recorded by classification only, never by message or cause.

The Explorer issues no writes of its own. On a managed connection, a first collection read can initialize __nocobase_collection_metadata, its companion cache-version table, and the initial version row, including bookkeeping added by an upgrade. Business collections, their rows, and existing metadata documents remain unchanged; subsequent reads also leave all bookkeeping rows unchanged. External connections use a directory-backed metadata store and do not create these tables.