> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase Integration

> Sync your Clustr referral intelligence to a table in your own Supabase / Postgres database

Export your referral intelligence to a table in **your own** Supabase (or any Postgres) database. After every enrichment job, Clustr upserts new and updated opportunities into the table, keeping your warehouse and BI tools current.

It's a **data export**, not an OAuth app: you connect with a Postgres connection string, and Clustr only ever writes to the one table it manages.

<Note>
  Connecting Supabase is **admin-only**, under **Integrations → Apps → Supabase/Postgres** in the dashboard.
</Note>

## Connect Supabase

Have your Supabase Postgres connection string ready, then run the three-step wizard.

<Steps>
  <Step title="Paste your connection string">
    In Supabase, go to **Settings → Database → Connection string** and copy the URI:

    ```
    postgres://postgres:<password>@db.<ref>.supabase.co:5432/postgres
    ```

    Paste it into Clustr and click **Continue**. Both the direct connection (`5432`) and the pooler (`6543`) work.

    <Note>
      The string includes your password — Clustr stores it encrypted and uses it only to write the export table. The host must be a Supabase host (`db.<ref>.supabase.co` or `*.pooler.supabase.com`).
    </Note>
  </Step>

  <Step title="Choose a destination schema">
    **Use existing** (pick a schema Clustr found) or **Create new** (defaults to `clustr`; names must be lowercase letters, digits, and underscores, starting with a letter or underscore). Click **Continue**.
  </Step>

  <Step title="Confirm the table and sync">
    Clustr checks `<schema>.clustr_referral_paths` and either creates it, reuses it, or — on a column **shape mismatch** — asks you to pick another schema or drop the table. Click **Connect & sync** to save the connection and run the first full export.
  </Step>
</Steps>

After the initial sync, Clustr pushes new and updated opportunities at the end of **every enrichment job** automatically.

## How It Works

Clustr writes a single table, **`<schema>.clustr_referral_paths`** — one flat, denormalized row per opportunity. Rows are upserted on `id` (`INSERT … ON CONFLICT (id) DO UPDATE`), so re-syncing never duplicates, and a full sync also removes opportunities that no longer exist in Clustr. Because it's keyed and idempotent, the table is safe to query live, build views on, or point a BI dashboard at.

## Settings

The Supabase panel shows connection status and sync controls.

| Control               | Description                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Connection status** | Destination host, `<schema>.clustr_referral_paths`, and last sync time.                                        |
| **Auto-sync**         | Every enrichment job upserts new/updated opportunities automatically.                                          |
| **Sync now**          | Trigger a manual full sync on demand.                                                                          |
| **Sync history**      | Recent export runs with status and row counts.                                                                 |
| **Disconnect**        | Removes the saved connection and stops syncs. Data already in Supabase is **not** affected; reconnect anytime. |

## Table Schema

`clustr_referral_paths` is keyed on `id` (used for upserts); all other fields are stored as `text` so the export never fails on type coercion. Full column reference:

