Plugin API Reference

Beta Feature

The plugin system is in beta (available in Beekeeper Studio 5.3+). Things might change, but we'd love your feedback!

The Beekeeper Studio Plugin API is accessible through the @beekeeperstudio/plugin package. The API provides communication between your plugin and the main application.

Installation

npmyarn

npm install @beekeeperstudio/plugin

yarn add @beekeeperstudio/plugin

Core Functions

Function	Description
`request(name, args?)`	Send requests to Beekeeper Studio to retrieve data or execute actions. Returns a Promise.
`notify(name, args)`	Send one-way notifications to the main application without expecting a response.
`addNotificationListener(name, callback)`	Listen for notifications from the main application (like theme changes).
`setDebugComms(enabled)`	Enable or disable debug logging for plugin communication. Useful for development.

Debugging

setDebugComms

Enable debug logging to see all communication between your plugin and Beekeeper Studio. This is helpful when developing plugins to understand what messages are being sent and received.

Usage:

// Enable debug logging
setDebugComms(true);

// Now all communication will be logged to the browser console
const tables = await getTables();

// Disable debug logging
setDebugComms(false);

Arguments Schema:

{ enabled: boolean }

Development Workflow

Enable debug communications early in your development process to see exactly what data is being exchanged. This makes it much easier to troubleshoot issues and understand the plugin API behavior.

Request Methods

getTables

Get a list of tables from the current database.

Usage:

// Get all tables
const tables = await getTables();

// Get tables from specific schema
const tables = await getTables({ schema: 'public' });

Example Response:

[
  {
    name: "users",
    schema: "public"
  },
  {
    name: "orders",
    schema: "public"
  }
]

Arguments Schema:

{ schema?: string }

Response Schema:

{ name: string; schema?: string }[]

getColumns

Get column information for a specific table.

Usage:

const columns = await getColumns({
  table: 'users',
  schema: 'public'
});

Example Response:

[
  {
    name: "id",
    type: "integer"
  },
  {
    name: "email",
    type: "varchar"
  }
]

Arguments Schema:

{ table: string; schema?: string }

Response Schema:

{ name: string; type: string }[]

runQuery

Execute a SQL query against the current database.

No Query Sanitization

The query will be executed exactly as provided with no modification or sanitization. Always validate and sanitize user input before including it in queries to prevent unwanted actions.

Usage:

const result = await runQuery({
  query: 'SELECT * FROM users WHERE active = true LIMIT 10'
});

Example Response:

{
  results: [
    {
      fields: [
        { id: "1", name: "id", dataType: "integer" },
        { id: "2", name: "email", dataType: "varchar" }
      ],
      rows: [
        { id: 1, email: "user1@example.com" },
        { id: 2, email: "user2@example.com" }
      ]
    }
  ]
}

Arguments Schema:

{ query: string }

Response Schema:

{
  results: {
    fields: { id: string; name: string; dataType?: string }[];
    rows: Record<string, unknown>[];
  }[];
  error?: unknown;
}

getConnectionInfo

Get information about the current database connection.

Usage:

const connectionInfo = await getConnectionInfo();

Example Response:

{
  connectionType: "postgresql",
  databaseName: "myapp_production",
  defaultSchema: "public",
  readOnlyMode: false
}

Response Schema:

{
  connectionType: string;
  databaseName: string;
  defaultSchema?: string;
  readOnlyMode: boolean;
}

Supported Connection Types:

Value	Database
`postgresql`	PostgreSQL
`mysql`	MySQL
`mariadb`	MariaDB
`sqlite`	SQLite
`sqlserver`	SQL Server
`oracle`	Oracle Database
`mongodb`	MongoDB
`cassandra`	Apache Cassandra
`clickhouse`	ClickHouse
`firebird`	Firebird
`bigquery`	Google BigQuery
`redshift`	Amazon Redshift
`duckdb`	DuckDB
`libsql`	LibSQL

getAllTabs

Get information about all open tabs.

Usage:

const tabs = await getAllTabs();

Example Response:

[
  {
    id: 123,
    title: "My Plugin Tab",
    type: "plugin"
  },
  {
    id: 124,
    title: "Query #1",
    type: "query"
  }
]

Response Schema:

{
  type: string;
  id: number;
  title: string;
}[]

setTabTitle

Set the title of the current plugin tab.

Usage:

await setTabTitle({ title: 'Data Analysis Tool' });

Arguments Schema:

{ title: string }

expandTableResult

Display query results in the bottom table panel (shell-type tabs only).

Usage:

await expandTableResult({
  results: [
    {
      fields: [
        { id: "1", name: 'id', dataType: 'integer' },
        { id: "2", name: 'name', dataType: 'varchar' }
      ],
      rows: [
        { id: 1, name: 'John', age: 30 }
      ]
    }
  ]
});

Arguments Schema:

{
  results: {
    fields: { id: string; name: string; dataType?: string }[];
    rows: Record<string, unknown>[];
  }[]
}

Table Display Tips

Results will replace any existing table data
Datasets are not paginated. Be aware of large datasets!

getViewState

Get the current state of your view instance.

Learn more about View State here.

Usage:

const state = await getViewState();
console.log('Current state:', state);

Response Schema:

any

setViewState

Store state for your view instance.

Learn about more about View State here.

Usage:

await setViewState({
  state: {
    selectedTable: 'users',
    filters: ['active = true']
  }
});

Arguments Schema:

any

Notifications

themeChanged

Fired when the application theme changes.

Usage:

addNotificationListener('themeChanged', (args) => {
  // Apply new theme to your plugin
  document.documentElement.style.setProperty('--primary-color', args.palette.primary);
  document.body.className = `theme-${args.type}`;
});

Schema:

{
  palette: Record<string, string>;
  cssString: string;
  type: "dark" | "light";
}

windowEvent

Internal Use

This notification is primarily for internal use.

Fired for various window events.

Usage:

addNotificationListener('windowEvent', (args) => {
  if (args.eventType === 'resize') {
    // Handle window resize
    adjustLayout();
  }
});

Schema:

{
  eventType: string;
  eventClass: "MouseEvent" | "KeyboardEvent" | "PointerEvent" | "Event";
  eventInitOptions: MouseEventInit | KeyboardEventInit | PointerEventInit;
}

Type Definitions

Result

Property	Type	Description
`rows`	`object[]`	Array of result rows
`fields`	`Field[]`	Array of field definitions
`rowCount`	`number`	Number of rows returned
`affectedRows`	`number`	Number of rows affected (for INSERT/UPDATE/DELETE)

Field

Property	Type	Description
`name`	`string`	Column name
`dataType`	`string`	Column data type

Column

Property	Type	Description
`name`	`string`	Column name
`dataType`	`string`	Column data type
`nullable`	`boolean`	Whether column allows NULL values
`primaryKey`	`boolean`	Whether column is part of primary key
`defaultValue`	`any`	Default value for the column

Table

Property	Type	Description
`name`	`string`	Table name
`schema`	`string`	Schema name
`entityType`	`string`	Type of entity (typically "table")

Tab

Property	Type	Description
`id`	`string`	Unique tab identifier
`title`	`string`	Tab display title
`type`	`string`	Tab type ("plugin", "query", etc.)
`active`	`boolean`	Whether tab is currently active