Postgres

What this endpoint does

A Postgres endpoint selects a table or a supported SQL query in a PostgreSQL database. Pipelines and supported reads use it to retrieve rows without copying database credentials into each pipeline. A separate write endpoint can select an output table when the installed capability supports writes.

Like all data endpoints, it belongs to a workspace and can be referenced by projects in that workspace, subject to permissions. Saving it configures access; it does not start ingestion.

Directions and supported operations

Each endpoint selects one installed capability. Create separate source, destination and fact-store endpoints even when they connect to the same database. A source endpoint is not automatically a destination.

The writer implements append, replace, upsert, update and delete. Keyed mutations require an actual database primary key; a primary-key hint on an endpoint does not create a constraint. Replacement recreates the table. Commits are per row, not one transaction covering a whole run. Policy writes reject foreign-key relationships and triggers.

Published-contract limitation: the current catalog target advertises append, upsert and overwrite, while the writer uses replace rather than overwrite. Do not treat these names as interchangeable. The complete destination example below uses append, which both support. Other mutations require a compatible installed contract and execution path; changing JSON alone does not enable them.

Plugin used

This plugin provides separate read and write capabilities. Select read for Ingress or write for Egress; the example below installs read first and then explains how to install write. Installation steps for this example are included below. The Postgres installation guide provides optional further detail. Connection details and credentials stay on the installation; the endpoint selects a particular target through that installed capability.

What you need

• A Semogram account with workspace access and permission to manage endpoints
• An existing matching installation, or the connection details to create one using the steps below
• Database access to a test table, its schema/table names and one known row for comparison

Read example setup

This example assumes your database already has a table named orders in the schema named public, with a unique order_id column. public.orders is the database’s schema-qualified table name. We choose orders as the endpoint name in Semogram and sales as its grouping namespace; both are labels you choose, not database objects. Use your own existing table and a useful endpoint name.

Install and configure the plugin

1. Open Plugins in this workspace and select Explore.
2. Find Postgres, inspect its publisher/version and select its read capability.
3. Name the installation and fill its connection settings using your actual external-system details.
4. Save and run the supported connection check. Fix any reported error before creating the endpoint.

Example installation configuration:

Install the plugin described on this page in this workspace. Discover its catalog entry, select the matching capability and propose the installation using the connection settings shown here. Ask me to enter credentials in protected installation fields. Show the selected plugin/version, capability and non-secret settings before saving.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "plugin_installation_create",
    "arguments": {
      "capabilityClass": "<MATCHING_CAPABILITY_CLASS>",
      "discoveryId": "<DISCOVERY_ID_FROM_CATALOG>",
      "name": "<INSTALLATION_NAME>",
      "config": {
        "host": "YOUR_DATABASE_HOST",
        "port": 5432,
        "database": "YOUR_DATABASE",
        "user": "YOUR_DATABASE_USER",
        "password": "YOUR_PASSWORD",
        "ssl": true
      },
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_INSTALLATION>"
    }
  }
}

Replace every YOUR_… value. Enter credentials only in protected installation configuration. The configuration above is separate from the endpoint target below; selecting a target does not create or authenticate the connection.

Prepare example data

In a test database, use your database's SQL client to create a tiny example table. The configured database user must have permission to read it.

CREATE TABLE public.orders (
  order_id integer PRIMARY KEY,
  total numeric(12,2),
  placed_at timestamptz
);
INSERT INTO public.orders VALUES
  (1, 120.00, '2026-01-01T10:00:00Z'),
  (2, 75.50, '2026-01-02T10:00:00Z');

Use a fresh test table/database if public.orders already exists. If you use a different table, update the target below to match it.

Use the assistant

Open Data Endpoints → New data endpoint in the workspace. Describe your actual target and choose a name for the endpoint. For the example above, you could ask:

Create a source endpoint named orders in namespace sales.
Use our installed Postgres read capability with contract source_stream
and set these target fields:
Schema: public
Table: orders
Review the proposed connection and target before saving.

Replace example values with your own. Give the assistant the installed connection reference; keep credentials in protected installation settings.

Configure manually

Choose Edit manually, select the matching installed capability and configure:

Create the endpoint described on this page using these settings:
name: <ENDPOINT_NAME_FROM_THIS_EXAMPLE>
namespace: <ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>
role: source
contractKind: source_stream
target / schema: public
target / table: orders
pluginCapabilityInstallationId: <INSTALLED_CAPABILITY_UUID>
Use the actual installed capability and the endpoint name/namespace selected in this example. Show the proposed direction, connection and target before saving. Keep credentials on the installation.

curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_ENDPOINT>" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
  "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
  "role": "source",
  "contractKind": "source_stream",
  "target": {
    "schema": "public",
    "table": "orders"
  },
  "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
      "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
      "role": "source",
      "contractKind": "source_stream",
      "target": {
        "schema": "public",
        "table": "orders"
      },
      "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

