> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/destinations/categories/database/postgresql.md).
# PostgreSQL
Send data to PostgreSQL with Coupler.io for SQL-native analysis, type enforcement, and direct querying without exports.
PostgreSQL is one of the most widely used open-source relational databases in the world. Sending data to PostgreSQL with Coupler.io lets you store, query, and analyze data from any supported source using the full power of SQL — including joins, aggregations, views, and more.
## Why use PostgreSQL as a Coupler.io destination?
* **SQL-native analysis** — query your imported data with any SQL tool, BI platform, or ORM without exporting anything
* **Type enforcement** — Coupler.io detects and maps column types automatically, so your data lands in PostgreSQL cleanly structured
* **Any source, one database** — combine data from Google Ads, Stripe, YouTube, Facebook Ads, and dozens of other sources into a single PostgreSQL database
* **Supabase compatible** — if you run Supabase, it uses PostgreSQL under the hood, so you can load data into it using this destination
* **Scheduled refreshes** — keep your tables up to date automatically on the interval that fits your workflow
## Prerequisites
* A running PostgreSQL instance (self-hosted, cloud-hosted, or Supabase)
* A database user with the following privileges:
* **CREATE** at the database level
* **CREATE** at the schema level
* **INSERT** on the target table
* If your database restricts inbound connections, allowlist these Coupler.io IPs:
* `34.123.243.115`
* `34.170.96.92`
## Quick start
{% hint style="success" %}
If you're using Supabase, just grab your connection credentials from the Supabase dashboard (Settings → Database) and use them in the PostgreSQL destination setup below.
{% endhint %}
{% stepper %}
{% step %}
**Create a new data flow and add your source.** Log in to Coupler.io, click **Add data flow**, and configure your data source — this can be any source Coupler.io supports, such as Google Ads, Stripe, or YouTube.
{% endstep %}
{% step %}
**Select PostgreSQL as your destination.** In the destination step, choose **PostgreSQL** from the list.
{% endstep %}
{% step %}
**Connect your PostgreSQL account.** Click **+ Add Account** and fill in your connection credentials:
* **Host** — hostname, IPv4, or IPv6 address of your PostgreSQL server
* **Port** — default is `5432`
* **Database** — the name of the target database
* **User** — your PostgreSQL username
* **Password** — your PostgreSQL password
Once filled in, click **Connect** to verify the connection.
{% endstep %}
{% step %}
**Set your target schema and table.** Enter the schema name and table name where Coupler.io should write data. If the schema or table doesn't exist yet, Coupler.io will create them automatically on the first run.
{% endstep %}
{% step %}
**Choose a write mode.**
* **Replace** — drops all existing rows in the table and loads fresh data on each run. Best for dashboards and reports that always reflect the latest state.
* **Append** — adds new rows below existing data without removing anything. Best for event logs, transaction history, or any time-series data.
{% hint style="warning" %}
If you use Append mode and your source data structure changes (e.g., new columns are added), you'll need to manually update the PostgreSQL table schema before the next run.
{% endhint %}
{% endstep %}
{% step %}
**Run your data flow.** Click **Save and Run** to trigger the first manual run. Coupler.io will connect to your database, create the table if needed, and load your data. Once the run completes successfully, you can set up a schedule.
{% endstep %}
{% endstepper %}
## Supported features
| Feature | Supported |
| -------------------- | --------- |
| Replace mode | Yes |
| Append mode | Yes |
| Automatic scheduling | Yes |
| Type enforcement | Yes |
| Templates | No |
## PostgreSQL common issues
### Connection issues
Coupler.io can't connect to my PostgreSQL server
This usually means the host, port, or credentials are wrong — or your database server is blocking the connection.
Things to check:
* Make sure the **host**, **port**, **database name**, **username**, and **password** are all correct
* Confirm your PostgreSQL instance is accessible from the internet (or at least from Coupler.io's IPs)
* If your server uses IP allowlisting or a firewall, add both Coupler.io IPs to the allowlist:
* `34.123.243.115`
* `34.170.96.92`
* If you're connecting to **Supabase**, use the connection string details from **Settings → Database** in your Supabase dashboard, and make sure you're using the correct connection mode (Session or Transaction pooler)
{% hint style="warning" %}
Some cloud-hosted PostgreSQL providers (e.g., AWS RDS, Google Cloud SQL) require you to explicitly enable public access or configure VPC rules. Check your provider's network settings if the connection keeps failing.
{% endhint %}
Connection times out during the data flow run
A timeout during the run (not at the credential step) often indicates the database server is under load, or the query is taking too long for very large datasets.
* Try running the data flow again — transient timeouts often resolve themselves
* If the issue persists, check your PostgreSQL server's resource usage (CPU, memory, connections)
* Consider splitting large data flows into smaller sources or filtering data at the source level
### Data issues
Data flow fails with a column name error
PostgreSQL enforces a **63-character limit** on column names. If your source data has field names longer than 63 characters, the data flow will fail.
This is a known issue with sources like **Facebook (Meta) Ads** and **Stripe**, which sometimes produce long field names.
To fix this:
* Use the **Transformations** step in your data flow to rename the affected columns to shorter names before they reach PostgreSQL
* Be careful when editing transformations — changes are saved automatically without a confirmation prompt, so double-check before navigating away
{% hint style="danger" %}
Transformation changes in Coupler.io save automatically. Accidental edits can change your column structure without warning. Review your transformation settings carefully if your data flow suddenly starts failing.
{% endhint %}
Append mode breaks after a source schema change
When using Append mode, Coupler.io writes new rows into the existing table structure. If your source adds new columns (for example, a new metric in your ad platform), PostgreSQL won't know about them and the run may fail.
To fix this, manually `ALTER TABLE` in PostgreSQL to add the new column(s) before the next run. After that, Coupler.io will populate them normally.
Data types are wrong in the destination table
Coupler.io detects and enforces column types automatically. However, if the table already exists with different column types from a previous run or manual creation, there can be a mismatch.
* If you're using **Replace** mode, try deleting the existing table and letting Coupler.io recreate it cleanly on the next run
* If you're using **Append** mode, check that the existing table's column types match what Coupler.io is trying to write
### Permission errors
Permission denied when creating a schema or table
The PostgreSQL user you connected with doesn't have enough privileges. Make sure the user has:
* **CREATE** privilege on the target database
* **CREATE** privilege on the target schema
* **INSERT** privilege on the target table
You can grant these with:
```sql
GRANT CREATE ON DATABASE your_database TO your_user;
GRANT CREATE ON SCHEMA your_schema TO your_user;
GRANT INSERT ON TABLE your_schema.your_table TO your_user;
```
{% hint style="info" %}
If you want Coupler.io to create new schemas and tables automatically, the user needs CREATE at both the database and schema level — not just INSERT on an existing table.
{% endhint %}
## PostgreSQL FAQ
Can I use Supabase as my PostgreSQL destination?
Yes. Supabase runs on PostgreSQL, so you can use Coupler.io's PostgreSQL destination to load data into it. In your Supabase dashboard, go to **Settings → Database** to find your connection credentials (host, port, database name, user, and password), then enter them in the PostgreSQL destination setup.
What's the difference between Replace and Append mode?
**Replace** deletes all existing rows in the table and loads the latest data from your source on every run. Use this when you always want the table to reflect the current state — for example, a live snapshot of your ad campaigns or subscriptions.
**Append** adds new rows to the bottom of the table without removing existing data. Use this for historical tracking — for example, logging daily metrics, transaction events, or usage data over time.
What happens if the schema or table I specify doesn't exist yet?
Coupler.io will create them automatically on the first successful run. You don't need to pre-create anything in PostgreSQL — just make sure the connected user has CREATE privileges at the database and schema level.
Can I send data from multiple sources into the same PostgreSQL database?
Yes. You can create multiple data flows, each pointing to the same PostgreSQL database but writing to different tables or schemas. You can also use a single data flow with multiple sources and apply Join, Append, or Aggregate transformations before the data lands in PostgreSQL.
Why are some of my column names getting truncated or causing errors?
PostgreSQL has a 63-character limit on column names. Sources like Facebook (Meta) Ads and Stripe sometimes produce field names longer than this, which causes the data flow to fail. Use the **Transformations** step in your data flow to rename those columns to something shorter before they reach PostgreSQL.
{% hint style="info" %}
**Note:** See the Common Issues article for step-by-step guidance on handling column name length errors.
{% endhint %}
How do I keep my existing PostgreSQL data safe when using Replace mode?
Replace mode overwrites everything in the target table on each run. If you need to preserve historical data, switch to **Append** mode instead. Alternatively, set up a separate table for Coupler.io's writes and use SQL views or queries to combine it with your other data.
Does Coupler.io enforce data types when writing to PostgreSQL?
Yes. Coupler.io detects column types from your source data and enforces them when writing to PostgreSQL. This means numeric fields land as numbers, dates as date types, and so on — rather than everything being stored as text. If the existing table has different types, you may see type mismatch errors. Letting Coupler.io create the table from scratch (using Replace mode on a new table) is the cleanest way to get properly typed columns.
What Coupler.io IP addresses should I allowlist for PostgreSQL?
If your PostgreSQL server restricts inbound connections by IP, allowlist the following Coupler.io addresses:
* `34.123.243.115`
* `34.170.96.92`
This applies to self-hosted databases, AWS RDS, Google Cloud SQL, and any other setup with network-level access controls.
Can I connect a self-hosted or private database?
Yes, just make sure your network is set up to allow remote access on Coupler.io's IP addresses.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/destinations/categories/database/postgresql.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.