New to plugins? Start with
PLUGIN_TUTORIAL.md— a 20-minute walkthrough that ends with a working Google Sheets driver. This document is a reference, not a tutorial.📚 The canonical, browsable version of the plugin docs lives at tabularis.dev/wiki/plugins.
Tabularis supports extending its capabilities via a JSON-RPC based external plugin system. By building a standalone executable that implements the JSON-RPC interface, you can add support for virtually any SQL or NoSQL database (such as DuckDB, MongoDB, etc.) using the programming language of your choice.
This guide details how to implement and register a custom external plugin.
AI providers use a separate, declarative ai-assistant package contract. See the
AI assistant package guide; those packages contain
HTTP templates and JSON selectors and do not use the executable driver protocol.
Native routine debugging is an optional, versioned capability. See
Routine debugger protocol v1 for the RPC, lifecycle,
write protections and required native integration evidence.
Implement stop for unused native preview IDs as well as execution session IDs,
so closing or expiring a preview discards its saved state without execution.
Plugins that connect to more than one database engine can opt in to connection metadata discovery to report capabilities and data types for each connection. Existing plugins keep their static manifests.
An external plugin in Tabularis is a separate executable (binary or script) that runs alongside the main application. Tabularis communicates with the plugin using JSON-RPC 2.0 over standard input/output (stdin / stdout).
- Requests: Tabularis writes JSON-RPC request objects to the plugin's
stdin, separated by a newline (\n). - Responses: The plugin processes the request and writes a JSON-RPC response object to its
stdout, followed by a newline (\n). - Logging: Any output to
stderrfrom the plugin is inherited/logged by Tabularis without interfering with the JSON-RPC communication.
The request-level schema field holds the item selected in the explorer.
For plugins with capabilities.schemas: false, a connection can also have
params.database: ["0", "3"] (Redis is one example). When schema is an
exact member of that array, the host sends only the selected database as
params.database: "3" for that RPC. Other parameters and the request's
schema stay unchanged.
For plugins with capabilities.schemas: true, the host does not rewrite
params.database. A schema can have the same name as a database, and the
plugin must use schema to select the namespace within its database.
Single-database values and requests with no matching selection are unchanged.
For plugins with capabilities.schemas: false, a connection saved with All
databases selects none: the host lists them with get_databases when it
connects, and schema names the one the explorer is on. params.database is
then the connection's default_database when the plugin asks for one (see
Connection Fields), and empty otherwise.
- Tabularis discovers plugins in its data folder at startup:
- Linux:
~/.local/share/tabularis/plugins/ - macOS:
~/Library/Application Support/tabularis/plugins/ - Windows:
%APPDATA%\tabularis\plugins\
- Linux:
- It reads each plugin's
.tabulariummanifest (or a legacymanifest.json) to discover its capabilities and data types. - The plugin is registered as a driver and appears in the "Database Type" list.
- Tabularis spawns the executable when it registers the driver, and sends JSON-RPC messages once a connection uses it. The desktop app and each
tabularis --mcpserver start their own process. - The same process instance is reused for all connections and operations in that session.
- When the session ends, Tabularis kills the process. Exit when
stdinreaches EOF as well: if Tabularis is killed (for example an MCP client force-quittingtabularis --mcp), EOF may be the only signal the plugin gets. On Windows, Tabularis also places the plugin in a job object that is killed with it.
A Tabularis plugin is distributed as a .zip file. When extracted into the plugins folder, it must have the following structure:
plugins/
└── drivers/
└── duckdb/
├── .tabularium (or legacy manifest.json)
└── duckdb-plugin (or duckdb-plugin.exe on Windows)
Installations and updates always use plugins/<kind-folder>/<name>/, mapping theme to themes, driver to drivers, and otherwise keeping the kind unchanged. Legacy or manually copied plugins/<name>/ bundles are a discovery fallback; the kind-scoped copy wins. An absent manifest kind means driver; declarative themes use theme and are never started as drivers.
One manifest tells Tabularis everything about your plugin — and, when you publish, tells the Tabularium registry how to list it. Its canonical name is .tabularium; the host still reads a legacy manifest.json as a fallback. With Tabularium 0.14.0+, use id as the stable lowercase identifier and name as the human-readable display name. Existing manifests without id remain supported: their name continues to supply the identifier. When publishing, the registry resolves the manifest from your release assets — upload .tabularium as a standalone asset (GitHub silently renames the dotfile to default.tabularium; the registry accepts both names).
JSON Schema available: point
$schemaat the registry's live merged schema (as below) for IDE autocompletion and validation, or at the localplugins/manifest.schema.jsonfor legacymanifest.jsonfiles.
{
"$schema": "https://registry.tabularis.dev/manifest.schema.json?kind=driver",
"id": "duckdb",
"name": "DuckDB",
"kind": "driver",
"engine": "duckdb",
"paradigms": ["sql"],
"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,
"connection_string": false,
"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
}
]
}| Field | Type | Description |
|---|---|---|
name |
string | Human-readable display name (e.g., "SQLite JDBC", 1–120 characters). Without id, this remains the legacy lowercase identifier (1–64 characters). |
id |
string | Stable identifier used in saved connections, the plugin folder and registry URLs; 1–64 characters matching ^[a-z][a-z0-9-]*$. Recommended for new manifests. Must equal the existing registry slug when migrating. |
engine |
string | Shared database engine (e.g., "sqlite" for "jdbc-sqlite"). Groups alternative drivers under the same engine; omit only when the plugin should form its own group. |
version |
string | Plugin version (semver, no leading v). Must equal the release tag with any v prefix stripped — the registry rejects tag/manifest mismatches. |
description |
string | Short description shown in the plugins list. Optional for the registry; max 280 chars. |
default_port |
number | null | Default TCP port. Use null for file-based databases. |
default_username |
string | Optional username pre-filled in the connection modal for a new connection (e.g. "root"). |
executable |
string | Relative path to the executable inside the plugin folder. |
capabilities |
object | Feature flags (see below). |
data_types |
array | List of supported data types (see below). |
type_mappings |
object | null | Optional map of generic inferred type names to driver-specific types. Used during paste/import to map generic types (e.g. DATETIME) to driver-native equivalents (e.g. TIMESTAMP). See Type Mappings below. |
connection_fields |
object | Optional hide, label, and placeholder overrides for the common host, port, username, password, and database fields. Omitted fields preserve the standard UI. See Connection Fields below. |
Upgrade the registry before publishing the new format. Add id equal to the existing registry slug, then change name to the display name. Do not rename installed-plugin folders, saved driver IDs or registry entries, and do not rewrite historical release archives. For JDBC, use id: "jdbc-sqlite", name: "SQLite JDBC", engine: "sqlite" in both the source manifest and generator. Known/shared engine cards retain their engine title; standalone plugin cards use the display name.
| Flag | Type | Description |
|---|---|---|
schemas |
bool | true if the database supports named schemas (like PostgreSQL). Controls whether the schema selector is shown in the UI. |
views |
bool | true if the database supports views. Enables the views section in the explorer. |
materialized_views |
bool | true if the database supports materialized views. Enables the materialized views section in the explorer (see Materialized Views). Defaults to false. |
routines |
bool | true if the database supports stored procedures/functions. |
triggers |
bool | true if the database supports triggers. Enables trigger-related UI for drivers that implement the trigger RPCs. |
file_based |
bool | true for local file databases (e.g., SQLite, DuckDB). Replaces host/port with a file path input in the connection form. |
in_memory |
bool | Requires file_based. true if the driver also opens the path :memory: as a temporary database (e.g. DuckDB). Adds an in-memory shortcut next to the file path input and skips the file existence check for that path. The database lives in the plugin process: connections that use :memory: share it until the plugin process stops. Also accepted as camelCase inMemory. Defaults to false. |
folder_based |
bool | true for plugins that connect to a directory rather than a single file (e.g. CSV plugin). Replaces host/port with a folder picker. |
no_connection_required |
bool | true for API-based plugins that need no host, port, or credentials (e.g. a public REST API). Hides the entire connection form — the user only fills in the connection name. |
connection_string |
bool | Set false to hide the connection string import UI for this driver. Defaults to true for network drivers. file_based and folder_based drivers skip the import UI automatically regardless of this flag. |
connection_string_example |
string | Optional placeholder example shown in the connection string import field (e.g. "clickhouse://user:pass@localhost:9000/db"). Also accepted as camelCase connectionStringExample. |
connection_string_examples |
array | Optional connection string presets shown beside the import field. Each item has a required label and value, plus an optional description. Selecting one fills the field; connection_string_example remains the placeholder. Also accepted as camelCase connectionStringExamples. |
identifier_quote |
string | Character used to quote SQL identifiers. Use "\"" for ANSI standard or "`" for MySQL style. |
serial_type |
string | Replacement data type for auto-increment columns in generated DDL (e.g. "SERIAL" for PostgreSQL). Empty if not applicable. When set to "SERIAL", the host widens it to match the column's integer width: smallint → SMALLSERIAL, integer → SERIAL, bigint → BIGSERIAL. Plugins whose serial syntax is not width-tied should use a distinct literal (e.g. "BIGINT GENERATED BY DEFAULT AS IDENTITY") to avoid widening. |
data_files |
string[] | Requires file_based. Data file formats (csv, tsv, json, ndjson, parquet, xlsx) the driver exposes as a queryable relation through the optional open_data_file RPC. Open data file uses the first registered driver that declares the file's format. Also accepted as camelCase dataFiles. Defaults to []. See Data Files. |
table_query_templates |
bool | Opts the Generate SQL dialog into the optional get_table_query_template RPC for SELECT/UPDATE/DELETE previews. Defaults to false; older plugins and built-in drivers keep the existing host templates. See Table Query Templates. |
column_comments |
bool | The DDL generation RPCs honour ColumnDefinition.comment (for example OPTIONS(description=...) or a COMMENT clause), so the column editor shows a description field. Defaults to false; the field is hidden otherwise and comment is omitted from requests when unset. |
column_stats |
bool | Opts the data grid's Column statistics popover into the optional get_column_stats RPC. Defaults to false: plugins whose sql_syntax.extends or sql_dialect is postgres, mysql or sqlite keep the host's generic SQL, and the others don't show the menu entry. See Column Statistics. |
query_classification |
bool | Opts the read-only policies (the MCP read-only mode, the MCP approval gate and saved read-only connections) into the optional classify_query RPC, so a driver whose query language is not SQL can say whether a query only reads. Defaults to false: the host reads every query as SQL, which is wrong for a non-SQL language (a plain read usually comes out unknown: blocked in read-only mode and needing approval). A select verdict only counts together with read_only_queries (or readonly). See Query Classification. |
drop_table_sql |
bool | Opts the explorer's Drop table action into the optional get_drop_table_sql RPC, so the plugin can return its own statement (for example DROP SNAPSHOT TABLE). Defaults to false: the RPC is never called and the host runs a generic DROP TABLE with your identifier_quote. See get_drop_table_sql. |
sql_dialect |
string | Optional SQL dialect preset: postgres, mysql, mssql, sqlite, oracle, or generic. Drives statement splitting, the AI/MCP read-only check, generated SQL and literals. A driver whose query language is not SQL declares query_classification instead of relying on the read-only check (see Query Classification). Oracle-like plugins, including DM/Dameng, should use "oracle". A host loads a dialect it doesn't know as generic and logs a warning. For an engine no preset describes, keep the closest preset here and declare sql_syntax. |
sql_syntax |
object | Optional declarative SQL syntax that extends a preset: quotes, comments, triple-quoted and prefixed strings, procedural blocks, string and boolean literals, LIKE … ESCAPE, formatter and autocomplete words. Hosts that predate it ignore it and use sql_dialect. See SQL Syntax. |
alter_primary_key |
bool | true if the database supports altering primary keys after table creation. |
manage_tables |
bool | true to enable table and column management UI (Create Table, Add/Modify/Drop Column, Drop Table). Does not control index or FK operations. Defaults to true. |
readonly |
bool | When true, the driver is read-only: all data modification operations (INSERT, UPDATE, DELETE) are disabled in the UI. The add/delete row buttons, inline cell editing, and context menu edit actions are hidden. Table and column management is also hidden regardless of manage_tables. Defaults to false. |
read_only_queries |
bool | Implements the optional database-enforced execute_read_only_query RPC, allowing users to enable read-only mode per connection. Defaults to false. See Optional protected read-only queries. |
table_export |
bool | Offers Export table to SQL... on table nodes. Defaults to true; set false for non-SQL plugins. See Table Export and Import. |
table_import |
bool | Offers Import table from SQL... on database and schema nodes. Defaults to true; set false for non-SQL plugins. Always off when readonly is true. |
explain |
bool | true if the driver implements the explain_query method (EXPLAIN / query plan support). Enables the Visual EXPLAIN button in the SQL editor and notebook cells; when false or omitted, the Visual EXPLAIN UI is hidden for connections using this driver. Defaults to false. |
supports_ssl |
bool | true to show the SSL/TLS configuration tab (mode + CA/client cert/key) in the connection modal. The values are forwarded to the plugin as ssl_mode, ssl_ca, ssl_cert, and ssl_key in ConnectionParams. Network drivers only. Also accepted as camelCase supportsSsl. Defaults to false. |
query_timeout |
bool | true when the driver honours query_timeout_secs — stops a statement on the server once the limit passes. Shows the query-timeout field in the connection modal. Built-in PostgreSQL and MySQL set this; plugins that can cancel a running statement should opt in. Defaults to false. |
socks5_proxy |
bool | true when the driver sends every database connection through the SOCKS5 proxy the host passes in socks5_proxy_host / socks5_proxy_port (and socks5_proxy_username / socks5_proxy_password when set). With SSH enabled, the host then opens a dynamic forward instead of rewriting host / port, so a connection that names several endpoints (an SRV seedlist, a replica set) reaches all of them. Also accepted as camelCase socks5Proxy. Defaults to false. See SSH Tunnels through a SOCKS5 Proxy. |
For drivers with several URL forms, declare the single example as the placeholder and add selectable presets:
For URI passthrough drivers, an opaque placeholder (such as jdbc:h2:mem:test) permits opaque inputs. An authority-based placeholder (such as mongodb://localhost/db) requires :// and a host in imported strings.
{
"connection_string_example": "jdbc:h2:tcp://localhost/~/test",
"connection_string_examples": [
{ "label": "In-memory", "value": "jdbc:h2:mem:test", "description": "A named in-memory database." },
{ "label": "Local file", "value": "jdbc:h2:./data/test" },
{ "label": "TCP server", "value": "jdbc:h2:tcp://localhost/~/test" }
]
}Writable drivers can opt in to the connection's Read-only mode by declaring
capabilities.read_only_queries: true. This is distinct from readonly: true,
which describes a driver that is always read-only. The default is false: older
plugins continue working, but cannot enable this connection policy.
Implement the execute_read_only_query JSON-RPC method. Its request and response
have the same shape as execute_query (a bare QueryResult response):
{
"jsonrpc": "2.0",
"id": 42,
"method": "execute_read_only_query",
"params": {
"params": {"driver": "example", "database": "analytics", "read_only": true},
"query": "SELECT * FROM items",
"limit": 100,
"page": 1,
"schema": null
}
}The host preflights the SQL using the declared dialect (a driver whose query
language is not SQL declares query_classification and the preflight uses the
driver's own verdict, see Query Classification), but a
keyword filter cannot detect side effects in stored functions. The plugin must enforce write
protection using its database's transaction, session or equivalent mechanism,
including for calls whose SQL looks like a read. If protection cannot be enabled,
return an error. An unsupported method, timeout or protection failure never falls
back to execute_query. Restore or discard the physical connection on every
success, error and cancellation path; protection must not leak to writable users.
ConnectionParams.read_only is persisted per connection and forwarded to all
driver calls, including connection testing and metadata discovery. The host omits
the saved startup_script while it is enabled. Plugins must also ensure their
own initialization and metadata operations cannot write in this mode. A driver
that loses the capability must refuse protected execution until the user updates
the plugin or explicitly disables the policy.
Read-only batches are preflighted in full, then each statement uses the protected
RPC independently. Explicit transaction/session-control statements are refused;
connection-local state is not shared between these calls. Visual EXPLAIN is
unavailable because its separate RPC has no protected execution contract; raw
EXPLAIN statements can use the protected query RPC. Existing readonly drivers
continue using their normal execution method and need no new RPC.
Always set sql_dialect to the closest preset, and add sql_syntax when no preset describes your engine. A plugin that declares neither (or only generic) still loads, but the host can't know how its SQL is tokenized, so it assumes the worst:
- AI/MCP read-only check. Without a dialect, every query is lexed under every preset's rules, and it only counts as a single read statement when all of them agree. Reads that some dialect tokenizes differently are rejected as possibly unsafe (
unknownor a write), for example queries containing:- a
#outside a string (a comment in MySQL, an operator such as#>in PostgreSQL); - a backslash inside a string literal (
'C:\temp','it\'s'), which only some dialects treat as an escape; - double-quoted or backtick-quoted text whose meaning differs (a string in MySQL, an identifier elsewhere), or
[bracketed]identifiers; $$/$tag$dollar-quoted bodies,E'…'strings, nested/* /* */ */comments or/*! … */executable comments;--not followed by a space (1--1is arithmetic in MySQL);- a
;that any dialect reads as a statement separator, even inside what your engine treats as a string or comment.
- a
- Generated SQL and literals. Filters, dumps, notebook cell CTEs and Copy as INSERT fall back to standard quoting (
'doubled, backslashes left as is), and dumps write booleans as1/0. On an engine where\is an escape character this is wrong, so declaremysql(orsql_syntax.string_escape) there; on one that rejects1/0for a boolean column, declaresql_syntax.boolean_literals.
sql_dialect picks one of the host's presets. When your engine lexes SQL differently from all of them (GoogleSQL's triple-quoted strings, # comments and procedural scripts, for example), describe the difference in capabilities.sql_syntax. It is data only: the host never runs code from it.
extendsnames the preset to start from. It defaults tosql_dialect, so most plugins set it explicitly whensql_dialectis only a fallback for older hosts.- Every other field is optional and overrides one rule of that preset. Leave a field out to keep the preset's rule.
- Older hosts ignore
sql_syntaxand keep usingsql_dialect, so setsql_dialectto the closest preset (e.g."mysql"for GoogleSQL: backticks,#comments, backslash escapes). - An invalid field is logged and ignored (the preset's rule stays); the plugin always loads. Unknown fields are ignored too, so newer descriptors work on this host.
- Without
sql_syntax, a driver behaves exactly as before.
| Field | Type | Default | Meaning |
|---|---|---|---|
extends |
string | sql_dialect |
Preset to extend: postgres, mysql, mssql, sqlite, oracle or generic. Any other value is ignored. |
quotes |
array | preset | Replaces the quote rules. 1 to 8 objects with a unique open: { "open", "close"?, "kind", "escape"? }. open is ', ", ` or [; close defaults to (and must equal) open, or ] for [. kind is "string" or "identifier". escape is "double" ('', default), "backslash" (\', no doubling), "both" or "none". |
triple_quoted_strings |
bool | false |
'''…''' and """…""" strings that may span lines, for the ' and " quotes of kind string. Escapes follow that quote's rule. |
string_prefixes |
string[] | [] |
Letter prefixes accepted before a string quote or triple quote, any case (e.g. r, b, rb, br). At most 8, each 1 or 2 ASCII letters. A raw r prefix keeps a backslash as text, but with a backslash escape the backslash still pairs with the next character, so r'\'' is one literal. |
hash_comments |
bool | preset (mysql: true) |
# starts a line comment. |
nested_block_comments |
bool | preset (postgres, mssql: true) |
/* … */ comments nest. |
line_comment_requires_space |
bool | preset (mysql: true) |
-- only starts a comment when followed by whitespace (1--1 is arithmetic). |
script_blocks |
bool | false |
Procedural blocks stay one statement: BEGIN … END (not BEGIN TRANSACTION), EXCEPTION WHEN ERROR THEN, IF … END IF, LOOP, WHILE, REPEAT, FOR … DO, CASE … END CASE, labels and CREATE PROCEDURE bodies. |
psql_blocks |
bool | false |
Firebird PSQL: preserve declarations and nested BEGIN/CASE blocks in procedures, functions, triggers, packages and EXECUTE BLOCK. Enable alternative q-quotes and consume standalone isql SET TERM directives. Ordinary transaction statements remain separate. Requires a host and registry schema supporting this field. |
dollar_quoting |
bool | preset (postgres: true) |
$tag$ … $tag$ strings. |
string_escape |
string | preset (mysql: doubled quote plus doubled backslash; others: "standard") |
How the host writes string literals in filters, foreign-key filters, Copy as INSERT / IN list, clipboard import, dumps and notebook cell CTEs: "standard" ('it''s') or "backslash" ('it\'s', with \\, NUL (\0), \n and \r escaped too). On a mysql base (extends: "mysql", or sql_dialect: "mysql" without extends) "standard" is ignored with a warning, since the engine still reads \ as an escape character; "backslash" is allowed. |
like_escape |
bool | true |
Whether LIKE … ESCAPE '!' is supported. With false, literal LIKE filters escape %, _ and \ with a backslash (the engine's default LIKE escape) and omit ESCAPE. |
boolean_literals |
string | each generator's default (dumps: TRUE/FALSE on postgres, 1/0 elsewhere; Copy as INSERT and filters: TRUE/FALSE; notebook cell CTEs: 'true') |
How the host writes boolean values in SQL it generates: "keywords" (TRUE / FALSE) or "numeric" (1 / 0). Applies to dumps, Copy as INSERT / IN list, foreign-key and cell-value filters, filters on BOOL / BOOLEAN columns (true, false, 1, 0), notebook cell CTEs and the BOOLEAN columns a clipboard import creates. Declare "keywords" when the engine has no implicit integer-to-boolean coercion (GoogleSQL rejects 1 for a BOOL column). Any other value is ignored. |
formatter |
string | preset | sql-formatter language for Format SQL: bigquery, clickhouse, db2, db2i, duckdb, hive, mariadb, mysql, n1ql, plsql, postgresql, redshift, singlestoredb, snowflake, spark, sql, sqlite, tidb, transactsql or trino. |
keywords |
string[] | [] |
Extra autocomplete keywords. At most 1000 entries of up to 64 characters: an ASCII letter or _, then letters, digits, _, $, . or single inner spaces ("FOR SYSTEM_TIME AS OF", "SAFE."). |
functions |
string[] | [] |
Extra autocomplete function names, same limits as keywords. |
Rules a descriptor can't change come from the preset it extends: E'…' strings (postgres), DELIMITER and /*! … */ executable comments (mysql), GO batches (mssql), / terminators, PL/SQL blocks and q'[…]' quotes (oracle). Extend generic to start from none of them.
For the AI/MCP read-only check, a declared syntax adds one tokenization pass to the passes of sql_dialect (every pass, for generic, oracle or no dialect). A query counts as a single read only when every pass agrees, so a descriptor can make the check stricter, never looser. A literal the fallback dialect reads differently, such as '''it's; ok''' with a mysql fallback, is treated as possibly unsafe.
sql_syntax comes from the manifest only; connection metadata cannot override it. When metadata overrides sql_dialect, a descriptor without extends extends the overridden dialect.
The GoogleSQL descriptor of a BigQuery driver, with "sql_dialect": "mysql" as the fallback for older hosts:
{
"extends": "generic",
"quotes": [
{"open": "'", "kind": "string", "escape": "backslash"},
{"open": "\"", "kind": "string", "escape": "backslash"},
{"open": "`", "kind": "identifier", "escape": "backslash"}
],
"triple_quoted_strings": true,
"string_prefixes": ["r", "b", "rb", "br"],
"hash_comments": true,
"nested_block_comments": false,
"line_comment_requires_space": false,
"script_blocks": true,
"dollar_quoting": false,
"string_escape": "backslash",
"like_escape": false,
"boolean_literals": "keywords",
"formatter": "bigquery",
"keywords": [
"QUALIFY", "PIVOT", "UNPIVOT", "TABLESAMPLE SYSTEM", "UNNEST",
"WITH OFFSET", "EXCEPT", "REPLACE", "WINDOW", "OVER", "PARTITION BY",
"CLUSTER BY", "OPTIONS", "FOR SYSTEM_TIME AS OF", "IGNORE NULLS",
"RESPECT NULLS", "UNION ALL", "UNION DISTINCT", "INTERSECT DISTINCT",
"EXCEPT DISTINCT", "MERGE", "WHEN MATCHED", "WHEN NOT MATCHED",
"WHEN NOT MATCHED BY SOURCE", "CREATE OR REPLACE TABLE",
"CREATE TEMP TABLE", "CREATE TEMP FUNCTION",
"CREATE OR REPLACE PROCEDURE", "CREATE SCHEMA", "RETURNS", "LANGUAGE js",
"EXPORT DATA", "LOAD DATA", "ASSERT", "DECLARE", "BEGIN",
"BEGIN TRANSACTION", "COMMIT TRANSACTION", "ROLLBACK TRANSACTION",
"EXCEPTION WHEN ERROR THEN", "ELSEIF", "END IF", "LOOP", "END LOOP",
"WHILE", "END WHILE", "REPEAT", "UNTIL", "END REPEAT", "FOR", "DO",
"END FOR", "END CASE", "LEAVE", "BREAK", "CONTINUE", "ITERATE", "RETURN",
"CALL", "EXECUTE IMMEDIATE", "RAISE USING MESSAGE", "INT64", "FLOAT64",
"NUMERIC", "BIGNUMERIC", "BOOL", "STRING", "BYTES", "DATE", "DATETIME",
"TIME", "TIMESTAMP", "INTERVAL", "GEOGRAPHY", "JSON", "STRUCT", "ARRAY",
"RANGE"
],
"functions": [
"SAFE_CAST", "SAFE.", "SAFE_DIVIDE", "IF", "IFNULL", "COALESCE",
"NULLIF", "COUNTIF", "ARRAY_AGG", "STRING_AGG", "LOGICAL_AND",
"LOGICAL_OR", "ANY_VALUE", "APPROX_COUNT_DISTINCT", "APPROX_QUANTILES",
"APPROX_TOP_COUNT", "APPROX_TOP_SUM", "ROW_NUMBER", "RANK", "DENSE_RANK",
"LAG", "LEAD", "FIRST_VALUE", "LAST_VALUE", "NTILE", "PERCENTILE_CONT",
"ARRAY_LENGTH", "ARRAY_CONCAT", "ARRAY_TO_STRING", "GENERATE_ARRAY",
"GENERATE_DATE_ARRAY", "SPLIT", "FORMAT", "STARTS_WITH", "ENDS_WITH",
"CONTAINS_SUBSTR", "REGEXP_CONTAINS", "REGEXP_EXTRACT",
"REGEXP_EXTRACT_ALL", "REGEXP_REPLACE", "REGEXP_INSTR",
"FARM_FINGERPRINT", "GENERATE_UUID", "JSON_VALUE", "JSON_QUERY",
"JSON_VALUE_ARRAY", "JSON_QUERY_ARRAY", "JSON_EXTRACT",
"JSON_EXTRACT_SCALAR", "PARSE_JSON", "TO_JSON", "TO_JSON_STRING",
"CURRENT_DATE", "CURRENT_DATETIME", "CURRENT_TIMESTAMP", "EXTRACT",
"DATE_TRUNC", "DATE_ADD", "DATE_SUB", "DATE_DIFF", "DATETIME_TRUNC",
"DATETIME_DIFF", "TIMESTAMP_TRUNC", "TIMESTAMP_ADD", "TIMESTAMP_SUB",
"TIMESTAMP_DIFF", "FORMAT_DATE", "FORMAT_TIMESTAMP", "PARSE_DATE",
"PARSE_TIMESTAMP", "UNIX_SECONDS", "UNIX_MILLIS", "TIMESTAMP_SECONDS",
"TIMESTAMP_MILLIS", "LAST_DAY", "ST_GEOGPOINT", "ST_GEOGFROMTEXT",
"ST_ASTEXT", "ST_DISTANCE", "ST_DWITHIN", "ST_CONTAINS", "ST_INTERSECTS",
"ST_AREA", "ST_LENGTH", "ST_BUFFER"
]
}Each entry in data_types describes a type the driver supports for column creation in the UI:
| Field | Type | Description |
|---|---|---|
name |
string | SQL type name (e.g., "VARCHAR", "BIGINT"). |
category |
string | UI grouping category (see below). |
requires_length |
bool | true if this type requires a length argument (e.g., VARCHAR(255)). |
requires_precision |
bool | true if this type requires a precision/scale argument (e.g., DECIMAL(10,2)). |
default_length |
string? | Optional default length pre-filled in the UI (e.g., "255" for VARCHAR). |
Type Categories:
| Category | Examples |
|---|---|
numeric |
INTEGER, BIGINT, DECIMAL, FLOAT, DOUBLE |
string |
VARCHAR, TEXT, CHAR |
date |
DATE, TIME, TIMESTAMP, DATETIME |
binary |
BLOB, BYTEA, VARBINARY |
json |
JSON, JSONB |
spatial |
GEOMETRY, POINT, POLYGON |
other |
BOOLEAN, UUID |
The optional type_mappings field lets your plugin declare how generic inferred type names should be mapped to driver-specific types. This is used during paste/import operations where Tabularis infers column types from data (e.g., detects a date column as DATETIME) and needs to translate that to a driver-native type.
Since map_inferred_type() is a synchronous trait method that cannot issue an RPC call, the mapping is declared statically in the manifest and resolved by the host at lookup time.
Example for a PostgreSQL plugin:
{
"type_mappings": {
"DATETIME": "TIMESTAMP",
"JSON": "JSONB"
}
}Rules:
- Keys are uppercase generic type names (the inferred type before mapping)
- Values are the driver-native equivalents to use instead
- Lookup is case-insensitive (the host uppercases the input before matching)
- If a type has no mapping, it passes through unchanged
- If
type_mappingsis omitted or empty, all types pass through unchanged
The optional connection_fields object adapts the host-owned inputs of the connection modal to a driver that does not use them as-is. Each of host, port, username, password and database accepts:
| Field | Type | Description |
|---|---|---|
hidden |
boolean | Hide the input for this driver. Defaults to false. |
label |
string | Driver-specific label (max 80 characters). |
placeholder |
string | Driver-specific placeholder (max 200 characters). |
Example for a cloud warehouse addressed by project id:
{
"connection_fields": {
"host": { "hidden": true },
"port": { "hidden": true },
"username": { "hidden": true },
"password": { "hidden": true },
"database": { "label": "Project ID", "placeholder": "billing-project" }
}
}Rules:
- Overrides are presentation only: a hidden input is not rendered, but the value already saved for it is left untouched and still sent to the driver.
- A hidden
databaseinput is not required on Test Connection or Save. - Hiding
hostalso hides the "Load databases" action next to the database input. - A flat multi-database driver (
schemas: false, not file- or folder-based, notsingle_database) has no Database input: itsdatabaseholds the databases picked on the Databases tab, or none for All databases. Declaringdatabasewithouthiddenadds the input to the top of that tab, with your label and placeholder, for a value the driver needs besides that selection (SurrealDB'snamespace/databaseto sign in to). Load Databases sends it asparams.database, and so does Test Connection while no database is chosen. The connection saves it asparams.default_database, and the host sends it asparams.databasewhile the connection selects none. Drivers that don't declaredatabaseare unchanged. - Use the
connection-modal.extra_fieldsslot for the inputs the driver needs instead, andsetSecretFieldfor credentials (see SlotContext).
Plugins can declare custom configuration fields that Tabularis renders in the Settings → gear icon modal for that plugin. Users fill in the values, Tabularis persists them in config.json, and passes them to the plugin at startup via an initialize RPC call.
Add an optional settings array at the top level of your manifest:
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"description": "A custom plugin with settings",
"executable": "my-plugin",
"capabilities": { ... },
"data_types": [ ... ],
"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", "ap-southeast-1"],
"default": "us-east-1",
"description": "Deployment region."
},
{
"key": "max_connections",
"label": "Max Connections",
"type": "number",
"default": 10
},
{
"key": "ssl",
"label": "Enable SSL",
"type": "boolean",
"default": true
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
key |
string | yes | Unique identifier used as the key in the settings map. |
label |
string | yes | Human-readable label shown in the UI. |
type |
string | yes | One of: "string", "boolean", "number", "select". |
default |
any | no | Default value pre-filled when no saved value exists. |
description |
string | no | Optional hint displayed below the field. |
required |
boolean | no | If true, saving the modal is blocked until the field is filled. |
options |
string[] | no | For "select" type: the list of choices shown in the dropdown. |
Immediately after spawning the plugin process, Tabularis sends an initialize call:
{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"settings": {
"api_key": "abc123",
"region": "eu-west-1",
"max_connections": 10,
"ssl": true
}
},
"id": 1
}- The
settingsobject contains only the keys the user has configured (merged with defaults). - Returning an error response is safe — Tabularis silently ignores any
initializefailure. - Plugins that do not implement
initializeare unaffected (the error is ignored). - Use
initializeto store settings in your plugin's state before any query arrives. - Google Sheets may receive another
initializeafter its OAuth settings change. It must replace the settings safely while requests are in progress; the host keeps the plugin process running. Updating shared plugin settings requires administrator authorization in Web mode.
"initialize" => {
let settings = ¶ms["settings"];
// Store settings in your plugin state, e.g.:
// API_KEY.set(settings["api_key"].as_str().unwrap_or("").to_string());
json!({
"jsonrpc": "2.0",
"result": null,
"id": id
})
}elif method == "initialize":
settings = params.get("settings", {})
# Store settings for later use:
# api_key = settings.get("api_key", "")
send_response({"result": None, "id": req_id})Plugins can inject custom React components into the host UI through a slot-based extension system. This is entirely optional — plugins without UI extensions continue to work as before.
Add an optional ui_extensions array to your manifest:
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"ui_extensions": [
{
"slot": "row-editor-sidebar.field.after",
"module": "ui/field-preview.js",
"api_version": "0.1.1",
"order": 50
},
{
"slot": "data-grid.toolbar.actions",
"module": "ui/export-button.js",
"api_version": "0.1.1"
},
{
"slot": "settings.plugin.before_settings",
"module": "ui/auth-panel.js",
"api_version": "0.1.1",
"driver": "my-plugin"
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
slot |
string | yes | Target slot name (see table below). |
module |
string | yes | Relative path to the pre-built IIFE JavaScript bundle inside the plugin folder. |
order |
number | no | Sort order within the slot. Lower values render first. Default: 100. |
driver |
string | no | If set, the contribution is only active when the active connection's driver matches this value. Useful for plugins that should only appear for their own driver. |
api_version |
string | recommended | Exact @tabularis/plugin-api version used to build the bundle. Incompatible bundles are skipped before execution. Omit only for legacy compatibility. |
| Slot Name | Location | Context Data | Use Cases |
|---|---|---|---|
row-edit-modal.field.after |
After each field in New Row modal | connectionId, tableName, schema, driver, columnName, rowData, isInsertion |
Validation hints, field previews |
row-edit-modal.footer.before |
Before Save/Cancel in New Row modal | connectionId, tableName, schema, driver, rowData, isInsertion |
Batch actions, templates |
row-editor-sidebar.field.after |
After each field in Row Editor sidebar | connectionId, tableName, schema, driver, columnName, rowData, rowIndex |
Field-level previews, lookups |
row-editor-sidebar.header.actions |
Sidebar header action buttons | connectionId, tableName, schema, driver, rowData, rowIndex |
"Copy as JSON", audit links |
data-grid.toolbar.actions |
Table toolbar (right side) | connectionId, tableName, schema, driver |
Export buttons, analysis tools |
data-grid.context-menu.items |
Right-click context menu on grid rows | connectionId, tableName, schema, driver, columnName, rowIndex, rowData |
Row-level custom actions |
editor.workspace.content |
Full-height main editor workspace | pluginId, workspaceId, connectionId, driver, schema, connectionName? |
Provider-owned service UI; only the owning plugin renders |
explorer.services |
Scrollable Explorer Structure body, before schema/tree sections | connectionId, connectionName, driver, schema |
Native provider service rows opening main tabs |
explorer.connection.actions |
Connection explorer, below its header | connectionId, connectionName, driver, schema |
Connection-specific service tools |
sidebar.footer.actions |
Narrow navigation icon rail footer (icon-sized controls) | connectionId, driver |
Status indicators, quick actions |
settings.plugin.actions |
Per-plugin actions in Settings modal | targetPluginId |
Diagnostics, re-auth buttons |
settings.plugin.before_settings |
Content above plugin settings form | targetPluginId |
OAuth panels, status banners |
connection-modal.setup |
Add Connection after choosing the driver; General when editing | driver, connectionId, isEditing, onConnectionCreated, onClose |
Provider-owned login and connection import; only the selected driver plugin renders. Requires runtime API 0.4.1 |
connection-modal.connection_content |
Inside the connection form | driver, database, connectionName, onDatabaseChange |
Custom connection fields; the callback is bridged over host RPC |
connection-modal.extra_fields |
Below host/port in the connection form | driver, extra, setExtraField, credentialFieldsHidden, setCredentialFieldsHidden, secretFields, setSecretField |
Plugin-specific connection fields (e.g. AWS region), including values stored per connection in the OS keychain. setCredentialFieldsHidden(true) hides and clears the host username/password inputs for drivers that authenticate without a login; while hidden the host also ignores the login of an imported connection string and drops the stored password on save. These callbacks are host RPC methods; callback functions are not cloned into the guest context. |
Provider UI bundles use sandbox API
0.4.1. The guest facade exposes scoped account, connection-service and workspace hooks. Native Monaco editors and read-only grids are rendered by trusted host components, clipped to the owning frame, with callbacks transported over its MessagePort. Plugin code never executes in the host window. Prototype API0.2.7bundles remain rejected; rebuild them against the current SDK.
An external driver can own its Add Connection flow by declaring a
connection-modal.setup entry in ui_extensions with api_version: "0.4.1".
Use this for provider login, project/branch selection and connection import.
This is a UI opt-in; it does not require no_connection_required or a new
backend capability. Declare the driver's real database capabilities normally.
The host reads the selected driver's manifest, so a missing or incompatible
bundle shows an unavailable message instead of generic SQL fields. The slot
only accepts contributions owned by that driver. Existing connection_content
and extra_fields integrations keep their current behavior.
import {defineSlot} from "@tabularis/plugin-api";
export default defineSlot("connection-modal.setup", ({context}) => {
// context: {driver: string, connectionId: string | null, isEditing: boolean,
// onConnectionCreated: () => void | Promise<void>, onClose: () => void}
return <ProviderSetup context={context} />;
}).component;For a new connection, the plugin replaces the full form body and supplies its
own actions; host name/environment inputs, tabs and Test/Save are hidden. Keep
login and imports inside the plugin, for example through usePluginAccount.
After a successful import, await context.onConnectionCreated() to refresh the
host list. This marks the session saved without closing it, allowing success or
warning messages. Call context.onClose() when the user finishes. The catalogue
and Change database navigation stay available.
When context.isEditing is true, display the existing binding identified by
connectionId and offer account reconnection as needed; do not import another
connection. The host renders the setup in General, retains name/environment,
Appearance and Privacy, and saves metadata with existing connection parameters
and secrets intact. Generic SQL/network fields and Test stay hidden.
Every slot component receives a context object with the fields listed above. The available fields depend on the slot — for example, rowData is only present for row-level slots. All fields are optional.
interface SlotContext {
connectionId?: string | null;
tableName?: string | null;
schema?: string | null;
driver?: string | null;
rowData?: Record<string, unknown>;
columnName?: string;
rowIndex?: number;
isInsertion?: boolean;
targetPluginId?: string;
}For connection-modal.extra_fields, setSecretField(key, value) keeps the
value out of connections.json and stores it under the saved connection in the
OS keychain. Passing an empty value explicitly clears the entry. On edit,
secretFields[key] exposes only { value, hasStoredValue, dirty }: an existing
secret is represented by hasStoredValue and is never returned to plugin UI.
Keys are 1-64 ASCII letters, digits, ., _ or -.
At runtime the host resolves stored values into params.extra[key] before
calling the driver (every RPC method, Test Connection, Load Databases and the
MCP server), so the JSON-RPC method shapes remain backward compatible. Export
with credentials and backups carry the values; duplicating a connection copies
them; deleting it removes them; switching the connection to another driver
drops them.
A stored secret can be unavailable at runtime: the connections file was synced
to a machine whose keychain does not have the entry, the keychain was reset, or
it is locked or denies access. The host never fails the call for that. It logs
a warning naming the key (never the value) and calls the driver with
params.extra[key] unset, so the plugin must check for the value and return a
clear error asking the user to set the credential again. Duplicating such a
connection copies only the values that can be read, and an import skips secret
keys with an invalid name instead of rejecting the whole file. Imported values
are written to the keychain only after the connections file has been saved.
Older Tabularis versions do not know plugin_secret_keys and drop it when they
rewrite connections.json. After a downgrade (or with an older install sharing
the same file) the keychain entries stay but are no longer referenced, so the
plugin sees the secret as unset. Setting it again from the connection modal
restores it.
Both properties are optional in the public TypeScript contract. A plugin that
also supports older hosts must guard their presence (for example by falling
back to the host password input when setSecretField is undefined).
Installed UI extensions execute as trusted application code rather than sandboxed widgets. Review the plugin UI extension trust model before distributing or installing third-party bundles.
Plugin UI components must be pre-built as IIFE bundles (Immediately Invoked Function Expression). The host provides React, ReactJSXRuntime, and the plugin API as globals — your bundle must not bundle its own copies of these.
The @tabularis/plugin-api package gives you TypeScript types, hook signatures, and the defineSlot helper for slot-aware type inference. Install it as a dev dependency — at runtime the host injects the real implementation, so the package itself ships as thin stubs.
npm install --save-dev @tabularis/plugin-api
# or: pnpm add -D @tabularis/plugin-apiThen react and @tabularis/plugin-api remain Vite externals in your build config — the installed package is used only for types and autocomplete in your editor.
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
build: {
lib: {
entry: "src/MyComponent.tsx",
formats: ["iife"],
name: "__tabularis_plugin__",
fileName: () => "ui/my-component.js",
},
rollupOptions: {
external: ["react", "react/jsx-runtime", "@tabularis/plugin-api"],
output: {
globals: {
react: "React",
"react/jsx-runtime": "ReactJSXRuntime",
"@tabularis/plugin-api": "__TABULARIS_API__",
},
},
},
},
});Key points:
- The
namefield must be"__tabularis_plugin__"— the host looks for this global.- The component must be the default export of the entry file.
- Multiple slots can reference the same
modulefile.
Recommended: use defineSlot for typed context. The helper infers the exact context shape for the slot you target, so fields like context.columnName are non-nullable where the host guarantees them:
// src/FieldPreview.tsx
import { defineSlot, usePluginConnection } from "@tabularis/plugin-api";
const FieldPreview = defineSlot(
"row-editor-sidebar.field.after",
({ context }) => {
const { driver } = usePluginConnection();
if (context.columnName !== "geometry") return null;
return (
<div style={{ padding: "4px 0", fontSize: "11px", color: "#888" }}>
Geometry preview for {String(context.rowData[context.columnName])}
</div>
);
},
);
// The loader expects a default-exported React component.
export default FieldPreview.component;Legacy form (no typed context). Older bundles used the loose SlotComponentProps shape. Still supported; new plugins should prefer defineSlot.
import { usePluginConnection } from "@tabularis/plugin-api";
import type { SlotComponentProps } from "@tabularis/plugin-api";
export default function FieldPreview({ context }: SlotComponentProps) {
const { driver } = usePluginConnection();
if (context.columnName !== "geometry") return null;
return <div>Geometry preview for {String(context.rowData?.[context.columnName!])}</div>;
}Slot components can import these hooks from @tabularis/plugin-api:
The iframe boundary, RPC capability list, and migration contract are described
in UI_SANDBOX_DESIGN.md.
| Hook | Returns | Purpose |
|---|---|---|
usePluginQuery() |
(query: string) => Promise<{ columns, rows }> |
Execute classified read-only SQL through a database-enforced read-only mode on supported built-in drivers; unsupported drivers reject the call |
usePluginConnection() |
{ connectionId, driver, schema } |
Access active connection metadata |
usePluginToast() |
{ showInfo(), showError(), showWarning() } |
Show toast notifications |
usePluginModal() |
{ openModal(options), closeModal() } |
Show custom React content in a modal contained in the plugin iframe |
usePluginSetting(pluginId) |
{ getSetting(key), setSetting(key, value) } |
Read/write plugin settings |
usePluginTheme() |
{ themeId, themeName, isDark, colors } |
Access current theme info |
usePluginTranslation(pluginId) |
t(key) |
Access plugin-specific i18n translations |
openUrl(url) |
Promise<void> |
Open a URL in the system browser |
exchangeGoogleOAuthToken(request) |
Promise<GoogleOAuthTokenResponse> |
Exchange or refresh Google OAuth tokens at the host-fixed Google endpoint |
usePluginQuery().executeQuery() rejects results larger than 10,000 rows or
16 MiB instead of returning an incomplete result. Add a SQL LIMIT clause or
otherwise narrow the query when a result exceeds either bound.
usePluginModal() lets you open a modal from within a slot component. Its React
content stays inside the sandboxed plugin iframe; it cannot render into the
host application's React tree. Keep the plugin frame open while the modal is
in use, and provide a close button in longer workflows. setSetting and
setSettings now return promises; await them when the next operation depends
on the saved value.
const { openModal, closeModal } = usePluginModal();
openModal({
title: "OAuth Setup",
content: <MyOAuthForm onDone={closeModal} />,
size: "md", // "sm" | "md" | "lg" | "xl"
});Plugins can ship locale files at locales/{lang}.json inside their plugin folder. The host loads them automatically and registers them under the plugin's namespace.
my-plugin/
├── .tabularium
├── my-plugin-binary
├── locales/
│ ├── en.json
│ └── it.json
└── ui/
└── my-component.js
Use usePluginTranslation("my-plugin") in components to access translations via t("key").
You can control when a contribution appears using two mechanisms:
driverfield in manifest: Set"driver": "my-plugin"to only render when the active connection uses that driver.- Component-level filtering: Return
nullfrom your component based oncontextvalues.
export default function PostgresOnly({ context }: SlotComponentProps) {
// Only render for PostgreSQL connections
if (context.driver !== "postgres") return null;
return <div>PostgreSQL-specific action</div>;
}Plugin components must not:
- Import from
@tauri-apps/*directly - Access
window.__TAURI__or invoke Tauri commands - Manipulate the DOM outside their subtree
All host interaction goes through @tabularis/plugin-api.
Each contribution is wrapped in a SlotErrorBoundary. If your component throws, a small error badge is shown instead — other plugins and the host continue working normally.
For the full specification, see plugin-ui-extensions-spec.md.
A plugin that returns the raw explain_query shape can ship the matching
TypeScript parser as an IIFE bundle. Declare each parser in the optional
explain_parsers manifest array:
{
"explain_parsers": [
{
"engine": "example-db",
"format": "example-db-plan-text",
"label": "Example DB plan",
"module": "explain/dist/index.iife.js"
}
]
}engine, format, and module are required non-empty strings. label is
optional. The module path is relative to the installed plugin directory and
must not be absolute or contain ...
Build the module as an IIFE named __tabularis_explain_parser__, externalize
@tabularis/explain to __TABULARIS_EXPLAIN__, and default-export either one
RegisteredExplainParser or an array. The sandbox reads each declared module
once, sends only parser metadata to the host, and the host matches exports by
exact engine and format before registering an asynchronous proxy. Parser
functions stay inside the sandbox. EXPLAIN helpers that dispatch to parsers are
asynchronous and must be awaited. For migration details, see
EXPLAIN_SANDBOX_DESIGN.md.
For example:
import type { RegisteredExplainParser } from "@tabularis/explain";
import { parseExamplePlan } from "./parser";
const parser: RegisteredExplainParser = {
engine: "example-db",
format: "example-db-plan-text",
label: "Example DB plan",
parse: parseExamplePlan,
sniff: (payload) => payload.startsWith("EXAMPLE PLAN"),
};
export default parser;Use a separate IIFE entry that only exports the descriptor. Do not self-register in that entry because the desktop loader performs registration. A package entry intended for npm may register itself when imported. Bundle read, evaluation, and descriptor failures are isolated per plugin; parser exceptions during actual parsing propagate to Visual EXPLAIN's normal error handling.
When enabled plugins change, Tabularis removes the formats loaded by the
previous pass and reloads enabled plugin manifests in sorted plugin-id order.
This makes disable and re-enable cycles deterministic. The plugin's minimum
runtime version must be the first Tabularis release that supports both raw
plugin EXPLAIN output and parser bundles. The host enforces
min_runtime_version at install and load time: an older Tabularis refuses the
plugin with a message naming both versions instead of failing later in Visual
EXPLAIN. Development builds of Tabularis load the plugin anyway and show the
mismatch as a warning toast, so a plugin can be tested against unreleased host
features.
Your plugin must run an event loop that:
- Reads one JSON line from
stdin. - Parses the JSON-RPC request.
- Executes the requested database operation.
- Writes a JSON-RPC response to
stdoutfollowed by\n.
{
"jsonrpc": "2.0",
"method": "get_tables",
"params": {
"params": {
"driver": "duckdb",
"host": null,
"port": null,
"database": "/path/to/my_database.duckdb",
"username": null,
"password": null,
"ssl_mode": null
},
"schema": null
},
"id": 1
}The params.params object is a ConnectionParams — the same values the user entered in the connection form. The top-level params may contain additional method-specific fields (e.g., schema, table, column_name, etc.).
Optional settings appear only when the user set them. For example, connect_timeout_secs is the number of seconds to wait for a new connection. A plugin that supports a connect timeout should honor it and use its own default when it is absent. Likewise, query_timeout_secs is the number of seconds a statement may run; 0 or absent means no limit. Declare capabilities.query_timeout: true only when the plugin can cancel a running statement and will stop it on the server once the limit passes; the connection modal shows the field solely for that capability.
By default, when a connection has SSH enabled, the host forwards one local port to the connection's host / port and sends the plugin 127.0.0.1 and that port instead. That cannot serve a connection that names several endpoints, such as a mongodb+srv:// URI or a replica-set seedlist: the driver discovers the other nodes and connects to them directly.
A driver that declares capabilities.socks5_proxy: true gets a SOCKS5 proxy through the SSH session instead. The host leaves host, port and connection_uri as the user entered them and adds:
| Field | Type | Description |
|---|---|---|
socks5_proxy_host |
string | Always 127.0.0.1. |
socks5_proxy_port |
number | Local port of the proxy. |
socks5_proxy_username |
string | Username the proxy requires (RFC 1929). Absent when the proxy does not authenticate. |
socks5_proxy_password |
string | Password the proxy requires. Absent when the proxy does not authenticate. Treat it as a secret: never log it or show it in an error. |
The fields are only present while SSH is enabled; the host drops any value a client sends. A plugin with this capability must:
- Send every connection to the database through the proxy, passing hostnames unresolved (SOCKS5 domain-name addresses), so the SSH server resolves them.
- Fail with a clear error when the user's connection already configures a different proxy, rather than picking one of the two silently. Otherwise the SSH tab looks active while the traffic takes another route.
Limits:
- Authentication depends on the SSH backend. When the connection uses an SSH password and no key file, the host runs the proxy itself and requires a random username and password, generated per tunnel. Otherwise (a key file, ssh-agent or default keys) the host normally runs the system
ssh -D, whose listener cannot authenticate clients: the username and password are absent and any local process can use the proxy while the tunnel is open. Always send them when present. In every case the proxy listens on127.0.0.1only. - DNS lookups the driver makes itself stay local. Only the destinations the driver connects to go through the proxy. Lookups it performs before connecting, such as the SRV and TXT queries for a
mongodb+srv://URI, use this machine's resolver. If those records exist only in the private network's DNS, the connection fails; the user can switch to a seedlist URI that names the nodes. - One tunnel per bastion. Connections that use the same SSH user, host and port share one proxy. Disconnecting one connection does not close it; it stays open until Tabularis exits or the proxy settings change, and is reopened on the next connection after its SSH session ends.
{
"jsonrpc": "2.0",
"result": [
{ "name": "users", "schema": "main", "comment": null }
],
"id": 1
}{
"jsonrpc": "2.0",
"error": {
"code": -32603,
"message": "Database file not found or inaccessible."
},
"id": 1
}Standard JSON-RPC error codes:
| Code | Meaning |
|---|---|
-32700 |
Parse error |
-32600 |
Invalid request |
-32601 |
Method not found |
-32602 |
Invalid params |
-32603 |
Internal error |
When a call exceeds the configured plugin call timeout, or its awaiting task is explicitly aborted, Tabularis stops waiting and writes a JSON-RPC notification (no top-level id) naming the abandoned request:
{ "jsonrpc": "2.0", "method": "cancel", "params": { "id": 1 } }params.id is the id of the original request. Handling it is optional, but recommended for drivers that run statements on a server: without it a timed-out execute_query keeps running there (and a DELETE or UPDATE still takes effect) even though the user already saw an error.
- Do not reply. A notification has no response; writing one would put an unexpected line on
stdout. - Ignore unknown ids (already finished, already cancelled, or not cancellable). A late or duplicate cancel must never be treated as an error.
- Keep reading
stdinwhile a request runs. A plugin that processes requests strictly one at a time only sees the cancel after the long call has finished. - Disabling the timeout (
0) disables automatic deadline cancellation; explicit caller cancellation still sends the notification. Calls abandoned before dispatch are not sent to the plugin.
Session-aware drivers can implement get_session_state with params { "session_id": "..." } and result { "in_transaction": true } (or false). Report the actual retained session state after earlier requests have settled; an unknown or released session reports false. This RPC must not create a new transaction or execute the original query again.
The host uses this read-only probe after a failed or cancelled query/batch, because the abandoned response may have carried a transaction-state change. It waits at most five seconds. Return JSON-RPC -32601 when unsupported. Unsupported, failed or malformed probes retain the last cached state, if any; an unavailable probe does not prove that a transaction closed. Cancellation may preserve or abort a transaction depending on the driver, so the host does not infer the state solely from cancellation.
Your plugin must respond to the following JSON-RPC methods. For unsupported features, return an empty array [] or a -32601 (Method not found) error: return code -32601 and a message containing Method not found (e.g. Method not found: execute_query_batch). Most fallbacks for optional methods match on the message; a few, such as get_connection_metadata, get_table_query_template and get_column_stats, match on the code.
Test whether a connection can be established.
Params: { "params": ConnectionParams }
Result: { "success": true } or an error response.
Lightweight health check called periodically (every N seconds, configurable) on active connections. If Tabularis does not receive a successful response after 2 consecutive attempts, the connection is considered dead and automatically disconnected.
Params: { "params": ConnectionParams }
Result: null (or any value) on success, or an error response if the connection is no longer alive.
If your plugin does not implement
ping, Tabularis falls back to callingtest_connectioninstead. Implementingpingis recommended for plugins that can perform a cheaper connectivity check than a fulltest_connection(e.g. reusing an existing connection/session rather than opening a new one).
List available databases.
Params: { "params": ConnectionParams }
Result: ["db1", "db2"]
List schemas within the current database.
Params: { "params": ConnectionParams }
Result: ["public", "private"]
Return
[]ifcapabilities.schemasisfalse.
List tables in a schema/database.
Params: { "params": ConnectionParams, "schema": string | null }
Result:
[
{ "name": "users", "schema": "public", "comment": "User accounts" }
]Get column information for a table.
Params: { "params": ConnectionParams, "schema": string | null, "table": string }
Result:
[
{
"name": "id",
"data_type": "INTEGER",
"is_nullable": false,
"default_value": null,
"is_pk": true,
"is_auto_increment": true,
"character_maximum_length": null,
"numeric_precision": null,
"numeric_scale": null,
"comment": null
}
]Metadata comments:
commentis optional in bothget_tablesandget_columns. Older plugins may omit it or returnnull; Tabularis treats both forms as “description unavailable”. This is an additive response field and does not require a manifest capability ormin_runtime_version. When present, the host displays it in the schema inspector, explorer tooltips, and table-browse grid headers.Type precision/length fields:
character_maximum_length,numeric_precision, andnumeric_scaleare optional additive fields (same backward-compatibility rules ascomment). When present, Tabularis preserves them in generatedCREATE TABLEDDL — e.g.numeric(10,2)orvarchar(50)instead of the bare type name — and the host may surface them in the column inspector. Omit them or returnnullfor types that have no such modifier.Full column type:
full_typeis an optional additive field (same backward-compatibility rules ascomment) carrying the full declared type with its modifiers, e.g.varchar(255),decimal(10,2),int unsignedorinteger[]. When present, the explorer's Columns list, the table schema view and the ER diagram show it instead ofdata_type; keep the base type name indata_type, since value handling, editing and DDL generation match on it. Send it only when it says more thandata_type. Without it, the host showsdata_typewithcharacter_maximum_length/numeric_precision/numeric_scaleappended when present (e.g.varchar(50),numeric(10,2)), so a plugin whosedata_typealready embeds the modifiers needs no change.Defaults for the column editor:
default_sqlandon_updateare optional additive fields (same backward-compatibility rules ascomment).default_sqlis the column default as SQL that can followDEFAULTunchanged ('new',CURRENT_TIMESTAMP,(uuid())), andon_updateis the column'sON UPDATEexpression. Whendefault_sqlis present, the Modify Column dialog starts with it as the default and sends it back in bothold_column.default_valueandnew_column.default_value, so a rename keeps the default;on_updateis passed through asColumnDefinition.on_update. Withoutdefault_sqlthe default field starts empty, as before.default_valuekeeps whatever the server reports.JSON / JSONB columns: Set
data_typeto"JSON"or"JSONB"(matched case-insensitively) to make Tabularis render the cell with syntax highlighting and expose the JSON editor window. Inexecute_queryrow data, send the cell as either a native JSON value (object/array/scalar) or a JSON-formatted string — both are accepted. For text-typed columns that hold JSON, end users can opt in per connection via the Detect JSON in text columns setting; no plugin change required.
Get foreign key relationships for a table.
Params: { "params": ConnectionParams, "schema": string | null, "table": string }
Result:
[
{
"name": "fk_user_id",
"column_name": "user_id",
"ref_table": "users",
"ref_column": "id",
"ref_schema": "auth",
"on_update": "CASCADE",
"on_delete": "SET NULL",
"seq_in_fk": 1
}
]Composite foreign keys: For a multi-column foreign key, return one entry per column, all sharing the same
name; setseq_in_fkto the 1-based position of each column within its constraint. Tabularis groups entries byname(ordered byseq_in_fk, falling back to row order) and emits a single multi-columnFOREIGN KEY (a, b) REFERENCES t (x, y)clause.seq_in_fkis optional and additive; older plugins may omit it for single-column FKs.Cross-schema references:
ref_schemais an optional additive field (same backward-compatibility rules asseq_in_fk) naming the schema ofref_table. Drivers withcapabilities.schemas = trueshould set it, because a foreign key can reference a table in another schema (billing.invoices.org_id → core.organizations.id). The Related Records panel and "Open referenced table" then queryref_schema.ref_table; without it, Tabularis assumes the referenced table is in the source table's schema. Omit it or returnnullfor drivers without schemas.
Get indexes for a table.
Params: { "params": ConnectionParams, "schema": string | null, "table": string }
Result:
[
{
"index_name": "idx_email",
"columns": ["email"],
"is_unique": true,
"is_primary": false
}
]List views in a schema/database.
Params: { "params": ConnectionParams, "schema": string | null }
Result: [{ "name": "active_users", "schema": "public" }]
Get the SQL definition of a view.
Params: { "params": ConnectionParams, "schema": string | null, "view": string }
Result: "SELECT * FROM users WHERE active = true"
Get column information for a view.
Params: { "params": ConnectionParams, "schema": string | null, "view": string }
Result: Same structure as get_columns.
Create a new view.
Params: { "params": ConnectionParams, "schema": string | null, "name": string, "definition": string }
Result: null on success, or an error.
Replace or modify an existing view.
Params: { "params": ConnectionParams, "schema": string | null, "name": string, "definition": string }
Result: null on success, or an error.
Drop a view.
Params: { "params": ConnectionParams, "schema": string | null, "name": string }
Result: null on success, or an error.
These methods are optional. Declare materialized_views: true in capabilities to enable the UI. If your plugin returns -32601 (method not found), the host falls back to empty results for get_materialized_views and get_materialized_view_columns; get_materialized_view_definition and refresh_materialized_view surface a "not supported by this driver" error instead.
List materialized views in a schema.
Params: { "params": ConnectionParams, "schema": string | null }
Result: [{ "name": string, "schema": string | null }]
Get columns of a materialized view.
Params: { "params": ConnectionParams, "view_name": string, "schema": string | null }
Result: [TableColumn] (same shape as get_columns)
Get the SQL definition of a materialized view.
Params: { "params": ConnectionParams, "view_name": string, "schema": string | null }
Result: string (the SQL definition)
Refresh a materialized view's data.
Params: { "params": ConnectionParams, "view_name": string, "schema": string | null }
Result: null on success, or an error.
List stored procedures and functions.
Params: { "params": ConnectionParams, "schema": string | null }
Result:
[
{ "name": "calculate_total", "routine_type": "FUNCTION", "schema": "public" }
]A name does not identify a routine in every dialect. Where yours overloads, add
identity_args to each entry with that routine's argument signature:
[
{ "name": "f", "routine_type": "FUNCTION", "identity_args": "" },
{ "name": "f", "routine_type": "FUNCTION", "identity_args": "a integer" },
{ "name": "f", "routine_type": "FUNCTION", "identity_args": "a text" }
]Tabularis labels the sidebar and palette entries with it, so overloads are
distinguishable, and sends it back as identity_args on the two reads below and
on the optional get_routine_edit_script and drop_routine management RPCs, so
each one acts on the routine the user clicked. Without it, every read takes the
first match and the reader cannot tell which one they got.
Three rules, because the field is a key and not a label:
- Omit it where a name is enough. MySQL and SQLite do; there is no overload to disambiguate and an empty label is noise.
- An EMPTY string is a value, not an absence. It is the signature of a
routine that takes no arguments, and it is what tells
f()apart fromf(a integer). Only a missing field means "this dialect does not overload". - Round-trip it unchanged. Tabularis treats it as opaque: it stores what you
send and sends it back verbatim. Use whatever your dialect accepts for
identifying one routine - the PostgreSQL driver uses
pg_get_function_identity_arguments, whichDROP,ALTERand a catalog lookup all take.
Get parameters of a stored routine.
Params: { "params": ConnectionParams, "schema": string | null, "routine": string, "identity_args": string | null }
Result:
[
{ "name": "p_user_id", "data_type": "INTEGER", "mode": "IN" }
]identity_args is the signature your get_routines reported for the row the
user clicked, or null where you reported none. Filter on it: a parameter list
that mixes two overloads is worse than an empty one, because the Run dialog
offers those arguments under one overload's name.
Get the SQL body of a stored routine.
Params: { "params": ConnectionParams, "schema": string | null, "routine": string, "identity_args": string | null }
Result: "BEGIN ... END"
Set capabilities.triggers to true when your driver implements the trigger RPCs. Tabularis uses this flag to show trigger-related UI.
Drivers that advertise triggers and whose dialect is not postgres, mysql or
sqlite — including generic, mssql and oracle — use a complete-SQL editor.
The host sends the entire statement, including procedural bodies, to
create_trigger once. It never drops the existing trigger before saving. Return
an engine-native edit script from get_trigger_definition (for example,
CREATE OR ALTER TRIGGER) when the engine supports one. A failed save leaves
the editor open; the driver must keep the old trigger intact when the
replacement statement fails. The new-trigger editor seeds ON <table> when a
table name is supplied.
List triggers in a schema/database.
Params: { "params": ConnectionParams, "schema": string | null }
Result:
[
{
"name": "users_audit_trg",
"table_name": "users",
"event": "INSERT OR UPDATE",
"timing": "AFTER",
"definition": "CREATE TRIGGER users_audit_trg ..."
}
]Get the SQL definition of a trigger.
Params: { "params": ConnectionParams, "schema": string | null, "trigger_name": string, "table_name": string }
Result: "CREATE TRIGGER users_audit_trg ..."
Create a trigger from SQL generated by the UI or entered in raw SQL mode.
Params: { "params": ConnectionParams, "schema": string | null, "trigger_sql": string }
Result: null on success, or an error.
Drop a trigger.
Params: { "params": ConnectionParams, "schema": string | null, "trigger_name": string, "table_name": string }
Result: null on success, or an error.
Execute a SQL query and return results.
Params:
{
"params": ConnectionParams,
"query": "SELECT * FROM users",
"limit": 100,
"page": 1,
"schema": null
}limit and schema are null when the caller did not pick them; page is 1-based.
Result:
{
"columns": ["id", "name", "email"],
"rows": [
[1, "Alice", "[email protected]"]
],
"affected_rows": 0,
"truncated": false,
"pagination": { "page": 1, "page_size": 100, "total_rows": 1, "has_more": false },
"server_time_ms": 10.5,
"fetch_time_ms": 1.2
}columns, rows and affected_rows are required. truncated defaults to false, and pagination and the timing fields are optional. Report truncated: true when the query produced more rows than you returned, so the caller sees the cut-off instead of a complete-looking result.
Run EXPLAIN or EXPLAIN ANALYZE for a query. Plugins may return either the historical parsed plan shape or a raw payload for a parser registered with the host.
Params:
{
"params": "ConnectionParams",
"query": "SELECT * FROM users WHERE id = 42",
"analyze": false,
"schema": "public"
}Parsed plan result:
{
"root": {
"id": "node-0",
"node_type": "Index Scan",
"relation": "users",
"startup_cost": 0.15,
"total_cost": 8.17,
"plan_rows": 1,
"actual_rows": null,
"actual_time_ms": null,
"actual_loops": null,
"buffers_hit": null,
"buffers_read": null,
"filter": null,
"index_condition": "id = 42",
"join_type": null,
"hash_condition": null,
"extra": {},
"children": []
},
"planning_time_ms": 0.12,
"execution_time_ms": null,
"original_query": "SELECT * FROM users WHERE id = 42",
"driver": "example-db",
"has_analyze_data": false,
"raw_output": null
}Raw result:
{
"engine": "example-db",
"format": "example-db-plan-text",
"payload": "raw plan payload",
"original_query": "SELECT * FROM users WHERE id = 42"
}The raw shape is detected only when engine, format, and payload are all
strings. original_query may be omitted or null; the host then fills it from
the request. Use a format registered by the plugin's EXPLAIN parser bundle.
A plugin returning the raw shape requires a Tabularis host new enough to
understand raw plugin output and load that bundle, so set min_runtime_version
to the first compatible host release. Older parsed-plan plugins remain
supported permanently.
Three gates ask the same question of a query: is it a clean read?
- The MCP read-only mode rejects anything that is not a read.
- The MCP approval gate asks the user before running anything that is not a
read (in the default
writes_onlymode). - A connection saved with Read-only mode (see Optional protected read-only queries) rejects anything that is not a read before it reaches the driver, in the editor, in exports and for MCP clients alike.
The host enforces all three. A driver only answers the question; the gates, and the check of a query the user edited in the approval dialog, stay in the host.
For a SQL driver the host answers by reading the SQL, using sql_dialect and
sql_syntax. For any other driver it still reads the text as SQL, which cannot
work for a query language it does not know (a document store's shell syntax, a
key-value protocol, a search DSL). A plain find comes out unknown, so
read-only mode blocks it, the approval gate asks for it and a saved read-only
connection rejects it; and text that happens to look like a SQL SELECT is
trusted as one, whatever it means to the driver. A driver takes over with two
capabilities, one of them the existing database-enforced read-only execution:
| Capability | RPC | The driver |
|---|---|---|
query_classification |
classify_query |
says what kind of statement a query is |
read_only_queries |
execute_read_only_query |
runs a query and refuses anything that is not a read (see Optional protected read-only queries) |
A non-SQL driver declares both. A select verdict from classify_query is only
trusted (allowed in read-only mode, no approval needed, accepted by a saved
read-only connection) when the driver also declares read_only_queries, or is
readonly and cannot write at all. A classifier alone is not an execution-time
guarantee. The host runs a query it classified as a read through
execute_read_only_query when the connection is read-only or the query skipped
approval, and a failed protected call is never retried through execute_query.
Called only when capabilities.query_classification is true, with the exact
text that is about to run: the same string the host then sends to execute_query
or execute_read_only_query. The host does not split it into statements, strip
comments from it or otherwise rewrite it.
Params:
{
"params": ConnectionParams,
"query": "db.users.find({ \"active\": true })"
}Result:
{ "kind": "select" }kind |
Meaning |
|---|---|
select |
Exactly one statement (or command) that only reads. It changes no data, schema, server state or file, and has no side effect: no aggregation stage that writes, no function that writes. |
write |
Changes data. |
ddl |
Changes structure: collections, indexes, tables. |
unknown |
Anything else: text the driver cannot parse, more than one statement, an operation it does not know to be safe. |
Rules for the driver:
- Classify with the parser
execute_queryuses, on the same text. A classifier that reads a query differently from the executor can be handed a write that looks like a read, for example when one of them drops comment lines and the other keeps them, or when they split the collection name at different dots. - Be conservative: when in doubt, answer
unknown. Classifying must not run the query. - The result is an object, and fields beyond
kindare ignored.
What the host does:
- Without the capability no RPC is sent and the host reads the query as SQL.
- With it the host never reads the query as SQL. An RPC error (
-32601included), a transport error, a timeout, a result that is not an object with akind, and akindother than the four above all count asunknown. - A
selectcounts only when the driver also has an execution guarantee,read_only_queriesorreadonly; otherwise the host reportsunknown. A saved read-only connection requires one of them anyway. - Every text is classified on its own. A query the user edits in the approval dialog is classified again before it runs, and the gates apply to the edited text.
- A saved read-only connection classifies a query in the preflight and again
inside the protected execution, which also runs once per statement of a batch
and once per page of an export. Keep
classify_querycheap.
Compatibility:
- Without
query_classificationno new RPC is sent and nothing changes, for plugins and built-in drivers alike. - A driver that declared the capability is never read as SQL, so a plugin that
declares it without implementing the method reads as
unknowneverywhere. - Older hosts ignore the capability and never call the method: they keep reading
the queries of a non-SQL driver as SQL, as before. Plugins need not raise
min_runtime_versionsolely for this optional feature. - The capability is a static manifest opt-in, not a connection-metadata override.
Registry rollout: as for table_query_templates, add the optional boolean
query_classification (default false) to the driver kind's
capabilities.properties in Tabularium before publishing a plugin that sets it.
Insert a new row into a table.
Params:
{
"params": ConnectionParams,
"schema": null,
"table": "users",
"data": { "name": "Bob", "email": "[email protected]" }
}Result: null on success, or an error.
Update a single field in a row.
Params:
{
"params": ConnectionParams,
"schema": null,
"table": "users",
"pk_col": "id",
"pk_val": 42,
"col_name": "name",
"new_val": "Robert"
}Result: Number of affected rows (e.g. 1), or an error.
Delete a row from a table.
Params:
{
"params": ConnectionParams,
"schema": null,
"table": "users",
"pk_col": "id",
"pk_val": 42
}Result: Number of affected rows (e.g. 1), or an error.
These methods are optional. If your plugin returns -32601 (method not found), the host shows "BLOB export/preview not supported" to the user.
Save a binary column value to a file on disk. The plugin receives the file path and is responsible for writing the file directly (since the plugin runs on the same machine as the host).
Params:
{
"params": ConnectionParams,
"table": "documents",
"col_name": "content",
"pk_map": { "id": 42 },
"schema": "public",
"file_path": "/tmp/export.pdf"
}Result: null on success, or an error.
Contract: The plugin must:
- Query the binary column value using the PK map to identify the row
- Write the raw bytes to
file_path - Return
nullon success or an error string on failure
Fetch a binary column value and return it as a displayable string (for preview in the row editor).
Params:
{
"params": ConnectionParams,
"table": "images",
"col_name": "data",
"pk_map": { "id": 7 },
"schema": "public"
}Result: A string in the BLOB wire format: "BLOB:<size_bytes>:<mime_type>:<base64_data>", or an error.
Example response:
{ "result": "BLOB:1024:image/png:iVBORw0KGgo..." }AI Query Assist obtains metadata through the active database driver. Plugins
that already implement get_tables, get_columns, and get_foreign_keys work
without changes: Tabularis calls those standard methods, limits the result, and
formats the provider-agnostic system prompt in the host.
Plugins may optionally implement get_ai_schema_context to replace those
per-table calls with a database-specific batch query. Return JSON-RPC error
-32601 when the method is not implemented; Tabularis then uses the standard
metadata fallback automatically.
Params:
{
"params": ConnectionParams,
"schema": "public",
"max_tables": 20
}Result:
{
"tables": [
{
"name": "users",
"columns": [ /* standard get_columns entries */ ],
"foreign_keys": [ /* standard get_foreign_keys entries */ ]
}
],
"total_table_count": 42
}The plugin must respect max_tables, but total_table_count reports the
number of tables before truncation. Plugins return structured metadata only;
the host owns prompt wording, identifier quoting, and provider dispatch.
These methods are used to build ER diagrams efficiently by loading all metadata in one call.
Return the complete schema structure (tables + columns + foreign keys).
Params: { "params": ConnectionParams, "schema": string | null }
Result:
[
{
"name": "users",
"columns": [ /* column list */ ],
"foreign_keys": [ /* FK list */ ]
}
]Return columns for all tables at once.
Params: { "params": ConnectionParams, "schema": string | null, "tables": ["users", "orders"] }
Result: { "users": [ /* columns */ ], "orders": [ /* columns */ ] }
Return foreign keys for all tables at once.
Params: { "params": ConnectionParams, "schema": string | null, "tables": ["users", "orders"] }
Result: { "users": [ /* FKs */ ], "orders": [ /* FKs */ ] }
get_table_query_template is an optional, additive RPC, called only when
capabilities.table_query_templates is true. It returns a SQL preview and
must not execute the generated statement.
Params:
{
"params": { "driver": "sqlserver", "connection_id": "..." },
"request": {
"table": "orders",
"schema": "sales",
"kind": "select",
"columns": ["id", "status"],
"limit": 100
}
}params is the usual resolved ConnectionParams. request.kind is select,
update or delete. Table, schema and column names are unquoted identifiers,
not SQL fragments; the driver must quote and escape them. columns defaults to
[]: SELECT uses *, UPDATE produces an editable column placeholder. schema
and limit may be omitted or null. limit is an unsigned 32-bit explicit SELECT
row limit (including zero); UPDATE/DELETE reject a non-null limit. SELECT All
passes no limit; SELECT Fields passes 100. UPDATE/DELETE templates must include
WHERE 1 = 0 to prevent accidental broad writes. UPDATE values use the host
editor's named placeholders (:value_1, etc.), not driver-native bind markers.
Result: a string, for example
"SELECT TOP (100) [id], [status] FROM [sales].[orders];".
Compatibility:
- Missing/false capability: no new RPC is sent; legacy generation is unchanged.
- Remote JSON-RPC error code
-32601: the host falls back to its legacy template. Transport errors, other remote errors and malformed results are surfaced, not silently replaced with another SQL dialect. - The Tauri command returns
string | null; null is the host's fallback signal, not a valid plugin success result. - Existing RPC signatures, built-in driver behavior and CREATE TABLE generation are unchanged. This is not a replacement for the existing DDL methods.
- Older hosts ignore the new manifest capability and never call the method.
Plugins need not raise
min_runtime_versionsolely for this optional feature. - The capability is a static manifest opt-in, not a connection-metadata override.
Registry rollout: add an optional boolean table_query_templates (default
false) to the driver kind's capabilities.properties in Tabularium for schema
validation and generated documentation. Do not make it required. The registry
only distributes the manifest and release; it does not route the RPC. No change
to registry endpoints, release formats or the Tabularium SDK is needed. Register
the property before publishing: Tabularium ingestion uses lenient validation with
AJV removeAdditional: 'all', which strips undeclared capability keys even when
the capabilities schema otherwise allows additional properties. Refresh an
already-ingested manifest after updating the schema.
The data grid's column header menu has a Column statistics entry on table tabs. It opens a popover with the row count, NULL count, distinct count, min / max and the most frequent values of the column, for the rows that match the tab's current filter.
Which source the host uses depends on the driver's capabilities:
| Driver | Statistics come from |
|---|---|
Plugin with capabilities.column_stats: true |
the plugin's get_column_stats RPC |
Built-in driver, or plugin whose sql_syntax.extends or sql_dialect is postgres, mysql or sqlite |
the host's generic SQL (COUNT(*), COUNT(DISTINCT col), MIN / MAX, then GROUP BY col ORDER BY 2 DESC, 1 LIMIT 10) |
| Any other plugin | nowhere: the menu entry is hidden |
"SQL-compatible" means an explicitly declared sql_syntax.extends or
sql_dialect that the generic SQL runs on (a valid extends wins when both are set;
an extends that isn't a known dialect is ignored, as for the syntax preset).
Declaring neither doesn't count (the statement splitter treats it as
postgres, but that is a splitting default, not a promise that the engine
runs arbitrary SQL). mssql and oracle have no
LIMIT, and generic promises no particular syntax, so those plugins need
column_stats to get the popover. A plugin that borrows a dialect only for
quoting or splitting (for example a non-SQL engine declaring mysql for
backtick identifiers) should opt in, or its users get a failing query.
get_column_stats is an optional, additive, read-only RPC, called only
when capabilities.column_stats is true.
Params:
{
"params": { "driver": "surrealdb", "connection_id": "...", "database": "app" },
"request": {
"table": "orders",
"schema": null,
"column": "total",
"data_type": "decimal",
"filter": "status = 'open'",
"top_values_limit": 10,
"include": { "distinct": true, "min_max": true, "top_values": true }
}
}paramsis the usual resolvedConnectionParams, with the tab's database.table,schemaandcolumnare unquoted identifiers; the driver quotes and escapes them.schemais null unless the driver hasschemas: true.data_typeis the column type the grid shows, or null when unknown.filteris the tab's current filter, a WHERE clause without the keyword, exactly as the grid query applies it (so in the plugin's own dialect), or null. Sort and LIMIT are not applied.includesays which optional parts to compute. The host turns parts off for types where they make no sense (no min / max for text, no top values for binary or JSON columns) and for masked columns, which never get min / max or top values. Skip what isn't asked for; the host drops it anyway.- The request carries no session context: the tab's
sessionIdis not sent, so session-local state (temporary tables,SET search_path) is not visible toget_column_stats. The same applies toget_table_query_template.
Result:
{
"row_count": 120,
"null_count": 3,
"distinct_count": 40,
"min": 1.5,
"max": 980,
"top_values": [{ "value": 25, "count": 12 }, { "value": 30, "count": 9 }],
"sample_size": null
}row_countandnull_countare required unsigned integers (rows matching the filter, and those where the column is NULL or missing), withnull_count <= row_count.distinct_count,min,maxandtop_valuesmay be null or omitted when not computed.min/maxand the topvalues are any JSON value; the popover shows strings as they are and other values as JSON.top_valueslists the most frequent non-NULL values, most frequent first, at mosttop_values_limitof them. Clicking one filters the table bycolumn = valuethrough the usual filter clause.sample_size(optional): set it whendistinct_count,min,maxandtop_valueswere computed over a sample of that many non-NULL values instead of all of them.row_countandnull_countmust stay exact. The popover then says the value statistics come from a sample, computes the top value shares against the sample and doesn't claim the column is unique.
Compatibility:
- Missing/false capability: no RPC is sent; the rules in the table above apply.
- Remote JSON-RPC error code
-32601: the host falls back to its generic SQL when the plugin is SQL-compatible, and otherwise shows "doesn't provide column statistics" in the popover. Transport errors, other remote errors and malformed results are shown as errors. - The Tauri command
get_column_statsreturns the result ornull; null is the host's fallback signal, not a valid plugin success result. - Cancellation: closing the popover doesn't cancel the RPC (there is no
per-request cancel, and
cancel_querywould stop the whole connection). The host drops a result that arrives after the popover closed. Keep the method cheap on large tables, for example by sampling. - Built-in drivers are unchanged. Older hosts ignore the capability and never call the method.
- The capability is a static manifest opt-in, not a connection-metadata override.
Registry rollout: as for table_query_templates, add an optional boolean
column_stats (default false) to the driver kind's capabilities.properties
in Tabularium before publishing a plugin that sets it.
open_data_file is an optional, additive RPC, called only for a format
listed in capabilities.data_files. It exposes one data file as a read-only
relation (a view, typically) so the grid, the SQL editor and exports work on the
file like on any table.
Params:
{
"params": { "driver": "duckdb", "database": "/…/data-files/duckdb/workspace.db" },
"path": "/home/me/exports/orders.csv",
"format": "csv",
"table": "orders"
}params is the usual resolved ConnectionParams. params.database is the
driver's workspace database: a file the host owns under its data directory
(data-files/<driver id>/workspace.db) and passes on every call; the driver
creates it on first use. path is an absolute host path to a regular file.
format is one of the declared data_files values; the host derives it from
the file extension (csv; tsv/tab; json; ndjson/jsonl;
parquet/pq; xlsx). table is an unquoted identifier made of letters,
digits and underscores; the driver must quote it and must treat path as data,
not SQL.
Result: null. The relation named table must then be listed by
get_views (or get_tables) and be queryable with execute_query. Opening the
same table again replaces the relation.
Behaviour the host relies on:
- Keep the relation lazy: scan the file when it is queried instead of copying it, and do not hold the file open between queries, so a large file opens at once and nothing stays locked.
- Fail the call when the file cannot be read as
format; the host shows the error and creates nothing. - The user closes a file with the regular drop action for the relation
(
drop_view). For a file uploaded from the Web UI the host stores the file beside the workspace (uploads/<table>/) and removes it onceget_viewsno longer liststable.
Compatibility:
- Missing or empty capability: the RPC is never sent. When no registered driver declares a file's format, the host offers to install the DuckDB plugin.
- The host saves one regular connection to the workspace database, named by the user's locale ("Data files"), and reuses it for every file the driver opens.
- In the Web UI the command requires local-administrator authorization, like the other file-backed drivers, because the workspace's SQL can read host files.
- Built-in drivers are unchanged. Older hosts ignore the capability and never call the method.
- The capability is a static manifest opt-in, not a connection-metadata override.
Registry rollout: as for table_query_templates, add an optional string array
data_files (default []) to the driver kind's capabilities.properties in
Tabularium before publishing a plugin that sets it.
These methods generate SQL statements. Tabularis may display the SQL to the user before executing it. When get_tables / get_columns return comments, the host preserves them in generated inspection SQL for MySQL-family dialects and dialects that use COMMENT ON (currently PostgreSQL and Oracle). Other dialects continue to receive the existing DDL without comments; no manifest change is required.
Connection context. Every DDL generation request carries params
(ConnectionParams) with the database the user is browsing already applied:
in a multi-database connection params.database is the selected database (for
example a project), not the first one saved on the connection. Plugins can use
it to qualify names (project.dataset.table) or pick a dialect variant. The
field is additive: older plugins that ignore it keep working. These are pure
SQL builders: Tabularis does not open SSH/SSM/K8s tunnels for them, so
host/port are the saved values (not a local tunnel endpoint). The keychain
password, the connection URI and the plugin-owned secrets
(params.extra[key], see setSecretField) are passed when
they can be read; a secret that is missing or unreadable is left unset and the
request is still sent. Build the SQL without connecting when you can. A builder
that needs the backend (for example get_drop_table_sql looking up the table
kind) must handle an unset credential by falling back to a generic statement or
returning a clear error. Results are an array of statements, executed in
order.
ColumnDefinition:
{ "name": "email", "data_type": "VARCHAR(255)", "is_nullable": true, "is_pk": false,
"is_auto_increment": false, "default_value": null, "comment": "Primary contact address" }comment is optional and only present when the user entered a description
(the field is shown only when the plugin declares capabilities.column_comments).
In get_alter_column_sql, compare old_column.comment with
new_column.comment: a missing new_column.comment while the old one was set
means the description was cleared.
Params: { "params": ConnectionParams, "schema": string | null, "table_name": string, "columns": ColumnDefinition[] }
Result: ["CREATE TABLE users (...)"]
Params: { "params": ConnectionParams, "schema": string | null, "table": string, "column": ColumnDefinition }
Result: ["ALTER TABLE users ADD COLUMN ..."]
Params: { "params": ConnectionParams, "schema": string | null, "table": string, "old_column": ColumnDefinition, "new_column": ColumnDefinition }
Result: ["ALTER TABLE users MODIFY COLUMN ..."]
The dialog fills both columns from the existing column, so an unchanged default arrives as the same default_value in old_column and new_column. Compare them before emitting a default change. A dialect that restates the whole column (MySQL CHANGE / MODIFY) should also restate new_column.on_update when it is set.
Params: { "params": ConnectionParams, "schema": string | null, "table": string, "index_name": string, "columns": string[], "is_unique": boolean }
Result: ["CREATE INDEX idx_email ON users(email)"]
Params: { "params": ConnectionParams, "schema": string | null, "table": string, "fk_name": string, "column": string, "ref_table": string, "ref_column": string, "on_delete": string | null, "on_update": string | null }
Result: ["ALTER TABLE orders ADD CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id)"]
Optional. Returns the editor template for a new routine. A -32601 falls back
to a generic CREATE PROCEDURE/CREATE FUNCTION skeleton.
Params: { "params": ConnectionParams, "schema": string | null, "routine_type": "PROCEDURE" | "FUNCTION" }
Result: "CREATE PROCEDURE my_routine() ..."
Optional, and only called when the manifest declares
capabilities.drop_table_sql: true. Returns the statement the explorer runs
when the user drops a table, for engines where a plain DROP TABLE is wrong
for some table kinds (for example DROP SNAPSHOT TABLE or
DROP EXTERNAL TABLE). database is the database the user is browsing (also
applied to params.database), or null.
Params: { "params": ConnectionParams, "table": string, "schema": string | null, "database": string | null }
Result: "DROP SNAPSHOT TABLE `project.dataset.daily`"
Return null (or a -32601 Method not found error) to let Tabularis build its
generic DROP TABLE <quoted schema>.<quoted table> with your
identifier_quote. A blank string or any non-string result (an array, an
object, ...) is ignored the same way, with a warning in the host log. Any other
error is shown to the user and nothing is executed. Plugins without the
capability, and built-in drivers, never receive this call; older hosts ignore
the flag and always run the generic statement.
Params: { "params": ConnectionParams, "schema": string | null, "table": string, "index_name": string }
Result: null on success, or an error.
Params: { "params": ConnectionParams, "schema": string | null, "table": string, "constraint_name": string }
Result: null on success, or an error.
Export table to SQL... writes one table, its structure and optionally its
rows, to a .sql file in your driver's dialect; Import table from SQL...
reads such a file back into a connection that uses the same driver. Both work
for a plugin that implements nothing new:
- Structure: the host calls
get_table_ddlbelow; without it, it buildsCREATE TABLEfromget_columnsandget_create_table_sql, and marks the fileStructure-Source: generated(indexes, constraints and defaults may be missing). - Rows: the host pages
execute_querywith 1000 rows per page, ordered by the primary key. Your paging must be deterministic and reportpagination.has_morecorrectly, or rows are lost or repeated. - Literals: without
render_insert_statementsbelow, the host rendersINSERTstatements fromidentifier_quote,sql_dialectandsql_syntax(string escaping and boolean literals). - Import: the host runs each statement through
execute_querywith the targetschema, and drops the table again when an import that created it fails. Withoutmanage_tablesonly Append rows into an existing table is possible.
Identifiers in the file are not schema-qualified, so a file can be imported
into any database or schema of a server using the same driver. Set
table_export and table_import to false when your engine has no SQL.
The engine's own CREATE TABLE (and index statements) for an existing table,
also used by Dump Database. Return it unqualified, or qualified exactly as
<quoted schema>.<quoted table> with your identifier_quote (the host strips
that prefix). Answer -32601 Method not found when you can't.
Params: { "params": ConnectionParams, "table": string, "schema": string | null }
Result: "CREATE TABLE [orders] (\n [id] int NOT NULL PRIMARY KEY\n);"
The host negotiates complete database transfers through runtime RPCs, without assuming that a table DDL dump reconstructs routines, permissions or dependencies. Missing methods (JSON-RPC -32601) and null results retain the existing host path; all other errors stop the operation. Built-in drivers default to that path.
get_database_sql_capabilities:{params: ConnectionParams}returns null or{format: string, native_backup?: {format: string, extension: string, label: string, description?: string}, create_database: boolean, requires_empty_target: boolean, target_label: string}.formatis the SQL dump format id (typically"sql"). The import dialog usestarget_labelas the destination field caption and asks for an explicit start action for this protocol. When the plugin can produce a native whole-file backup, setnative_backup:format: id the host echoes inexport_database_sqloptions.formatextension: ASCII alphanumeric file extension, 1–16 characters, no leading dot or path separators (for example"fbk"). The host rejects anything else.label: dump-dialog option text (for example"Complete Firebird backup (.fbk)")description: optional help shown when that format is selected The host never infers a native format from the driver id. A plugin that omitsnative_backuponly offers SQL. A booleannative_backup(for exampletruefrom Firebird plugin v1.0.0) is accepted and treated as omitted: the host still offers SQL, but not a native dump, until the plugin sends the object.
export_database_sql:{params, file_path: string, options: {format?: string, structure: boolean, data: boolean, tables: string[] | null}}returns null or{rows: number, tables: number}.options.formatis omitted or"sql"for SQL, or thenative_backup.formatid for a native backup. Do not fall back to SQL when a native format was requested. The path is a private host-owned pending file. Finish and close it before returning success. The host publishes it atomically; errors preserve any previous destination. Reject unsupported partial-schema selections explicitly, or return null to use the host renderer.import_database_sql:{params, file_path: string, create_database: boolean}returns null for an unrecognized ordinary SQL file, or{statements: number}. Validate the complete file before modifying the destination. Own statement boundaries, dependencies, transaction policy, cancellation and cleanup. A new target must never overwrite an existing database. The host never falls back to ordinary SQL execution when creation was requested but the RPC returns null. Native backup files are recognized bynative_backup.extension.
Connection parameters are supplied directly before metadata specialization, so new database creation does not first require a successful attachment to that target. Desktop file paths come from the native chooser; browser requests still use opaque session-owned upload/download tokens. ZIP imports pass the extracted SQL file while retaining its cleanup guard. No browser client supplies a server file path.
Whole-file import/export RPCs do not inherit the ordinary 120-second plugin timeout. Explicit global or per-plugin call timeouts still apply, including zero to disable them. Transfer cancellation and the client transfer deadline remain active.
Renders complete INSERT statements for one batch of up to 500 rows, for
engines whose literals the host can't write (dates, decimals, binary, arrays,
JSON, N'...' strings). rows are positional arrays matching columns, with
values as your own execute_query returned them. No database access: this is
pure rendering. Each statement may end with ; or not.
Params: { "table": string, "schema": string | null, "columns": string[], "rows": any[][] }
Result: ["INSERT INTO [orders] ([id], [note]) VALUES (1, N'it''s'), (2, NULL);"]
A -32601 Method not found error makes the host render this and every later
batch itself. Any other error stops the export.
The table's approximate row count from the engine's own statistics, shown in
the Export table to SQL... dialog. Keep it cheap: no table scan. Return
null when there is no estimate; -32601 Method not found shows none.
Params: { "params": ConnectionParams, "table": string, "schema": string | null }
Result: 128400
Here is a minimal but functional skeleton for a plugin executable in Rust.
use std::io::{self, BufRead, Write};
use serde_json::{json, Value};
fn main() {
let stdin = io::stdin();
let mut stdout = io::stdout();
for line in stdin.lock().lines() {
let line = line.unwrap();
if line.trim().is_empty() {
continue;
}
let req: Value = serde_json::from_str(&line).unwrap_or_else(|_| {
// Ignore unparseable lines
return Value::Null;
});
if req.is_null() {
continue;
}
let id = req["id"].clone();
let method = req["method"].as_str().unwrap_or("");
let params = &req["params"];
let response = dispatch(method, params, id);
let mut res_str = serde_json::to_string(&response).unwrap();
res_str.push('\n');
stdout.write_all(res_str.as_bytes()).unwrap();
stdout.flush().unwrap();
}
}
fn dispatch(method: &str, params: &Value, id: Value) -> Value {
match method {
"test_connection" => json!({
"jsonrpc": "2.0",
"result": { "success": true },
"id": id
}),
// Optional: lightweight health check (called periodically).
// If omitted, Tabularis falls back to test_connection.
"ping" => json!({
"jsonrpc": "2.0",
"result": null,
"id": id
}),
"get_databases" => json!({
"jsonrpc": "2.0",
"result": ["my_database"],
"id": id
}),
"get_schemas" => json!({
"jsonrpc": "2.0",
"result": [],
"id": id
}),
"get_tables" => {
// Connect to the database using params["params"]["database"], etc.
json!({
"jsonrpc": "2.0",
"result": [
{ "name": "example_table", "schema": null, "comment": null }
],
"id": id
})
},
"execute_query" => {
let query = params["query"].as_str().unwrap_or("");
// Execute query and return results
json!({
"jsonrpc": "2.0",
"result": {
"columns": ["id", "name"],
"rows": [[1, "Alice"]],
"affected_rows": 0,
"truncated": false
},
"id": id
})
},
_ => json!({
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": format!("Method not found: {}", method)
},
"id": id
}),
}
}Add serde_json to your Cargo.toml:
[dependencies]
serde_json = "1"You can test your plugin directly by piping JSON-RPC messages:
echo '{"jsonrpc":"2.0","method":"get_tables","params":{"params":{"driver":"duckdb","database":"/tmp/test.duckdb"},"schema":null},"id":1}' \
| ./duckdb-pluginYou should see a valid JSON-RPC response on stdout.
- Create the plugin directory in Tabularis's data folder:
- Linux:
~/.local/share/tabularis/plugins/drivers/myplugin/ - macOS:
~/Library/Application Support/tabularis/plugins/drivers/myplugin/ - Windows:
%APPDATA%\tabularis\plugins\drivers\myplugin\
- Linux:
- Place your
.tabularium(or legacymanifest.json) and the compiled executable in that directory. - On Linux/macOS, make the executable runnable:
chmod +x myplugin - Restart Tabularis (or install via Settings to hot-reload without restart).
- Open Settings → Installed Plugins — your driver should appear.
- Try creating a new connection using your driver from the connection form.
To make your plugin available in the official registry:
- Build release binaries for all supported platforms.
- Package each platform binary with your
.tabulariuminto a.zipfile (the scaffolded release workflow does this). - Create a GitHub Release with the ZIP files attached — plus
.tabulariumas a standalone asset (GitHub renames it todefault.tabularium; the registry accepts both). The registry resolves the manifest from release assets, and the tag stripped ofvmust equal the manifestversion. - Submit your plugin at registry.tabularis.dev/submit — ownership is verified via OAuth against your linked repository, and CI can pre-validate the manifest via
POST /api/manifest/validate. A manifest that fails validation is rejected with HTTP 422 — there is no silent fallback. The registry's plugin development page documents every.tabulariumfield; the full author docs live at docs.tabularium.wiki. - Installs are verified client-side: Tabularis checks the registry's JWS signature and the download's SHA-256 before anything runs.
The legacy path — a pull request adding an entry to plugins/registry.json (format in README.md) — still works during the transition; new plugins should submit to the registry directly.
Note:
min_tabularis_versionis specified per-release inside thereleases[]array, not at the root plugin level. This allows older Tabularis installs to install an older compatible release even when a newer release requires a higher app version.
Account prerequisites and interactive sign-in setup can use
usePluginAccount(pluginId).prepare(method, args) (API 0.4.1). Like account
calls, it requires local-admin authorization. The host forwards no stored
account/SQL credentials, only {method,args,secrets:{},context:{plugin_id, scope:"account-setup"}} to the enabled external plugin. Keep an explicit setup
method allowlist, bound any child processes or polling, start login only after
a user action, and return metadata rather than credentials or raw process output.
account_import cannot be called through preparation. copyText(text) provides
host-native clipboard access for commands and diagnostic text.
Use usePluginWorkspace(pluginId).openWorkspace({id, title, connectionId?}) from an
explorer.services contribution to open a provider service as a main
editor tab. Register its content in editor.workspace.content (with api_version: "0.4.1"). Reopening the same plugin/workspace/connection focuses the existing tab;
other connections keep separate tabs. The optional connection ID must match both
the current slot connection and the editor connection. Mismatches throw instead of
switching connections or assigning the workspace to another connection.
Only tab metadata and the plugin/workspace identifiers are saved. Do not put
credentials in workspace IDs or titles. SQL controls and query shortcuts are
unavailable on workspace tabs. Disabled, removed, or unloadable plugins show an
unavailable state; their tabs can still be closed and reopened. Background
workspaces stay mounted and retain their iframe state. Content unmounts when its
tab closes or the plugin is disabled or removed, so clean up polling,
subscriptions and pending requests in React effect cleanup. Bind service calls with
usePluginRpc(pluginId, context.connectionId) rather than a changing global selection.
PluginExplorerSection renders a native collapsible Explorer section. Pass
pluginId, providerName, optional connectionId/icon/disabled, and
items: [{id, label, icon?}]. Each row opens its own main tab, titled
Provider · Service, and repeated clicks focus that tab. Selection is scoped to
the owning plugin, service and connection. Supported item icon names are
overview, branches, database, users, storage, functions, ai, realtime, settings,
documents and security; unknown icons use the document icon. Scope errors
appear inline. The provider mark stays small and uses the native section header.
PluginWorkspaceShell supplies a compact native header and bounded scrolling
content. Pass title, optional subtitle/icon/actions, and children for the
current service. It renders full-width content with no internal navigation by
default. Existing callers can still pass tabs: [{id, label, icon?}], activeTab,
onTabChange, and optional brandColor for the navigation indicator.
PluginConnectionAction remains supported for existing connection actions.
PluginDataGrid renders the actual host data grid for read-only provider results.
Pass columns: string[], rows: unknown[][], optional connectionId, and optional
accessible label. It has a bounded height and uses native copy preferences,
selection and column resizing. It exposes no mutation callbacks or generated SQL.
API 0.4.1 adds PluginResourceList and PluginCodeEditor. Declare at least
api_version: "0.4.1" before using them; Earlier sandbox hosts do not expose these
components. Older plugin bundles remain supported by the newer host.
PluginResourceList takes items: [{id, title, subtitle?, status?}], onOpen(id),
emptyMessage, and an optional accessible label. Open resource details with
usePluginWorkspace, keeping connection ownership and resource IDs explicit.
PluginCodeEditor takes controlled value/onChange, optional language
(javascript, typescript, json, or plaintext), readOnly, and an accessible label.
Its parent supplies the height. It shares the host's lazy Monaco instance,
editor theme and font preferences, and does not register SQL execution actions.
Keep provider deployment, secrets and draft persistence policies in the plugin.
API 0.4.1 exposes a themed, searchable PluginSelect popup for sandboxed provider forms.
Declare api_version: "0.4.1" before using placeholder, loading, loadingLabel
and option descriptions. Pass value, onChange(value) and
options: [{value, label, description?}]. Empty-string values remain valid for a
personal account; placeholders are separate from selectable values.
Link a translated label with id, or pass ariaLabel; use disabled and
ariaDescribedBy for prerequisites. Set loading and a translated loadingLabel
while fetching dependent options. The host renders the spinner, announces the
loading state and closes any stale popup. It also handles search, keyboard
navigation, Escape layering, scrolling and theme colors instead of delegating
the popup to the operating system.