Skip to content

nocobase/nocobase / packages/plugins/app-plugin-database-explorer/skills/nocobase-app-plugin-database-explorer

nocobase-app-plugin-database-explorer

Verified

Browse an application's database connections, collections, and fields read-only through the Database Explorer endpoints, and grant access to them.

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 pathReturns
GET /api/databaseExplorer/connectionsEvery configured connection; the default one has isDefault: true
GET /api/databaseExplorer/connections/:connection/collectionsOne page of collections; pageSize is 1–100 (default 20), pageToken opaque
GET /api/databaseExplorer/connections/:connection/collections/:collectionThe resolved definition, its fields, and resolution warnings
GET /api/databaseExplorer/connections/:connection/collections/:collection/physicalSchemaPhysical 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.

deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall