docusaurus-plugin-dbschema

A Docusaurus plugin that renders interactive database schema documentation from JSON definitions, powered by @xyflow/react.

Provides a set of theme components to visualize tables, views, functions, procedures, triggers, enums, domains, and sequences — both as a browsable object list and as an interactive ERD diagram.

Installation

npm install docusaurus-plugin-dbschema
# or
pnpm add docusaurus-plugin-dbschema

Configuration

Register the plugin in your docusaurus.config.ts:

import type { DocusaurusConfig } from '@docusaurus/types';

const config: DocusaurusConfig = {
  plugins: [
    [
      'docusaurus-plugin-dbschema',
      {
        routeBasePath: '/',
      },
    ],
  ],
};

export default config;

routeBasePath

The base path corresponds to the folder where your schema .mdx files live inside docs/, not to the files themselves.

| Files location | routeBasePath | |----------------|-----------------| | docs/db/... | / | | docs/example/db/... | /example |

Schema data files

Schema definitions are JSON files that you place anywhere accessible to your Docusaurus site (e.g. schemas/schema/schema.json). The exact structure may evolve — refer to the provided examples for the current format.

Usage

Object list page

DbSchemaObjects renders a browsable list of all schema entities and acts as the index page for your schema documentation.

import DbSchemaObjects from '@theme/DbSchemaObjects';
import schema from '@site/schemas/schema/schema.json';

<DbSchemaObjects schema={schema} />

Detail components

Each object type has a dedicated detail component. Import the schema JSON and pass the name of the specific entity you want to display.

import DbSchemaTableDetail from '@theme/DbSchemaTableDetail';
import schema from '@site/schemas/schema/example.json';

<DbSchemaTableDetail schema={schema} name="athlete" />

Available components:

| Component | Renders | |-----------|---------| | @theme/DbSchemaTableDetail | Table columns, types, constraints, and foreign keys | | @theme/DbSchemaViewDetail | View definition and columns | | @theme/DbSchemaFunctionDetail | Function signature, parameters, return type, and DDL | | @theme/DbSchemaProcedureDetail | Procedure signature, parameters, and DDL | | @theme/DbSchemaTriggerDetail | Trigger event, timing, table, and linked function | | @theme/DbSchemaEnumDetail | Enum values | | @theme/DbSchemaDomainDetail | Domain base type, nullability, and check constraint | | @theme/DbSchemaSequenceDetail | Sequence parameters and ownership | | @theme/DbSchema | Interactive ERD diagram (pannable, zoomable) |

Frontmatter

For DbSchemaObjects to generate correct internal links to each detail page, every .mdx file that renders a detail component must declare two frontmatter fields:

---
dbschema:
  type: tables
  name: athlete
---

import DbSchemaTableDetail from '@theme/DbSchemaTableDetail';
import schema from '@site/schemas/example/example.json';

<DbSchemaTableDetail schema={schema} name="athlete" />

type must match the JSON collection key for that entity (tables, views, functions, procedures, triggers, enums, domains, sequences). name must exactly match the entity name in the JSON.

ERD diagram

import DbSchema from '@theme/DbSchema';
import schema from '@site/schemas/example/example.json';

<DbSchema schema={schema} />

The diagram renders all tables and their relationships as an interactive canvas. It is wrapped in BrowserOnly and does not produce static HTML output.

Type color customization

Column type badges are rendered with a default style. Any type name — including custom or user-defined types — can be styled by defining CSS variables in your custom stylesheet:

:root {
  --dbschema-col-type-uuid-background-color: #e8f4ff;
  --dbschema-col-type-uuid-color: #1a5fa8;
  --dbschema-col-type-uuid-border-color: #bad4f5;

  --dbschema-col-type-jsonb-background-color: #fff7e6;
  --dbschema-col-type-jsonb-color: #7a4a00;
  --dbschema-col-type-jsonb-border-color: #f5d08a;
}

The variable name pattern is:

--dbschema-col-type-{type-name}-background-color
--dbschema-col-type-{type-name}-color
--dbschema-col-type-{type-name}-border-color

{type-name} is the type string as it appears in the JSON, lowercased. Types without explicit variables fall back to the default badge style. All three variables must be defined together for consistent rendering.

License

MIT © Alberti Group