> 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/azure_sql.md).

# Azure SQL

Send data to Azure SQL Database with Coupler.io, using a SQL login or a Microsoft Entra ID service principal.

Azure SQL is Microsoft's managed SQL Server service in Azure. With the Azure SQL destination, Coupler.io loads data from any supported source into a table in your Azure SQL Database, on a schedule, so you can query it with SQL, Power BI, or any tool that connects to SQL Server.

## Why use Azure SQL as a Coupler.io destination?

* **Your data in your Azure tenant** — data lands in a database you own and control, next to the rest of your Microsoft stack
* **Enterprise sign-in** — connect with a Microsoft Entra ID service principal, so you don't need SQL logins enabled on the server
* **Typed columns** — Coupler.io creates the table with proper SQL Server types (numbers, dates, date-times, booleans), not text only
* **Replace or Append** — keep a fresh snapshot, or build history by adding rows on every run
* **Any source, one database** — combine data from Google Ads, HubSpot, QuickBooks, Stripe and other sources in one database

## Prerequisites

* An Azure SQL Database reachable from the internet (public endpoint)
* A database user for Coupler.io, using one of:
  * a **SQL login** (user name and password), or
  * a **Microsoft Entra ID service principal** (an app registration with a client secret)
* Permissions for that user in the target database:
  * **INSERT** on the target table or schema — needed in every mode
  * **CREATE TABLE** and **ALTER** on the schema — needed when Coupler.io creates or replaces the table
  * **CREATE SCHEMA** — only if you want Coupler.io to create a new schema
* The Coupler.io IP addresses allowed in the server firewall:
  * `34.123.243.115`
  * `34.170.96.92`

