Extensions

Overview

Monospace connects to PostgreSQL, MySQL, and other databases out of the box. Your data doesn't always live in a database, though. Customers sit in Stripe, tickets in a SaaS tool, inventory behind an internal API.

Extensions close that gap. An extension is code you write and install on your Monospace instance, your running Monospace deployment, to teach it something new. Once installed, what it adds works like the built-in parts of Monospace: callers use the same REST API, SDK, and Studio, under the same roles and permissions.

What You Can Build

Today you can build data connector extensions. A data connector teaches Monospace how to read, and optionally write, a system it has no built-in connector for. The system's objects show up as collections in a workspace.

A few examples:

• Show Stripe customers, products, and prices next to the orders in your own database.
• Expose an internal service's API as collections, so teams query it through Monospace instead of calling it directly.
• Browse a public dataset, such as the Art Institute of Chicago's collection, in Studio.

A data connector doesn't copy anything. Monospace checks each request first and rejects what the data source doesn't offer. When it accepts a request and has no cached answer for it, it sends the request to the connector. The connector answers, calling the external data source when it needs data, or refuses the request. Permission rules reach the connector as part of the request's filter, and Monospace doesn't re-check the items (single data objects) the connector returns, so a connector must apply every filter it receives. See Data Connectors to decide whether your system is a good fit.

Each kind of extension has its own section in these docs.

How It Works

Every extension follows the same path from code to a running capability:

1. Write it. Create a project with the Monospace CLI. You describe the extension in a small config file and write its code in TypeScript.
2. Build it. The CLI validates your config and bundles your code into a build: the files your instance loads. It doesn't type-check your TypeScript, so run the project's typecheck script as well.
3. Install it. Copy the build into your instance's extensions directory. Monospace is self-hosted, so installing is a file operation on your own server.
4. Use it. Your instance loads the extension. For a data connector, you then add it as a data source in a workspace, approve the hosts it may reach, and its collections appear.

The code runs inside your instance, isolated from Monospace itself. A data connector can reach only the hosts you approve for it, and every other network request fails.

Start Building

• Data Connector Quickstart: build a read-only data connector for the Art Institute of Chicago API, install it, and query it
• Build a Stripe Data Connector: a larger Stripe connector with writes, walked through in excerpts
• Install and Manage Extensions: where your instance loads extensions from, and how to update and remove them

For the exact file formats and commands, see Extension Config and Manifest and the CLI reference.

Stability

Extensions are in preview. The extension kit, CLI, manifest format, and data connector contract can change in breaking ways between releases. When a release breaks an extension, its release notes include upgrade instructions. Use extensions in non-production environments only.

We're expanding support for data connector extensions and expect to stabilize the surface in the coming releases. If you build a connector, share your feedback, especially on external data sources that don't fit the contract.

See Also

• Data Connectors: how data connectors work and whether your system fits
• Data Model: collections, fields, and relations
• Connectors: the built-in database connectors