Schema Editor

A visual schema editor built into the Admin Dashboard for modifying edgebase.config.ts during development.

Dev Mode Only

The schema editor is available only when running npx edgebase dev. It is not available in production deployments. Production schema changes must be made directly in edgebase.config.ts and redeployed.

How It Works

The schema editor uses a CLI sidecar architecture. Since the Cloudflare Workers runtime (workerd) cannot access node:fs or AST manipulation libraries, the CLI process starts a separate HTTP server alongside wrangler dev to handle file system operations.

Dashboard UI ── POST /schema/tables ──> CLI Sidecar (:8788)
                                              │  ts-morph AST manipulation
                                              v
                                        edgebase.config.ts modified
                                              │  fs.watch detects change
                                              v
                                        wrangler auto-restarts

Architecture Components

Component	Location	Role
Config Editor	packages/cli/src/lib/config-editor.ts	Uses ts-morph to modify edgebase.config.ts via AST manipulation. Preserves comments, formatting, and function code (rules, hooks).
Sidecar Server	packages/cli/src/lib/dev-sidecar.ts	HTTP server with REST endpoints, Admin JWT verification, and CORS support.
Dev Info Endpoint	GET /admin/api/data/dev-info	Returns { devMode, sidecarPort } so the dashboard can auto-discover the sidecar.

Enabling the Schema Editor

The sidecar starts automatically when all of these conditions are met:

1. You are running npx edgebase dev
2. JWT_ADMIN_SECRET is set in .env.development
3. The sidecar port (default: 8788, which is the main dev server port + 1) is available

The CLI passes EDGEBASE_DEV_SIDECAR_PORT to the Worker via wrangler --var, so the Worker knows how to direct the dashboard to the sidecar.

What You Can Do

The schema editor provides a visual interface for all schema operations:

Tables

• Add a new table -- Creates a new table entry under the selected database block
• Edit a table -- Modify table settings (FTS fields, index configuration)
• Remove a table -- Removes the table definition from config

Fields

• Add a field -- Add a new column with type, default, constraints (required, unique, min, max, pattern)
• Edit a field -- Change field properties
• Remove a field -- Remove a column definition

Indexes

• Add an index -- Create single or composite indexes on table fields
• Remove an index -- Remove an existing index definition

Full-Text Search

• Enable FTS -- Specify which fields to include in FTS5 search
• Disable FTS -- Remove FTS configuration from a table

How Changes Are Applied

When you make a change in the schema editor:

1. The dashboard sends a REST request to the CLI sidecar (port :8788)
2. The sidecar uses ts-morph to parse edgebase.config.ts as an AST
3. The AST is navigated: default export -> defineConfig() -> databases -> {dbKey} -> tables -> {tableName} -> schema
4. The targeted node is modified while preserving all surrounding code (comments, rules, hooks)
5. The modified AST is written back to edgebase.config.ts
6. fs.watch detects the file change
7. wrangler dev auto-restarts with the new config
8. The Lazy Schema Init process applies the schema changes on the next request

Changes are reflected immediately -- there is no manual reload or restart needed.

Sidecar Security

The sidecar server enforces security:

• Admin JWT verification: Every request to the sidecar is authenticated using the same Admin JWT (HS256) as the main Admin Dashboard. The secret is read from .env.development.
• CORS: The sidecar allows cross-origin requests so the dashboard UI (served by the Worker on the main port) can communicate with the sidecar on a different port.
• Dev mode only: The sidecar is never started in production (edgebase deploy). It only runs during edgebase dev.

Dev Info Discovery

The dashboard auto-discovers the sidecar port by calling:

GET /admin/api/data/dev-info

Response:

{
  "devMode": true,
  "sidecarPort": 8788
}

When devMode is false (production), the schema editor UI is hidden entirely. When devMode is true, the dashboard uses sidecarPort to route schema editing requests to http://localhost:{sidecarPort}.

Limitations

• Dev mode only -- Not available in production. Schema changes in production require editing edgebase.config.ts and redeploying with npx edgebase deploy.
• Single developer -- The sidecar runs on the local machine. Concurrent edits from multiple developers on the same dev server are not supported.
• AST preservation -- While ts-morph preserves comments and formatting, extremely complex TypeScript expressions in the config file may occasionally require manual review after editing.
• No destructive migration generation -- The schema editor modifies the config file but does not auto-generate migration entries. If you rename or delete a column via the editor, you will need to manually add a migration entry in the migrations array. The CLI will prompt you about destructive changes on the next dev restart.