Plugin API

Status: Experimental

An exporter is a pure function that converts a TitanSchema into target-specific output: schema in, files out, no side effects. This is the easiest way to extend Titanbase.

Warning

The exporter contract is experimental. There is no formal ExportPlugin registration interface yet — exporters are plain functions — and the shared ExportResult shape may still change. Treat this as an internal contract and expect breaking changes; pin your dependency versions. Importer, diff, and CLI plugin APIs do not exist yet.

The contract#

Today, an exporter is a function that takes a TitanSchema and returns results. Most exporters use the shared ExportResult type from @titanbase/core:

import type { TitanSchema, ExportResult, ExportWarning } from "@titanbase/core";

export function exportMyTarget(schema: TitanSchema): ExportResult {
  const warnings: ExportWarning[] = [];

  const content = schema.tables
    .map((table) => `-- ${table.name}`)
    .join("\n");

  return {
    files: [{ path: "schema.txt", content }],
    warnings,
  };
}

The shared result types are:

interface ExportFile {
  path: string;
  content: string;
}

interface ExportWarning {
  code: string;
  message: string;
  path?: string;
}

interface ExportResult {
  files: ExportFile[];
  warnings: ExportWarning[];
}

Note

The built-in PostgreSQL exporter currently returns a different shape — { sql: string; warnings: string[] } — for historical reasons. New exporters should prefer the shared ExportResult shape used by the Mermaid, Prisma, and Drizzle exporters.

Responsibilities#

A well-behaved exporter handles:

Type mapping — map each column's type (and nativeType) to a target type, with a safe fallback.
Output generation — produce the DDL, schema code, or diagram for the target.
Constraints — primary keys, unique constraints, foreign keys, and indexes where the target supports them.
Defaults — translate the column default string into the target's syntax where possible.
Warnings — emit a warning (rather than failing) when the target can't represent a feature, and choose a safe fallback.

Look to the existing exporter packages (@titanbase/export-mermaid, @titanbase/export-prisma, @titanbase/export-drizzle) as reference implementations.

Determinism and safety#

Be a pure function: same schema in, same output out. No network calls, no global state.
Quote or sanitize identifiers for the target so generated output is always valid.
Never throw on a recoverable problem — skip the affected object and add a warning so the rest of the output stays usable.

Distribute it#

An exporter is a standalone package. Until the contract stabilizes, keep it pinned to a specific @titanbase/core version. Ready to contribute it upstream? See Contributing.