# Database Visualizer

The Database Visualizer turns a Bubble database into an interactive diagram: every data type, every option set, and every relationship between them.

It is the only LumiDevKit tool that does not need a full Bubble application export, which makes it the one you can use on a free Bubble plan, or with no Bubble app at all.

## What to upload

The tool offers four ways in:

**Database Schema** — a small JSON file containing just `user_types` and `option_sets`. This is what LumiDevKit's own Download Schema produces, and what an AI produces from [our prompt](/docs/schema-format-for-ai).

**Full App Export** — a complete Bubble application export. The database part is extracted automatically and everything else is ignored. See [get your app export out of Bubble](/docs/export-your-bubble-app).

**Start from Scratch** — an empty canvas with Bubble's built-in User. No file needed. See [build or edit a schema by hand](/docs/build-and-edit-schemas).

**My Schemas** — reopen something you [saved earlier](/docs/save-and-reuse-schemas).

There is also a **Postgres / SQL** panel for [importing a Postgres schema](/docs/import-a-postgres-schema). That panel contains the only paste box on the screen, and despite its heading it accepts Bubble JSON as well — the format is detected from the content, not from the label.

Accepted extensions are `.json`, `.bubble` and `.sql`, up to 50 MB.

[[img:database-visualizer/01-entry-cards.png|The four ways in, plus the Postgres / SQL panel underneath.]]

## Reading the diagram

Colour tells you what a box is:

| Colour | Meaning |
|---|---|
| Blue | A data type |
| Orange | An option set |
| Gold | Bubble's built-in User |
| Grey | A deleted item |
| Red | A broken reference — `[Missing: …]` |
| Green | A new item you added in edit mode |

**Red boxes are the important ones.** A red `[Missing: X]` box means some field points at a type called `X` that does not exist in the file. Nothing errors when this happens; the placeholder box is the only signal. On an AI-generated schema it usually means a typo in a reference; see [the schema format](/docs/schema-format-for-ai).

Relationship lines are coloured by direction: green for outgoing, violet for incoming, red where two types reference each other both ways.

**Deleted items are hidden by default.** If a type you expected is missing, turn on *Show deleted* before assuming the export is wrong.

[[img:database-visualizer/02-graph.png|A real Bubble app: 142 data types and option sets with every relationship drawn between them.]]

Here is what a broken reference looks like. This schema has two: a field set to `custom.products` where the type is actually keyed `product`, and one set to `option.orderStatus` where the option set is keyed `order_status`. Both draw a red placeholder box, and both appear in the node list on the left alongside the real types they were meant to point at.

[[img:database-visualizer/03-missing-reference.png|Two red [Missing: …] boxes from a single plural and a single capital letter. Nothing about the file failed to load.]]

## Interacting

- **Pan and zoom** the canvas.
- **Click the chevron** on the left of a box to expand it and see its fields. Relationship lines then attach to the specific field row rather than to the header.
- **Click a box body** to select it and reveal what it links to.

[[img:database-visualizer/05-expanded-fields.png|Three boxes expanded. Each line now leaves the exact field it belongs to, so you can read Order's Items going to Order Item and its Watchers going to User without tracing anything by hand.]]
- **Click a reference field** to jump to the type it points at.
- **Drag** boxes to rearrange. Positions persist if you save the schema.
- **Search** to find a type by name.
- Large types cap at 15 visible field rows, with a **"+N more"** toggle to show the rest.

Selecting a type pulls it and everything it touches out of the crowd, and fills the right-hand panel with its fields, what it points at, and what points back at it.

[[img:database-visualizer/04-selected-node.png|One type selected out of 161. The panel lists each field with its raw value, the types it references, and the one type that references it.]]

## Getting things out

- **Download Schema** — the `{user_types, option_sets}` round-trip file. It opens a dialog first, where you choose Data Types and Option Sets, and whether to include privacy rules and deleted items. In scratch mode the button reads **Download Schema JSON** and downloads straight away with no dialog, merging in your unsaved additions.
- **Export as…** — Postgres SQL, Markdown, Prisma or Drizzle. See [export your schema](/docs/export-your-schema).
- **Copy for Bubble** — paste the whole schema into a real Bubble app. See [push a schema into Bubble](/docs/copy-for-bubble).
- **Save** — keep it on your account. See [saved schemas](/docs/save-and-reuse-schemas).

## Limits

- The diagram models `custom` and `option` references and their list forms. Bubble types like `date_range`, `numeric_range` and `date_interval` are drawn as plain values.
- Privacy rules are read but not visualised.
- The relationship model is one-to-one and one-to-many. Many-to-many is not inferred.

## If something goes wrong

[Upload errors, decoded](/docs/troubleshooting-uploads) lists every message. The most common one here is *"Invalid Bubble schema format. Expected user_types object."*, which means the file has no `user_types` key at the top level.