Set the primary-key hint to order_id after checking uniqueness and nulls. Add a useful description, owner and expected freshness. Save in the workspace. Inspect the installed version’s contract before adding optional settings.

Verify the endpoint

1. Open the saved endpoint and run its supported connection check and schema inspection.
2. Read a small sample through the supported preview. If the connector has no preview, select a project, open Pipeline Studio and create a pipeline with a source node referencing this endpoint.
3. Configure a bounded test input using the connector's supported settings, validate the pipeline, save a version and run it.
4. Inspect returned records or the completed run's output. Compare expected keys and values with the example fixture before scheduling anything.

Compare order IDs, totals, timestamps and nulls with the database. One table read does not prove access to other tables.

Check connectivity, target validity and actual data separately. Saving does not import records or schedule execution.

Write example: copy two orders into a test output table

This example uses the two-row public.orders fixture created above. The source endpoint is named orders; the destination will be named verified_orders, grouped under namespace sales, and will target a different physical table, public.verified_orders. Endpoint names are Semogram labels; public and the table names are PostgreSQL objects.

1. In workspace Plugins → Explore, select Postgres → write and install it. Enter the same host, port, database and TLS settings shown above, with a database user authorized for the output table. Read and write installations can use different least-privilege users.
2. In your test database SQL client, create an empty output table:

CREATE TABLE public.verified_orders (
  order_id integer PRIMARY KEY,
  total numeric(12,2),
  placed_at timestamptz
);

3. Grant the installation user the required schema and output-table access. The writer also performs table/schema setup; its connection needs permission to create tables and to alter the test output table. The writer enables row-level security on that table; use its owner or an explicitly authorized database identity when verifying the output. Keep this fixture in a test database where those operations are authorized.
4. Open workspace Data Endpoints → New data endpoint → Edit manually. Choose name verified_orders, namespace sales, Egress (role destination), the installed Postgres write capability and contract write.
5. Set the target and save:

Create the endpoint described on this page using these settings:
name: <ENDPOINT_NAME_FROM_THIS_EXAMPLE>
namespace: <ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>
role: destination
contractKind: write
target / schema: public
target / table: verified_orders
target / writeMode: append
pluginCapabilityInstallationId: <INSTALLED_CAPABILITY_UUID>
Use the actual installed capability and the endpoint name/namespace selected in this example. Show the proposed direction, connection and target before saving. Keep credentials on the installation.

curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
  --header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
  --header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_ENDPOINT>" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
  "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
  "role": "destination",
  "contractKind": "write",
  "target": {
    "schema": "public",
    "table": "verified_orders",
    "writeMode": "append"
  },
  "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>"
}
JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "source_create",
    "arguments": {
      "name": "<ENDPOINT_NAME_FROM_THIS_EXAMPLE>",
      "namespace": "<ENDPOINT_NAMESPACE_FROM_THIS_EXAMPLE>",
      "role": "destination",
      "contractKind": "write",
      "target": {
        "schema": "public",
        "table": "verified_orders",
        "writeMode": "append"
      },
      "pluginCapabilityInstallationId": "<INSTALLED_CAPABILITY_UUID>",
      "idempotencyKey": "<UNIQUE_KEY_FOR_THIS_ENDPOINT>"
    }
  }
}

6. Select a project in this workspace and open Pipeline Studio. Create a pipeline with an ingress node referencing orders and an egress node referencing verified_orders; connect the source output to the destination input. Use only the two fixture rows. Inspect the resolved target, append mode and applicable write policy/permissions; validate, save a version and execute once.
7. Inspect the completed run and query the external table:

SELECT order_id, total, placed_at
FROM public.verified_orders ORDER BY order_id;

Expect IDs 1 and 2 with totals 120.00 and 75.50. Also read the original public.orders table to confirm the source was unchanged. A failed run may have committed some rows: inspect the output before retrying. Repeating append with these primary keys can fail with a duplicate-key error; it is not an automatic upsert. To repeat this fixture, clear only the dedicated test output table using your database tools, then run once again.

A prompt alternative is: “Create an Egress endpoint named verified_orders in namespace sales using the installed Postgres write capability, contract write, and target schema public, table verified_orders, writeMode append.” Review the actual capability, target and policy before executing the pipeline.

Manage the endpoint

For a reviewed SQL source, select the supported source_query contract and use a target such as {"query":"SELECT order_id, total FROM public.orders LIMIT 100"}. Query targets differ from table targets.

Keep credentials on the installation. Review consumers before replacing capabilities, changing targets or deleting endpoints.

FAQ

Why does verification fail?

Check table/schema spelling, grants, TLS and runtime reachability

Can another project use it?

Yes, within the same workspace and subject to permissions. The endpoint remains workspace-scoped.

What comes after verification?

Use sources in a bounded pipeline, destinations in a supported write flow, and stores in ontology bindings. Inspect real output before scheduling recurring work.