Develop and Submit DBX Plugins

DBX plugins are independently installed .dbxp packages that can contribute connection types, workbenches, filesystems, and native sidecars. Plugin source, the DBX plugin platform, and the official Marketplace catalog are owned by different repositories.

Which Repository Receives the Change

DBX-maintained plugins that need an independent release cadence should normally use separate source repositories as well. Only tightly coupled host examples, SDK verification projects, or components explicitly accepted by maintainers belong in t8y2/dbx.

Plugin Project Layout

my-plugin/
├── manifest.json
├── dbx-plugin.toml
├── assets/
├── ui/
├── backend/                       # absent from the frontend template
├── .github/workflows/
│   └── plugin-release.yml
└── dist/                          # generated; do not commit

• manifest.json declares identity, version, permissions, entrypoints, and contributions.
• ui/ runs in a sandboxed workbench and talks to DBX through Host APIs.
• backend/ is an optional native sidecar. Rust and Go SDKs are provided, while other languages may implement the DBX JSON-RPC protocol directly.
• .dbxp is an installable artifact, not the source repository.
• Frontend-only plugins can publish one universal package. Native sidecars require packages for each operating-system and CPU target.

Workbench Context Contract

Workbench context is a JSON data snapshot across the DBX/plugin boundary. The host recursively removes Vue reactivity and sends an independent copy, so plugins must not expect Vue refs, proxies, DOM nodes, functions, component instances, or credentials.

Context may contain null, booleans, finite numbers, strings, arrays, and plain objects. Undefined object properties are omitted and undefined array entries become null. Dates, Maps, Sets, symbols, bigints, non-finite numbers, circular references, and custom class instances are rejected with an error. The UTF-8 encoded context is limited to 2 MiB.

Connection provider fields using binding: "config" are persisted in external_config; fields using binding: "secret" are persisted in the Secret Store. Plugin connection configuration keeps external_config through create, edit, save, and reconnect flows.

Create a Plugin

Install the precompiled CLI without Rust or a DBX source checkout:

npm install --global @dbx-app/plugin-cli
dbx-plugin --help

Or run it directly through npx:

npx @dbx-app/plugin-cli create my-ui-plugin --template frontend

The npm package selects the precompiled binary for the current platform and bundles the matching Rust and Go plugin SDK sources. Frontend-only plugins do not need Rust or Go; native toolchains are required only to compile the plugin's own sidecar.

Create a project:

# Frontend only and cross-platform
dbx-plugin create my-ui-plugin --template frontend

# Rust sidecar plus frontend
dbx-plugin create my-rust-plugin --template rust

# Go sidecar plus frontend
dbx-plugin create my-go-plugin --template go

Develop, test, and version the generated project in the plugin's own source repository. Do not copy an ordinary plugin source tree into t8y2/dbx merely to publish it.

Build Review Candidates

From the plugin project root, run:

dbx-plugin package .

The command produces unsigned review candidates only:

dist/<plugin-id>-<version>-<target>.dbxp
dist/<plugin-id>-<version>-<target>.artifact.json

Official plugin authors do not create or possess the DBX Store private key. The generated GitHub Release workflow builds candidates for each target and merges their metadata into release-candidates.json.

To install an unsigned package during local development, explicitly enable Allow unsigned development packages in Plugin Center. This option never relaxes official Marketplace verification.

Complete Official Marketplace Flow

Step 1: Publish Source and a Candidate Release

Create a version tag and GitHub Release in the plugin's source repository. The Release should contain:

• one unsigned .dbxp candidate for each supported target;
• the corresponding .artifact.json files;
• merged release-candidates.json;
• release notes and the matching source tag.

Candidate packages may live in GitHub Releases, a CDN, or object storage. Do not commit .dbxp binaries to Git history.

Step 2: Open a Review Issue in dbx-store

Open t8y2/dbx-store Issues, choose Plugin submission, and provide:

• plugin ID, version, and publisher;
• source repository and exact tag;
• the HTTPS URL of release-candidates.json;
• permissions, data access, network access, and native-sidecar behavior;
• license, privacy policy, and support links.

The Issue is the pre-signing review entrypoint. Do not submit the plugin source to t8y2/dbx, and do not invent an official signingKeyId yourself.

Step 3: DBX Store Reviews and Signs

Maintainers review the source, Manifest, permissions, candidate SHA-256 values, sizes, and native behavior. After approval, the protected DBX Store workflow:

1. downloads the candidate using its reviewed SHA-256 and size;
2. confirms that it is unsigned and matches the expected plugin ID and version;
3. adds an Ed25519 signature using the DBX Store repository key;
4. publishes the final .dbxp, final artifact metadata, and signing receipt.

Plugin authors never receive the official repository private key.

Step 4: Open the Listing PR Against dbx-store

After receiving final signed artifact metadata, fork t8y2/dbx-store and add or update:

publishers/<publisher-id>.json    # only for a publisher's first submission
plugins/<plugin-id>.json
catalog/index.json                # generated by validation

Run:

node scripts/validate.mjs

Then open the pull request with:

Base repository: t8y2/dbx-store
Base branch: main

Do not include the following in a listing PR:

• .dbxp binaries;
• a copied plugin source tree;
• Ed25519 private keys, tokens, or download credentials;
• unsigned candidate URLs as final install artifacts;
• a self-assigned verified: true value.

Update an Existing Plugin

Every update uses a new semantic version. Existing Release assets cannot be replaced:

1. Publish a new source tag and candidate Release in the plugin source repository.
2. Open a new Plugin submission Issue in t8y2/dbx-store and reference the existing plugin and new version.
3. Wait for the new candidates to complete review and repository signing.
4. Open a PR against t8y2/dbx-store that updates plugins/<plugin-id>.json.

Fix plugin-code problems in the plugin source repository. Only catalog metadata, review status, final URLs, hashes, sizes, and Marketplace copy belong in dbx-store.

Signatures and Publisher Identity

DBX currently uses one repository signature:

• publisher records authorship and Marketplace ownership;
• signingKeyId identifies the repository key that published the final installable package;
• DBX Store reviews and signs official plugins centrally;
• custom and private repository operators manage their own repository keys;
• developer signatures and dual signatures are not current listing requirements.

Human review determines whether a plugin may appear in the Marketplace. Ed25519 repository signing ensures that the reviewed package was not replaced afterward. A signature does not replace source review and is not an operating-system sandbox for native sidecars.

Related Documentation

• JDBC Plugin and Database Drivers
• Contribute to the DBX Core Repository
• t8y2/dbx plugin platform source
• t8y2/dbx-store official Marketplace repository