Plugin System & Custom Drivers

While Tabularis supports major relational databases natively via Rust, the ecosystem of data stores is vast. The Plugin System allows anyone to add support for external databases (like DuckDB, ClickHouse, or Redis) using any programming language.

This page explains how a plugin is structured and loaded. The rest of the plugin documentation:

• Installing Plugins — for users: the Plugin Center, updates and plugin settings.
• Plugin Protocol — the JSON-RPC methods a driver implements.
• Building Your First Plugin — scaffold a driver and implement it step by step.
• UI Extensions — add React components to the Tabularis interface.
• Publishing Plugins and Plugin Kinds — release a plugin to the registry.

Architecture: JSON-RPC over STDIO

Tabularis avoids dynamic linking (.so or .dll files) for plugins, which can cause version conflicts and security issues. Instead, plugins are standalone executables — a binary or a script — that run as child processes.

For each enabled plugin driver, Tabularis:

1. Spawns the plugin executable as a child process when the app starts (or when you enable the plugin in Settings).
2. Sends JSON-RPC 2.0 request objects to the plugin's stdin, one per line.
3. Reads JSON-RPC 2.0 response objects from the plugin's stdout, one per line.
4. Reuses that single process for every connection that uses the driver.

Output written to stderr is passed through to Tabularis's own standard error (visible when you launch the app from a terminal). It is not part of the protocol, so it is safe to use for debugging.

Directory Structure

A plugin is distributed as a .zip file per platform. Tabularis installs it into a folder named after the plugin id, grouped by kind:

plugins/
├── drivers/
│   └── duckdb/
│       ├── .tabularium      (or legacy manifest.json)
│       ├── duckdb-plugin    (or duckdb-plugin.exe on Windows)
│       ├── locales/         (optional, UI translations)
│       └── ui/dist/         (optional, UI extension bundles)
└── themes/
    └── my-theme/

Plugin folders placed directly under plugins/ (without the drivers/ level) are still loaded, so older manual installs keep working.

Plugin folder locations:

The Manifest (.tabularium)

Every plugin ships one manifest that tells Tabularis its capabilities and the data types it supports. Its canonical name is .tabularium — one file at the plugin root that serves both the host (loading the driver) and the Tabularium registry (listing it). The host still reads a legacy manifest.json as a fallback. With Tabularium 0.14.0 and Tabularis v0.25.0, a .tabularium may carry id as the stable lowercase identifier and name as the human-readable display name, which the connection catalogue shows for standalone plugins instead of title-casing the slug; manifests without id remain valid, and their name keeps acting as the identifier. When adopting the split, set id equal to the existing registry slug first, then change name. The registry-side fields are listed in Publishing Plugins and, per kind, in Plugin Kinds.

{
  "$schema": "https://registry.tabularis.dev/manifest.schema.json?kind=driver",
  "name": "duckdb",
  "version": "1.0.0",
  "description": "DuckDB file-based analytical database",
  "default_port": null,
  "executable": "duckdb-plugin",
  "capabilities": {
    "schemas": false,
    "views": true,
    "routines": false,
    "file_based": true,
    "identifier_quote": "\"",
    "alter_primary_key": false
  },
  "data_types": [
    { "name": "INTEGER",  "category": "numeric", "requires_length": false, "requires_precision": false },
    { "name": "VARCHAR",  "category": "string",  "requires_length": true,  "requires_precision": false },
    { "name": "BOOLEAN",  "category": "other",   "requires_length": false, "requires_precision": false },
    { "name": "TIMESTAMP","category": "date",    "requires_length": false, "requires_precision": false }
  ]
}

Capabilities

When the manifest includes a capabilities object, schemas, views, routines and file_based are required; the other flags fall back to the defaults listed above.

Declaring the SQL dialect

