# Powering a map from your own database

Connect a read-only data bridge to your Postgres database and back a map with live external data, with no copying or imports.

Most maps show the records you keep in Saw Your Sign. A **data bridge** lets a map show pins straight from your own data instead. Nothing gets copied or imported, and your data stays where it lives. It's built for products, directories, and networks that already keep their listings somewhere and want a Saw Your Sign map on top.

Data bridges are a **beta** feature. If your data lives in a CRM like Jobber or AccuLynx, use [Connecting your CRM](/help/connecting-your-crm) instead.

## Source types

A bridge can connect to any of these, each needing latitude and longitude for every row:

- **PostgreSQL database**: a read-only connection string and a table or view. Best for live, large datasets. (For technical teams.)
- **CSV file at a URL**: a publicly reachable CSV link. The first row is the header.
- **Google Sheet**: a sheet shared so anyone with the link can view, or published to the web, with no developer needed.
- **Airtable**: a base and table, with a read-only personal access token.

The spreadsheet and Airtable options are the no-code path: paste a link (or a token) and map your columns. Whichever you pick, the map reads your source live, your credentials are encrypted and never sent to the browser, and visitors can only filter through the fields you allowlist.

## How it works

1. You connect Saw Your Sign to your database with a **read-only** connection.
2. You map your table's columns: which column is the title, which are the coordinates, and which fields visitors can filter by.
3. You point a saved map at the bridge. The map queries your database directly (results are briefly cached, for at most a minute, so a busy map doesn't hammer your database), and visitors can only filter through the fields you allowlisted. They can never run their own queries, and your connection string is never sent to the browser.

## Create a bridge

You can start from two places: **Settings → Data bridges**, or **Records**, where bridges appear as an **External sources** group below your record types. Either way the same setup dialog opens.

1. In the dashboard, go to **Settings → Data bridges** and click **+ New** (or open **Records** and click **External source**).
2. **Connect** (step 1 of 2): choose a **Source type**, then give it what it needs:
   - **PostgreSQL**: paste a **connection string**, or click **Enter details** for host, port, database, user, password, and SSL mode. Use a dedicated role that can only `SELECT` from the table or view you want to map.
   - **CSV file** or **Google Sheet**: paste the **URL**.
   - **Airtable**: enter your **personal access token**, **base ID**, and **table**.

   Credentials are encrypted at rest and never shown again after saving.
3. Click **Test connection**. Nothing is saved until it works. If it fails you'll see the source's own error message (wrong password, unreachable host, a sheet that isn't shared, and so on).
4. **Map your data** (step 2 of 2): for a database, pick the **table or view** first; the other sources go straight to mapping. The core columns (ID, title, latitude, longitude, plus optional slug, city, state, description, and thumbnail) are offered as dropdowns of the source's actual columns, pre-selected by name where there's an obvious match.
5. Add **fields** for the attributes you want on each record by picking columns from the dropdown. Each field gets a sensible key, label, and type automatically (you can adjust them), plus two toggles:
   - **filter**: whether visitors (and embedding sites) can filter by it,
   - **search**: whether the free-text search box looks at it.
6. Click **Create bridge**. The mapping is verified immediately and the bridge appears as **Connected**.

Once a bridge exists, selecting it under **Records → External sources** opens a detail view: its status and last check, how many rows are mappable, the fields you allowlisted, and the maps it backs (with a link to each map and a **View live** link to open the public map). From there you can **Test connection**, **Edit** the mapping, or jump to **Settings** to manage it. Deleting a bridge lives in Settings.

## Point a map at the bridge

1. Open the map's settings (**Maps** → pencil icon) and stay on **General**.
2. In the **Data source** card, pick your bridge from the **External sources** group (your record types sit in the same list under **Workspace records**) and the change saves immediately.
3. Visit the map. Pins, filters, and search now come from your database. Filter options and ranges are sampled live from your data, the same way they are for workspace records.

A bridge-backed map keeps all of your map's styling: theme, pin colors, clustering, branding, and embed settings work as usual.

## What's different on a bridge-backed map

- Clicking a record highlights it on the map but doesn't open the built-in record detail page: your records live in your product, so detail pages stay yours. If you embed the map with the [JavaScript SDK](/help/embedding-with-the-sdk), your site gets a `select` event with the record's ID and slug and can open its own page.
- The lead form and reviews still work and belong to your workspace, not the external data.
- Record privacy modes don't apply: bridge data is assumed to be public business listings with exact coordinates.

## Troubleshooting

- **The map is empty.** Run **Test connection** on the bridge. If it passes, check that your latitude/longitude columns are non-null for the rows you expect, and that the map's saved filters aren't excluding everything.
- **A filter is missing.** Only fields with **filter** checked appear, and only when your data actually has values for them.
- **The test fails with "permission denied".** Your database role needs `SELECT` on the mapped table or view (and `USAGE` on its schema).

If you change the table's columns later, re-run **Test connection**: the bridge reports the exact column it can no longer find.