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

# Dial Configuration

> How the Connector reaches a Resource's upstream: direct TCP or Google Cloud SQL

Dial configuration controls how the Connector establishes the upstream connection for a Resource. It is optional. When absent, the Connector dials direct TCP using the Resource's `hostname` and `port`. This is the default and matches the behavior of every Resource before this feature.

```mermaid theme={null}
sequenceDiagram
    participant Client as Client
    participant Connector as Connector
    participant Upstream as Upstream

    Client->>Connector: Connect to hostname:port
    alt dial_method = tcp (default)
      Connector->>Upstream: TCP dial to hostname:port
    else dial_method = gcp_cloudsql
      Connector->>Upstream: Google Cloud SQL dial to project:region:instance
      Note over Connector, Upstream: Cloud SQL handles mTLS end-to-end
    end
    Upstream-->>Connector: Response
    Connector-->>Client: Response
```

## Dial methods

### `tcp` (default)

The Connector dials `hostname:port` directly. This fits self-managed databases, Amazon RDS and Aurora, and any other endpoint reachable over plain TCP from the Connector.

### `gcp_cloudsql`

The Connector dials Google Cloud SQL natively, similarly to what Google's `cloud-sql-proxy` does. Ephemeral mTLS certificates are minted and rotated automatically, and the connection is encrypted end-to-end by Cloud SQL.

`gcp_cloudsql` requires `dial_target` to be the Cloud SQL instance connection name in `project:region:instance` form. Supported only for `postgres` and `mysql` Resources.

Connector prerequisites:

* The Connector runs in the Cloud SQL instance's VPC, or in a peered / PSC-connected VPC. The dial targets the instance's private IP.
* Application Default Credentials configured: the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points at a service account JSON key, or the Connector runs on a GCP workload with a bound identity.
* The credentials grant `roles/cloudsql.client` on the project that owns the Cloud SQL instance.

<Info>
  When `dial_method` is not `tcp`, the Resource's [TLS configuration](/docs/guides/core-concepts/resources/tls) is ignored.
</Info>

## Configure dial configuration

<Tabs>
  <Tab title="Web Console">
    <Steps>
      <Step title="Open the Resource">
        Navigate to [Resources](https://app.formal.ai/resources) and open the target Resource.
      </Step>

      <Step title="Open the Connectivity tab">
        Select the **Connectivity** tab. The **Dial Configuration** section is where the dial method and target are set.
      </Step>

      <Step title="Pick a dial method">
        Selecting **TCP** keeps the default. Selecting **Google Cloud SQL** routes upstream connections natively.
      </Step>

      <Step title="Set the dial target (Cloud SQL only)">
        Enter the Cloud SQL instance connection name in `project:region:instance` form (for example `my-project:us-central1:pg-prod`), then click **Save**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Terraform">
    ```hcl theme={null}
    # Direct TCP dial (matches the default, usually omitted).
    resource "formal_resource_dial_configuration" "tcp" {
      resource_id = formal_resource.my_postgres.id
      dial_method = "tcp"
    }

    # Native Cloud SQL dial.
    resource "formal_resource_dial_configuration" "cloudsql" {
      resource_id = formal_resource.my_postgres.id
      dial_method = "gcp_cloudsql"
      dial_target = "my-project:us-central1:pg-prod"
    }
    ```
  </Tab>
</Tabs>

<Tip>
  A Resource has at most one dial configuration. Deleting it restores the default `tcp` behavior.
</Tip>

## Verify

After applying the configuration, run the standard connectivity check:

1. From the Resource Details page, click **Test Connection** (or **Test Connectors** for a specific Connector).
2. The check should report success for the TCP, TLS, Authentication, and Data Access stages.

See [Testing Resource Connectivity](/docs/guides/core-concepts/resources/introduction#testing-resource-connectivity) for what each stage validates.

<Info>
  For Cloud SQL, the first dial against a new instance adds roughly one second of latency while the ephemeral certificate is minted. Subsequent dials within the hour reuse the cached certificate.
</Info>