Always set sql_dialect to the closest preset. A plugin that declares no dialect, or only generic, still loads, but the host cannot know how its SQL is tokenized and assumes the worst: the AI/MCP read-only check lexes every query under every preset and rejects reads they disagree on (a # outside a string, a backslash in a string literal, $$ bodies, and similar), and generated SQL (filters, dumps, notebook cell CTEs, Copy as INSERT) falls back to standard quoting. Since v0.29.0 the Copy SQL Without Comments editor action is also hidden for such drivers.

SQL Syntax (sql_syntax)

Since v0.29.0, a driver whose engine lexes SQL differently from every preset (GoogleSQL's triple-quoted strings, # comments and procedural scripts, for example) can describe the difference in capabilities.sql_syntax. It is data only; the host never runs code from it. extends names the preset to start from (it defaults to sql_dialect), and every other field overrides one rule of that preset:

The statement splitter, Format SQL, autocomplete, the filter bar, Copy as INSERT, imports, dumps, notebook literals and the MCP read-only check all read it. For the read-only check a declared syntax adds a tokenization pass, so it can make the check stricter, never looser. An invalid field is logged and ignored, unknown fields are ignored, and hosts that predate sql_syntax keep using sql_dialect, so keep sql_dialect set to the closest preset (e.g. mysql for GoogleSQL). Connection metadata cannot override it. The full field reference, with the GoogleSQL descriptor of the BigQuery driver as an example, is in the plugin guide.

Connection Fields

Since v0.29.0 the optional manifest object connection_fields adapts the host's connection inputs to a driver that does not use them as-is. Each of host, port, username, password and database accepts hidden (boolean), label (up to 80 characters) and placeholder (up to 200 characters):

{
  "connection_fields": {
    "host": { "hidden": true },
    "port": { "hidden": true },
    "username": { "hidden": true },
    "password": { "hidden": true },
    "database": { "label": "Project ID", "placeholder": "billing-project" }
  }
}

Overrides are presentation only: a hidden input is not rendered, but a value already saved for it is kept and still sent to the driver. A hidden database is not required on Test Connection or Save, and hiding host also hides Load Databases. Collect what the driver needs instead through the connection-modal.extra_fields UI extension, with setSecretField for credentials, which are kept in the OS keychain.

Data Type Categories

Type Mappings

The optional type_mappings manifest field declares how generic inferred type names map to driver-native types. It is used during paste/import, where Tabularis infers column types from the data (e.g. detects a date column as DATETIME) and needs the driver-native equivalent. The mapping is static in the manifest and resolved by the host — no RPC round-trip.

{
  "type_mappings": {
    "DATETIME": "TIMESTAMP",
    "JSON": "JSONB"
  }
}

Keys are uppercase generic type names; the lookup is case-insensitive. Types without a mapping (or an omitted type_mappings) pass through unchanged.

@tabularis/create-plugin scaffolds the .tabularium manifest directly and ships a migrate command that converts an existing legacy manifest.json plugin (and, with --ci, regenerates a registry-ready release workflow).

Plugin Settings

Plugins can declare configuration fields that Tabularis renders in Settings → gear icon next to the plugin; the values are persisted in config.json and delivered to the plugin through the initialize call. For the user side, including the per-plugin call timeout, see Plugin Settings.

Declaring settings in the manifest

Add an optional settings array to your manifest:

{
  "name": "my-plugin",
  "settings": [
    {
      "key": "api_key",
      "label": "API Key",
      "type": "string",
      "required": true,
      "description": "Your API key for authentication."
    },
    {
      "key": "region",
      "label": "Region",
      "type": "select",
      "options": ["us-east-1", "eu-west-1"],
      "default": "us-east-1"
    },
    {
      "key": "max_connections",
      "label": "Max Connections",
      "type": "number",
      "default": 10
    },
    {
      "key": "ssl",
      "label": "Enable SSL",
      "type": "boolean",
      "default": true
    }
  ]
}

Supported setting types: "string", "boolean", "number", "select".

The initialize call

Tabularis sends an initialize JSON-RPC call with the user's saved settings just before the first real request to the plugin, not at spawn time. Other requests wait for it to finish (up to 15 seconds):

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": { "settings": { "api_key": "abc", "region": "eu-west-1" } },
  "id": 1
}

Returning an error from initialize is safe — Tabularis logs a warning and carries on. Plugins that do not implement initialize are completely unaffected.

Plugin settings are stored under the top-level plugins key in config.json, keyed by plugin ID.

For the full developer reference (field schema, code examples in Rust and Python), see the Plugin Guide.

Testing Your Plugin

You can test your plugin directly from the shell before installing it in Tabularis:

echo '{"jsonrpc":"2.0","method":"test_connection","params":{"params":{"driver":"duckdb","database":"/tmp/test.duckdb","host":null,"port":null,"username":null,"password":null,"ssl_mode":null}},"id":1}' \
  | ./duckdb-plugin

You should see a valid JSON-RPC response on stdout.

Installing Locally

1. Create the plugin directory inside the Tabularis plugins folder, for example on Linux:

   ~/.local/share/tabularis/plugins/drivers/myplugin/
   

2. Place your .tabularium (or legacy manifest.json) and the compiled executable there, plus ui/dist/ and locales/ if the plugin has UI extensions.
3. On Linux/macOS, make it executable: chmod +x myplugin
4. Restart Tabularis, or enable the plugin in Settings → Plugins. Once you have saved a list of enabled plugins, a folder copied in by hand stays disabled until you turn it on there.

A project scaffolded with @tabularis/create-plugin handles steps 1–3 with just dev-install, which copies the executable, .tabularium and ui/dist/index.js. Copy locales/ yourself if the plugin has translations.