<AccordionGroup>
  <Accordion title="Keys & metadata">
    | Column        | Description                   |
    | ------------- | ----------------------------- |
    | `id`          | Opportunity ID (primary key)  |
    | `tenant_id`   | Your Clustr tenant ID         |
    | `exported_at` | When the row was last written |
    | `source_app`  | Always `clustr`               |
  </Accordion>

  <Accordion title="Contact (client)">
    | Column                          | Description                                                                                       |
    | ------------------------------- | ------------------------------------------------------------------------------------------------- |
    | `contact_first_name`            | Connector's first name                                                                            |
    | `contact_last_name`             | Connector's last name                                                                             |
    | `contact_job_title`             | Connector's job title                                                                             |
    | `contact_company`               | Connector's company                                                                               |
    | `contact_linkedin_url`          | Connector's LinkedIn URL                                                                          |
    | `contact_linkedin_urn`          | Connector's LinkedIn URN, the stable member identifier (e.g. `ACoAA…`). Empty when not available. |
    | `contact_tags`                  | Tags on the contact                                                                               |
    | `contact_in_crm`                | Whether the contact exists in your CRM                                                            |
    | `contact_crm_id`                | The contact's record ID in your CRM. Empty when not matched.                                      |
    | `contact_crm_provider`          | Which CRM the ID is from (`hubspot`, `salesforce`, or `attio`)                                    |
    | `contact_associated_deals`      | Deals associated with the contact                                                                 |
    | `contact_associated_deal_stage` | Stage of associated deals                                                                         |
    | `contact_recent_activities`     | Recent CRM activity                                                                               |
  </Accordion>

  <Accordion title="Relationship quality">
    | Column                           | Description                                |
    | -------------------------------- | ------------------------------------------ |
    | `relationship_quality_score_pct` | Confidence score for the referral path (%) |
  </Accordion>

  <Accordion title="Prospect">
    | Column                           | Description                                                                                      |
    | -------------------------------- | ------------------------------------------------------------------------------------------------ |
    | `prospect_first_name`            | Prospect's first name                                                                            |
    | `prospect_last_name`             | Prospect's last name                                                                             |
    | `prospect_seniority_level`       | Prospect's seniority                                                                             |
    | `prospect_profile_headline`      | Prospect's profile headline                                                                      |
    | `prospect_job_title`             | Prospect's job title                                                                             |
    | `prospect_linkedin_url`          | Prospect's LinkedIn URL                                                                          |
    | `prospect_linkedin_urn`          | Prospect's LinkedIn URN, the stable member identifier (e.g. `ACoAA…`). Empty when not available. |
    | `prospect_in_crm`                | Whether the prospect exists in your CRM                                                          |
    | `prospect_crm_id`                | The prospect's record ID in your CRM. Empty when not matched.                                    |
    | `prospect_crm_provider`          | Which CRM the ID is from (`hubspot`, `salesforce`, or `attio`)                                   |
    | `prospect_associated_deals`      | Deals associated with the prospect                                                               |
    | `prospect_associated_deal_stage` | Stage of associated deals                                                                        |
    | `prospect_recent_activities`     | Recent CRM activity                                                                              |
  </Accordion>

  <Accordion title="Prospect company">
    | Column                                  | Description                                                    |
    | --------------------------------------- | -------------------------------------------------------------- |
    | `prospect_company_name`                 | Company name                                                   |
    | `prospect_company_linkedin_url`         | Company LinkedIn URL                                           |
    | `prospect_company_linkedin_numeric_id`  | Company LinkedIn numeric ID                                    |
    | `prospect_company_linkedin_vanity_name` | Company LinkedIn vanity name                                   |
    | `prospect_company_crm_id`               | The company's record ID in your CRM. Empty when not matched.   |
    | `prospect_company_crm_provider`         | Which CRM the ID is from (`hubspot`, `salesforce`, or `attio`) |
    | `prospect_company_domain`               | Company domain                                                 |
    | `prospect_company_industry`             | Company industry                                               |
    | `prospect_company_size`                 | Company size                                                   |
    | `prospect_company_revenue`              | Company revenue                                                |
    | `prospect_country`                      | Prospect's country                                             |
  </Accordion>

  <Accordion title="Engagement">
    | Column                        | Description                        |
    | ----------------------------- | ---------------------------------- |
    | `last_engagement_type`        | Type of the most recent engagement |
    | `last_engagement_url`         | Link to the engagement             |
    | `last_engagement_context_url` | Link to the engagement context     |
    | `last_engagement_date`        | Date of the most recent engagement |
    | `total_engagements_found`     | Total engagements found            |
    | `full_engagement_history`     | Full engagement history            |
  </Accordion>

  <Accordion title="Shared experience">
    | Column                            | Description                             |
    | --------------------------------- | --------------------------------------- |
    | `common_company`                  | Company shared by contact and prospect  |
    | `overlap_in_months`               | Months of overlap at the shared company |
    | `shared_experience_company`       | Shared experience company               |
    | `shared_education_institution`    | Shared education institution            |
    | `shared_education_overlap_months` | Months of overlap in education          |
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Problem                          | What to do                                                                                                                   |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Authentication failed**        | Re-copy the connection string (especially the password) from **Settings → Database → Connection string**.                    |
| **Host not allowed**             | The host must be `db.<ref>.supabase.co` or a `*.pooler.supabase.com` pooler host. Custom proxies aren't supported.           |
| **Insufficient permissions**     | The role needs permission to create and write in the chosen schema (for Supabase, the default `postgres` user works).        |
| **Table shape mismatch**         | A `clustr_referral_paths` table with incompatible columns already exists. Pick a different schema, or drop it and reconnect. |
| **An export is already running** | Wait for the in-flight sync to finish before starting another.                                                               |