> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://docs.mammoth.io/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# PostgreSQL connector

> Connect Mammoth to PostgreSQL: what you need, how to enter credentials, and how to import a table or custom SQL query as a dataset.

The PostgreSQL connector imports data from your PostgreSQL database into Mammoth as a dataset. You can import tables directly or write custom SQL queries to select specific rows and columns. When enabled for your workspace, AI query generation creates SQL from plain-language descriptions; you can also edit queries manually. You can refresh the dataset manually or on a schedule.

## Before you start

You need:

- A PostgreSQL server accessible from the internet
- A database user with `SELECT` permission on the tables you want to import
- Your server's hostname or IP address, port (default: 5432), database name, username, and password
- Mammoth's IP address added to your PostgreSQL firewall allowlist—see [Network requirements](https://docs.mammoth.io/learn/connectors/network-requirements/)

## Step 1: Select the PostgreSQL connector

1. In Mammoth, go to **Data Library** and click **+ New Dataset**
2. Select **Connectors**
3. Search for **PostgreSQL**
4. Click the **PostgreSQL** tile

## Step 2: Create a connection

Click **New Connection** to open the credential form.

![PostgreSQL New Connection form with Host URL, Port, Username, Password, Database, and Display Name fields](https://docs.mammoth.io/api/v1/images/20260615_103344_Screenshot2026-05-221755361.jpg)

Fill in the following fields:

| Field | Description | Example |
| --- | --- | --- |
| **Host URL** | Hostname or IP address of your PostgreSQL server | `analytics-prod.example.com` |
| **Port** | TCP port PostgreSQL listens on | `5432` (default) |
| **Username** | Database user with SELECT access | `mammoth_reader` |
| **Password** | Password for the database user |—|
| **Database** | Name of the database to connect to | `analytics_prod` |
| **Display Name** | Optional label for this connection in Mammoth | `Postgres Production` |

> **Mammoth needs network access.**
> Your PostgreSQL server must allow inbound connections from Mammoth's IP address, which the connection form shows. See [Network requirements](https://docs.mammoth.io/learn/connectors/network-requirements/) for firewall configuration steps.

After filling in the fields, click **Connect**. Mammoth validates the credentials and saves the connection; if validation fails, the error message appears at the bottom of the form.

---

## Step 3: Query your PostgreSQL data

After connecting, your connection appears under **Existing Connections**. Select it to open the query builder, which has a table browser and two options for specifying your data:

### Select a PostgreSQL schema

PostgreSQL databases can have multiple schemas (the default is `public`). Mammoth lists them under **Schema** below your connection; click the schema that contains your tables. If the database has only one schema, Mammoth opens it automatically.

### Browse and select PostgreSQL tables

The **List of tables** panel lists all tables in the selected schema. Click a table name to load a `SELECT *` query for it and its preview.

### Generate a PostgreSQL query with AI

When enabled for your workspace, the **Describe the data you need...** box appears above the query editor. Use it to tell Mammoth what you want in plain language—for example, *"all completed orders in the last 90 days"*—and click the generate button. Mammoth writes the SQL query based on your table structure and description. The box is disabled while Mammoth sets up metadata for AI query.

### Write a custom PostgreSQL query

Alternatively, write or edit SQL directly in the **Enter SQL query** field to filter rows, join tables, or select specific columns:

```sql
SELECT order_id, customer_id, amount, created_at
FROM orders
WHERE created_at >= NOW() - INTERVAL '90 days'
  AND status = 'completed'
```

Click **Run** to execute and preview the results.

![PostgreSQL New Dataset dialog with table list, SQL query, data preview, Save table as field, and Save as dataset button](https://docs.mammoth.io/api/v1/images/20260615_103405_Screenshot2026-05-221757111.jpg)

See [Understanding data preview & query](https://docs.mammoth.io/learn/connectors/understanding-data-preview-query/) for a full guide to the preview screen.

## Step 4: Save the PostgreSQL dataset

When the preview looks correct:

1. Enter a **dataset name** in the **Save table as** field (e.g., *"PostgreSQL Orders"*)
2. Check the **Update Method** (the default is **Replace all data**). To change it, click the edit icon, pick an option, and click **Save changes**:
   - **Replace all data**—Replaces all existing data
   - **Add new data**—Adds new data based on a unique sequential column
   - **Replace with new data**—Replaces existing data with new data based on a unique sequential column
   For **Add new data** and **Replace with new data**, also choose a **Key column**—a numeric or date column with incrementing values, such as an ID or a date.
3. Click **Save as dataset**. When the dataset is saved, click **Done**

Your dataset appears in the Data Library and is ready to use in pipelines and dashboards.

## Keep PostgreSQL data up to date

To refresh your PostgreSQL dataset on a schedule, create a **Dataset Refresh** automation. This re-runs your query and updates the dataset according to your update method. You can also run it manually.

## Troubleshoot PostgreSQL connections

### Connection fails

- Confirm Mammoth's IP address is in your PostgreSQL allowlist (`pg_hba.conf` and any cloud security group)
- Check the hostname and port are correct
- Verify the database user can connect from an external host (not just `localhost`)

### No tables appear in the table browser

- Your database user may lack `SELECT` permission—run `GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_user;`
- Verify the database connection succeeded and the database user has access to your tables

### Query returns unexpected results

- Test the query directly in your PostgreSQL client before running it in Mammoth
- Check for timezone differences if filtering by date

---
Source: https://docs.mammoth.io/learn/connectors/postgresql-connector.md · Updated: 2026-10-13