TLS server certificate validation

Lakeflow Connect database connector pipelines encrypt all data in transit using TLS. Starting with newly created pipelines, Lakeflow Connect also validates the source database server's TLS certificate. This certificate validation verifies that the pipeline is connecting to the intended server—not an impersonator—and prevents person-in-the-middle (PITM) attacks.

This page applies to the MySQL, PostgreSQL, and SQL Server Lakeflow Connect connectors.

How certificate validation works

When a new pipeline connects to a source database, Lakeflow Connect verifies the server's TLS certificate against a trusted CA certificate. The pipeline fails to connect if the certificate cannot be verified.

Certificate validation changes do not affect existing pipelines. Newly created pipelines have certificate validation enabled by default.

The default validation behavior differs by connector:

Connector	Default behavior when no CA certificate is provided
MySQL	The pipeline fails to connect. MySQL requires an explicit CA certificate because the MySQL binlog replication utility does not use the JVM truststore. You must either provide a CA certificate in the connection or opt out of validation.
PostgreSQL	The pipeline connects using the JVM default truststore, which includes well-known public certificate authorities (for example, DigiCert and Let's Encrypt). If your PostgreSQL server uses a certificate from a recognized public CA, no action is required. If your server uses a private or internal CA, you must provide a custom CA certificate.
SQL Server	The pipeline connects using the JVM default truststore, which includes well-known public certificate authorities. If your SQL Server uses a certificate from a recognized public CA, no action is required. If your server uses a private or internal CA, you must provide a custom CA certificate.

Provide a CA certificate

If your database server uses a certificate from a private or internal CA—or if you are using MySQL—add your CA certificate to the Unity Catalog connection that the pipeline uses.

Create or update a connection with a CA certificate

Databricks UI

To add a CA certificate when creating a new connection:

1. In the Databricks workspace, click Catalog.
2. Click Create and select Create connection.
3. Enter a Connection name and select the Connection type for your database.
4. Click Next.
5. On the Authentication page, enter the host, port, and login credentials.
6. In the SSL certificate field, paste the contents of your CA certificate file (PEM format).
7. Click Create connection.

To update an existing connection to add a CA certificate:

1. In the Databricks workspace, click Catalog.
2. In Catalog Explorer, go to the connection.
3. Click Edit.
4. In the SSL certificate field, paste the contents of your CA certificate file (PEM format).
5. Save your changes.

Databricks CLI

Include the CA certificate in the options object when creating a connection. The following examples show the CA certificate option for each connector.

MySQL:

Bash

databricks connections create --json '{
  "name": "my_mysql_connection",
  "connection_type": "MYSQL",
  "options": {
    "host": "<host>",
    "port": "3306",
    "user": "<username>",
    "password": "<password>",
    "ssl_ca": "<CA certificate content in PEM format>"
  }
}'

PostgreSQL:

Bash

databricks connections create --json '{
  "name": "my_postgresql_connection",
  "connection_type": "POSTGRESQL",
  "options": {
    "host": "<host>",
    "port": "5432",
    "database": "<database>",
    "user": "<username>",
    "password": "<password>",
    "ssl_ca": "<CA certificate content in PEM format>"
  }
}'

SQL Server:

Bash

databricks connections create --json '{
  "name": "my_sqlserver_connection",
  "connection_type": "SQLSERVER",
  "options": {
    "host": "<host>",
    "port": "1433",
    "user": "<username>",
    "password": "<password>",
    "ssl_ca": "<CA certificate content in PEM format>"
  }
}'

Opt out of certificate validation (not recommended)

warning

Disabling certificate validation exposes your pipelines to person-in-the-middle (PITM) attacks and must not be used in production environments. Databricks recommends providing a CA certificate instead.

If your environment does not support certificate validation, you can configure the connection to trust the server certificate without verifying it against a CA. Set trustServerCertificate to true in the connection options.

Databricks UI

When creating or editing a connection in Catalog Explorer, select Trust server certificate to skip certificate validation.

Databricks CLI

Bash

databricks connections create --json '{
  "name": "my_connection",
  "connection_type": "POSTGRESQL",
  "options": {
    "host": "<host>",
    "port": "5432",
    "database": "<database>",
    "user": "<username>",
    "password": "<password>",
    "trustServerCertificate": "true"
  }
}'

HIPAA and FedRAMP workspaces

In workspaces with HIPAA or FedRAMP compliance configurations, Lakeflow Connect enforces TLS version 1.2 or 1.3 for all database connector connections. This requirement cannot be turned off.

Troubleshoot TLS certificate errors

If a pipeline fails due to a TLS certificate error, check the pipeline event log for the ingestion gateway pipeline. The event log records connection errors, including certificate validation failures, with details to help you diagnose the issue.

Common causes and resolutions:

Error	Likely cause	Resolution
PKIX path building failed or unable to find valid certification path	The server's CA certificate is not in the JVM truststore and no custom CA certificate was provided.	Provide the CA certificate in the Unity Catalog connection.
SSL connection has been closed unexpectedly	The server does not support TLS or requires a different TLS version.	Verify that TLS is enabled on your database server. In HIPAA and FedRAMP workspaces, TLS 1.2 or 1.3 is required.
Connection refused or pipeline fails immediately on MySQL	No CA certificate was provided and trustServerCertificate is not set.	Provide the CA certificate for MySQL, or opt out of validation if you cannot provide a certificate.

For more connector-specific troubleshooting, see:

• Troubleshoot MySQL ingestion issues
• Troubleshoot PostgreSQL ingestion
• Troubleshoot SQL Server ingestion