Writing plugins
A plugin declares what it can do in its manifest, should pass the contract suite, and builds on a plugin API that stays backward compatible within a major version. To install or manage plugins, see Plugins.
Capabilities
Section titled “Capabilities”The manifest declares what the plugin can do, and the UI offers only what it declares. Each
capability is a key. What it brings lives under that key of session.services (what connect
returns) or of language.services, or it is the plugin’s language or commandLanguage. A flag
brings no service.
A key is present exactly when its capability is declared, and the other way round. TableCraft checks this when it loads the plugin and on every session it opens, and refuses a plugin that breaks it.
| Capability | What it does | Where it lives |
|---|---|---|
sql |
Runs one statement and returns rows or a row count; the plugin also supplies the SQL language (splitting, classifying, completion). | plugin.language |
cancel |
Stops a running statement, and says what the stop reaches. | session.services.cancel |
schemaTree |
Lists schemas and describes tables, views, columns, keys and indexes. | session.services.schemaTree |
transactions |
Switches between auto-commit and manual transactions, commits and rolls back. | session.services.transactions |
ddl |
Returns the definition of a table or view; requires schemaTree. |
session.services.ddl |
explain |
Returns the plan of a statement without running it; requires sql. |
session.services.explain, language.services.explain |
explainAnalyze |
Runs a statement and returns its plan with actual rows and times; requires explain. |
flag |
currentNamespace |
Reports which database or schema a console is in, so completion follows USE and SET search_path; requires sql. |
session.services.currentNamespace, language.services.currentNamespace |
keepAlive |
Turns on TCP keepalive when asked and answers a ping, so an idle console notices a dropped connection and reconnects. | session.services.keepAlive |
bulkInsert |
Writes batches of rows from an imported file and proposes and creates a table for one; requires transactions. |
session.services.bulkInsert, language.services.bulkInsert |
objects |
Writes the DDL that creates, modifies, renames, truncates and drops tables and other objects from the database tree; requires sql and schemaTree. |
language.services.objects |
serverMessages |
Returns the warnings and notices the server left about a statement, which Output lists under it and the result tab counts. | flag |
sessions |
Lists the server’s sessions with who blocks whom, and cancels or terminates one, for the Sessions view; requires sql or commands, and schemaTree or keyValue. |
session.services.sessions |
routineCall |
Writes the statements that call a function or procedure with the values from Execute Routine, OUT values included; requires sql and schemaTree. |
language.services.routineCall |
commands |
Runs one command of a command language such as Redis’s and returns its reply; the plugin also supplies the language (splitting, classifying, completion). A plugin declares either sql or commands, never both. |
plugin.commandLanguage |
keyValue |
Lists databases and scans keys for the key tree, reads a key into a tab and applies guarded edits to it; requires commands. |
session.services.keyValue |
nodes |
Lists the nodes of a cluster, so a console can run a command on one node or on every primary; requires sql or commands. |
session.services.nodes |
serverInfo |
Reports the server’s statistics and slow log for the Server tab; requires sql or commands. |
session.services.serverInfo |
serverTimeout |
Says what the connected server stops by itself and hands it the statement timeout, so the database stops a statement even when TableCraft cannot; needs no cancel. A server without such a setting has limit: null. |
session.services.serverTimeout |
revisions |
Reads a key at an earlier revision for history, diff and restore. | flag |
watch |
Follows changes to a key or range from now or a past revision, with explicit gaps. | session.services.watch |
leases |
Lists leases with keys and TTL, grants, renews and revokes them. | session.services.leases |
access |
Lists and changes users, roles and permissions, and manages authentication where safe. | session.services.access |
members |
Lists configured endpoints and cluster members, and promotes or removes a member. | session.services.members |
maintenance |
Reports status and alarms, compacts, defragments, snapshots and checks consistency. | session.services.maintenance |
coordination |
Shows holders and queues under configured lock and election prefixes. | session.services.coordination |
bulkTransfer |
Exports a range and imports chunk-atomically, resuming only confirmed boundaries. | session.services.bulkTransfer |
savepoints |
Writes the savepoint statements that let console edits inside an open transaction undo only themselves when one is refused; requires sql and transactions. |
language.services.savepoints |
rowLimit |
Writes a row limit into a plain SELECT, so the server stops after one page; Fetch Next Page and Fetch All run it again with a larger limit; requires sql. |
language.services.rowLimit |
topics |
Lists, describes and reads topics without joining a consumer group, produces, administers topics and tails them live, for the stream tree and topic tabs; requires commands, excludes schemaTree and keyValue. |
session.services.topics |
consumerGroups |
Lists and describes consumer groups with their lag, and previews and applies an offset reset by token; requires commands. |
session.services.consumerGroups |
schemaRegistry |
Lists subjects and versions of a schema registry, checks and registers schemas; answers available: false on a data source without a registry; requires commands. |
session.services.schemaRegistry |
searchIndices |
Lists indices, aliases and data streams, describes their fields, searches with a Lucene or Query DSL query, a sort and a time range, counts, draws a histogram over time and analyzes text, for the index tree and index tabs; requires commands, excludes schemaTree, keyValue and topics. |
session.services.searchIndices |
Write the default export
Section titled “Write the default export”Write the default export with definePlugin and its capabilities as const. The types then
require exactly the declared keys on the session and the language, and type connect’s
configuration from the connection schema.
import { definePlugin, type PluginSession } from "@tablecraft-app/plugin-api";
const CAPABILITIES = ["sql", "cancel", "schemaTree", "transactions"] as const;type Capability = (typeof CAPABILITIES)[number];
class Connection implements PluginSession<Capability> { readonly services: PluginSession<Capability>["services"] = { cancel: { cancel: () => this.#cancel(), reach: { method: "cancel request", reaches: "statement" } }, schemaTree: introspector, transactions: transactions, }; // execute, close, serverVersion …}
export default definePlugin({ id: "example", capabilities: CAPABILITIES, connectionSchema, connect: async (config) => new Connection(await open(connectionSchema.parse(config))), language,});Fill in the manifest
Section titled “Fill in the manifest”The manifest is table-craft-plugin.json. Here is PostgreSQL’s, with most of its connection fields
left out:
{ "id": "postgres", "name": "PostgreSQL", "version": "0.0.0", "apiVersion": "2.4.0", "entry": "index.js", "capabilities": [ "sql", "cancel", "schemaTree", "transactions", "ddl", "explain", "explainAnalyze", "currentNamespace", "keepAlive", "bulkInsert", "objects", "serverMessages", "sessions", "routineCall", "serverTimeout", "savepoints", "rowLimit" ], "highlight": "postgresql", "brands": [{ "id": "postgresql", "name": "PostgreSQL" }], "connection": { "fields": [ { "key": "host", "label": "Host", "kind": "text", "default": "localhost", "required": true }, { "key": "password", "label": "Password", "kind": "password", "secret": true } ], "url": { "schemes": ["postgresql", "postgres"], "form": "server", "parts": { "host": "host", "password": "password" } }, "network": { "host": "host", "port": "port", "connectTimeout": "connectTimeout" } }}brands: the database products the plugin speaks, the default first. Eachidis a Simple Icons slug, which picks the logo TableCraft draws, andnameis what the picker and the tree call it. The New Data Source picker lists one row per brand, and a session’sserverBrandsays which one the server is.connection.fields: draws the connection form. A field’s optionalhint(plugin API 2.1) puts an (i) beside it. Say there what the field does, its unit, and what blank means, such as how a timeout applies.connection.network: names the fields that hold the server’s address (a text host, a number port and optionally a number of seconds to wait). A plugin that declares it gets the SSH tunnel. TableCraft opens the tunnel and hands the plugin127.0.0.1and the forwarded port in those fields, so the plugin itself knows nothing about SSH.connection.tls: names the SSL fields (mode, a select offering every one ofverifyModes, and optionally thecaFile,certFileandkeyFilefile fields and thekeyPassphrasesecret). The dialog draws them under SSL, asks for the passphrase only when the key file is encrypted, and shows the session’stls(protocol and cipher) after Test Connection. Through a tunnelconnectgets the configured host asserverName, which averify-fullcheck must use instead of127.0.0.1.
Describe results
Section titled “Describe results”A plugin’s result columns may name their type class (typeClass: integer, float, decimal,
boolean, temporal, json, bytes or text). The grid then aligns, sorts and exports them by
that class ahead of the type name; SQL Server’s bit, for one, is a boolean.
A plugin that sends the server other text than execute was given, such as a statement with a
hint it added, returns that text as the result’s sent, or passes sent to the PluginError it
throws (plugin API 2.1). The query history and Services then show what reached the server.
Read Oracle and SQL Server scripts
Section titled “Read Oracle and SQL Server scripts”The shared SQL kit in @table-craft/plugin-api/sql also reads Oracle and SQL Server scripts when a
plugin turns on their dialect options: [bracketed] names, q'[…]' and N'…' strings, GO and
/ separator lines, and :1 or @p1 placeholders.
Pass the contract suite
Section titled “Pass the contract suite”A plugin depends on @tablecraft-app/plugin-api and should pass its contract suite,
runPluginContract from @table-craft/plugin-api/testing. The built-in plugins run it against
real databases. See Plugin contract.
Plugin compatibility
Section titled “Plugin compatibility”The plugin API follows semver and stays backward compatible within a major version:
- Set
apiVersionto the version of@tablecraft-app/plugin-apiyou built against. TableCraft with plugin API2.zloads a plugin built for2.ywhenyiszor lower. A plugin built for a newer minor, or another major, is listed as unavailable with the plugin API it needs. - A minor version only adds: new exports, new optional fields and methods, new capabilities. New contract tests apply only to plugins that declare what they test.
- Breaking changes wait for the next major: removing or renaming anything, making something optional required, adding a required member to what a plugin implements or returns, adding a value to what a plugin receives without an opt-in, or changing what a field means.
- Before removal, a member is marked
@deprecatedwith its replacement for at least one major. - A new optional method is called only when your plugin has it or declares its capability, never
because of your
apiVersion.
Publishing to a private registry
Section titled “Publishing to a private registry”A plugin for your company alone can live in your own npm registry, such as GitLab’s package registry, instead of npm. To publish it there:
-
Name the package in a scope your registry serves, such as
@acme/tablecraft-plugin-example. -
Put
table-craft-plugin.jsonand the builtindex.jsin the package, and declare the plugin inpackage.json, asscripts/plugins/pack.tsdoes for the official ones. The id must not be a built-in or official plugin’s id.{"name": "@acme/tablecraft-plugin-example","version": "1.0.0","type": "module","main": "index.js","tableCraft": { "id": "example", "apiVersion": "2.4.0" }} -
Publish it to the registry with
npm publish. -
Tell users the package name and the registry’s address and scope. They add the registry as described in Private registries.
TableCraft reads tableCraft from the tarball when the registry leaves it out of the packument, as
GitLab does, and picks the newest version whose apiVersion it accepts. Pre-releases
(1.1.0-beta.1) install only for users on the beta channel.
Licensing your plugin
Section titled “Licensing your plugin”TableCraft is GPL-3.0-or-later, and @tablecraft-app/plugin-api is MIT. A plugin that talks to
TableCraft only through the plugin API may use any license, open or closed: the
plugin exception grants that on top of the GPL. A plugin that imports
other TableCraft code, such as @table-craft/core or the desktop app, is a derivative of the GPL’d
code and must be GPL-3.0-or-later itself.
From 1.x to 2.0
Section titled “From 1.x to 2.0”Plugin API 2.0 groups everything a capability brings under its key. TableCraft on plugin API 2.0 refuses a plugin built for 1.x. The plugins it downloads update themselves, and one you built or installed from a file shows “Rebuild it for plugin API 2.x”.
Move a plugin to 2.0
Section titled “Move a plugin to 2.0”- Set
apiVersionto2.0.0and wrap the default export indefinePlugin, with the capabilitiesas const. - Move each flat session member under its capability in
services:cancel()andcancelReachbecomeservices.cancel(cancel,reach).introspectorbecomesservices.schemaTree, and itsdefinitionmoves toservices.ddl.transactions,keyspace(nowkeyValue),keyTransfer(nowbulkTransfer),watch,leases,accessandcoordinationmove as they are.ping(),insertRows(),explain(),currentNamespace(),nodes()becomekeepAlive.ping,bulkInsert.insertRows,explain.explain,currentNamespace.currentandnodes.list.serverInfo()andslowLog()becomeserverInfo.infoandserverInfo.slowLog.sessions,serverSessionId,serverInstanceandfindServerInstance()becomeservices.sessionswithownId,ownInstanceandfindOwnInstance().serverTimeoutbecomesservices.serverTimeoutwithlimit(nullwhen the server has no such setting).clustersplits intomembersandmaintenance.
- Move the language’s optional members under
language.services:explainabletoexplain.explainable.namespaceSwitchtocurrentNamespace.importTypeandcreateTabletobulkInsert.objectsandroutineCall(nowroutineCall.call) as they are.savepointtosavepoints.savepoint, declaringsavepoints.
- Implement what became required:
splitStream,signatureAt,inspect, andselectSourceon the language,reachoncancel,slowLogonserverInfo. The SQL kit’ssqlStatementStream,sqlCompleter,sqlInspectorandsqlSavepointssupply them. - Leave out every key you do not declare. A service without its capability is refused like a capability without its service.
serviceProblems in @tablecraft-app/plugin-api says what that check finds, and the contract
suite runs it.
