Skip to main content
The onPremConnection function creates a connection for components that need to communicate with resources behind a firewall or inside a private network. When an on-prem agent is configured, Prismatic overwrites the connection’s host and port values with the local tunnel endpoint established by the agent.
On-prem connections require required host and port inputs with onPremControlled: true. These values are automatically overridden by the on-prem agent at runtime — do not use them as configurable user fields.

​
Function signature

function onPremConnection<T extends OnPremConnectionDefinition>(definition: T): T

​
Parameters

​
definition
OnPremConnectionDefinition
required
An object describing the on-premises connection. See fields below.

​
OnPremConnectionDefinition fields

​
definition.key
string
required
Unique programmatic identifier for this connection type.
​
definition.display
ConnectionDisplayDefinition
required
Controls how this connection appears in the Prismatic UI.
​
definition.inputs.host
OnPremConnectionInput
required
The hostname or IP address of the on-premises resource. Must have onPremControlled: true. When the on-prem agent is active, this value is overridden with the agent tunnel’s local endpoint.
​
definition.inputs.port
OnPremConnectionInput
required
The port number of the on-premises resource. Must have onPremControlled: true. When the on-prem agent is active, this value is overridden with the agent tunnel’s local port.
​
definition.inputs[key]
ConnectionInput
Additional connection inputs (e.g., credentials, database name) beyond host and port. These follow the standard ConnectionInput shape.

​
OnPremConnectionInput type

OnPremConnectionInput extends ConnectionInput with one additional required field: 
type OnPremConnectionInput = {
  onPremControlled: true;
} & ConnectionInput;
The onPremControlled: true flag tells the Prismatic platform that this field’s value will be overridden by the on-prem agent when the connection is used in an on-prem context.

​
Return type

Returns the same OnPremConnectionDefinition object passed in, after validation. Pass the returned value to the connections array in component.

​
Example

import { onPremConnection, action, input, component } from "@prismatic-io/spectral";

export const databaseConnection = onPremConnection({
  key: "databaseConnection",
  display: {
    label: "Database (On-Prem)",
    description: "Connect to an on-premises database through the Prismatic agent",
  },
  inputs: {
    host: {
      label: "Host",
      type: "string",
      required: true,
      onPremControlled: true,
      placeholder: "db.internal.example.com",
      comments: "Overridden by the on-prem agent when active",
    },
    port: {
      label: "Port",
      type: "string",
      required: true,
      onPremControlled: true,
      placeholder: "5432",
      comments: "Overridden by the on-prem agent when active",
    },
    database: {
      label: "Database Name",
      type: "string",
      required: true,
      placeholder: "mydb",
    },
    username: {
      label: "Username",
      type: "string",
      required: true,
      placeholder: "db_user",
    },
    password: {
      label: "Password",
      type: "password",
      required: true,
      writeOnly: true,
      placeholder: "Your database password",
    },
  },
});

const queryDatabase = action({
  display: {
    label: "Query Database",
    description: "Execute a SQL query against the on-premises database",
  },
  inputs: {
    connection: input({ label: "Connection", type: "connection", required: true }),
    query: input({
      label: "SQL Query",
      type: "code",
      language: "sql",
      required: true,
      placeholder: "SELECT * FROM orders WHERE status = 'pending'",
    }),
  },
  perform: async (context, params) => {
    const { host, port, database, username, password } = params.connection.fields as {
      host: string;
      port: string;
      database: string;
      username: string;
      password: string;
    };

    context.logger.info(`Connecting to ${host}:${port}/${database}`);

    // Connect to the database using the (potentially tunneled) host/port
    const results = await executeQuery(`${host}:${port}`, database, username, password, params.query);

    return { data: results };
  },
});

async function executeQuery(
  endpoint: string,
  database: string,
  username: string,
  password: string,
  query: string
) {
  // Database query logic
  return [];
}

export default component({
  key: "onPremDatabaseComponent",
  display: {
    label: "On-Prem Database",
    description: "Query an on-premises database",
    iconPath: "icon.png",
  },
  actions: { queryDatabase },
  connections: [databaseConnection],
});

Build docs developers (and LLMs) love

Get started for freeTalk to us