See [Azure SQL Connection Setup](https://docs.coupler.io/destinations/categories/database/azure_sql/connection-setup.md) for step-by-step instructions, including the SQL to create the user.

## How to connect

{% stepper %}
{% step %}
**Create a data flow and add your source.** On **Data flows**, click **Create**, choose **Start from scratch**, and configure any source Coupler.io supports.
{% endstep %}

{% step %}
**Select Azure SQL as your destination.** In the **Destinations** step, choose **Azure SQL** and select the data set you want to send.
{% endstep %}

{% step %}
**Connect your Azure SQL account.** Click **+ Add account**, then choose an **Authentication method**:

* **Entra ID Service Principal secret** (default) — enter **Host**, **Port**, **Database**, **Tenant ID**, **Client ID** and **Client secret**
* **SQL username/password** — enter **Host**, **Port**, **Database**, **User** and **Password**

**Host** is your server name, for example `myserver.database.windows.net`. **Port** is `1433` for Azure SQL Database. Click **Save**.

The details are checked on the first run, not when you save the connection.
{% endstep %}

{% step %}
**Set the schema and table.** Enter the **Schema** (default `dbo`) and the **Table**. If they don't exist, Coupler.io creates them on the first run.
{% endstep %}

{% step %}
**Choose the import mode.**

* **Replace** — drops the table and creates it again with the latest data on every run
* **Append** — adds the new rows below the existing ones
  {% endstep %}

{% step %}
**Run the data flow.** Click **Save and run**. When the run succeeds, set up a schedule in **Flow settings**.
{% endstep %}
{% endstepper %}

## Supported features

| Feature                                 | Supported |
| --------------------------------------- | --------- |
| Replace mode                            | Yes       |
| Append mode                             | Yes       |
| Automatic scheduling                    | Yes       |
| Typed columns                           | Yes       |
| SQL login                               | Yes       |
| Microsoft Entra ID service principal    | Yes       |
| Managed identity, Entra ID user sign-in | No        |
| Private endpoint, SSH tunnel            | No        |

### How data is written

| Coupler.io column type | Azure SQL type                                                 |
| ---------------------- | -------------------------------------------------------------- |
| String                 | `nvarchar(max)`                                                |
| Integer                | `bigint`                                                       |
| Decimal                | `float`                                                        |
| Boolean                | `bit`                                                          |
| Date                   | `date`                                                         |
| DateTime               | `datetime2` (values with a time zone offset are stored in UTC) |

All columns are created as nullable. Column names are made SQL-friendly: characters other than Latin letters, digits, `_` and `$` become `_` (`Country Name` → `Country_Name`), and a name starting with a digit gets a `_` prefix. If two names become the same (names are compared without case), each of them gets a number: `Test_name_1`, `test_name_2`.

In Append mode, Coupler.io doesn't add or change columns in an existing table. If the columns in your data change, run the data flow once in **Replace** mode, or add the new columns to the table yourself.

The connection is always encrypted with the latest protocol SQL Server supports (TDS 8.0).

## Azure SQL common issues

### Connection issues

<details>

<summary>The run fails with "Cannot open server … Client with IP address … is not allowed to access the server"</summary>

The server firewall blocks Coupler.io. In the Azure portal, open your SQL server → **Security** → **Networking**, set **Public network access** to **Selected networks**, and add firewall rules for `34.123.243.115` and `34.170.96.92`. Rules can take a few minutes to apply.

</details>

<details>

<summary>The first run after a while fails with "Failed to connect to … in 10000ms"</summary>

Serverless Azure SQL databases pause after a period without use and take up to a minute to resume. The first connection wakes the database but can time out before it's ready. Run the data flow again. For scheduled runs, consider disabling auto-pause on databases that Coupler.io writes to.

</details>

<details>

<summary>The run fails with "Login failed for user '&#x3C;token-identified principal>'"</summary>

Microsoft Entra ID signed in the service principal, but the database didn't accept it. Check that:

* the **Database** name in the connection is exact
* the service principal was added to this database with `CREATE USER [<app name>] FROM EXTERNAL PROVIDER;`

See [Azure SQL Connection Setup](https://docs.coupler.io/destinations/categories/database/azure_sql/connection-setup.md#option-a-microsoft-entra-id-service-principal).

</details>

<details>

<summary>The run fails with an AADSTS error</summary>

The Tenant ID, Client ID or Client secret is wrong, or the secret has expired. Make sure you pasted the secret's **Value**, not its **Secret ID**. Create a new secret in the app registration if the old one expired, then reconnect the connection in Coupler.io.

</details>

<details>

<summary>The run fails with "We could not connect to the provided database"</summary>

The database name is wrong, or the user doesn't exist in that database. Check the **Database** field, and that the user was created in the target database itself, not only in `master`.

</details>

### Permission errors

<details>

<summary>"Cannot drop the table '…', because it does not exist or you do not have permission"</summary>

Replace mode drops the table before it creates it again. The user needs `ALTER` on the table's schema. This often happens when the schema or table was created by another user. Grant the permission, replacing `<schema>` with the table's schema and `<user>` with the Coupler.io user:

```sql
GRANT ALTER ON SCHEMA::<schema> TO [<user>];
```

</details>

<details>

<summary>"CREATE TABLE permission denied" or "CREATE SCHEMA permission denied"</summary>

The user can't create the table or schema. Grant the missing permission, or create the table yourself and use **Append** mode. Replace `<schema>` with the schema Coupler.io writes to and `<user>` with the Coupler.io user:

```sql
GRANT CREATE TABLE TO [<user>];
GRANT ALTER, INSERT ON SCHEMA::<schema> TO [<user>];
GRANT CREATE SCHEMA TO [<user>];  -- only to let Coupler.io create new schemas
```

</details>

### Data issues

<details>

<summary>"The data does not match the table" with a column type</summary>

A column in the existing table has a type that can't hold the data, for example a `date` column that receives numbers. Use **Replace** mode to create the table again, or change the column type in the table.

</details>

## Azure SQL FAQ

<details>

<summary>Which Azure SQL login method should I use with Coupler.io?</summary>

Use a **Microsoft Entra ID service principal** if your organization disables SQL logins or manages access in Entra ID. Use a **SQL login** if it's enabled on your server and you want the quickest setup. Both give Coupler.io the same access.

</details>

<details>

<summary>Does Coupler.io create the Azure SQL schema and table?</summary>

Yes. If the schema or table doesn't exist, Coupler.io creates it on the first run. The user needs `CREATE TABLE` and `ALTER` on the schema, and `CREATE SCHEMA` for a new schema.

</details>

<details>

<summary>How do I query Azure SQL columns that have spaces in their names?</summary>

Coupler.io replaces spaces with underscores, so `Country Name` becomes `Country_Name` and you can query it without brackets.

</details>

<details>

<summary>Can I use a private endpoint or a VNet with the Azure SQL destination?</summary>

No. Coupler.io connects over the public endpoint, from the IP addresses `34.123.243.115` and `34.170.96.92`.

</details>


---

# 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/azure_sql.md?ask=<question>&goal=<user_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.
