Connecting to Databricks over JDBC from Syntasa Notebooks

This guide explains how to connect to an existing Databricks workspace from a Syntasa notebook using JDBC, how credential ownership works, and what to expect around token expiry — including how to set things up so shared notebooks work smoothly for every user.

Overview

Syntasa notebooks can query an existing Databricks workspace over JDBC (or the databricks-sql-connector Python package). Databricks authenticates these connections with a Personal Access Token (PAT).

Two properties of PATs drive everything in this document:

1. A PAT is personal. It is issued to one Databricks user and carries that user's identity and permissions. It is not a shared service secret.

2. A PAT expires. Its lifetime is set in Databricks when the token is generated (and may be capped by the Databricks workspace's token policy). Syntasa stores the token value as-is and does not — and cannot — refresh or rotate it.

Because the token is personal, each user must store their own PAT in their own Syntasa credential object and reference that credential from notebook code. This page documents that model, the correct setup, what happens in shared notebooks, and how to read the errors you may see.

The credential-ownership model

Credential objects

Databricks PATs should be stored in a Syntasa credential object (Settings → Credentials). A credential holds key–value secrets, has an owner, and has a sharing setting:

The secret values can come from any supported source type — INLINE (stored in Syntasa), or resolved at read time from AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault. The ownership and sharing rules are the same regardless of source.

Who is "the user" in a notebook?

Notebook cells always execute under the identity of the user who runs the cell — not the notebook's author and not the notebook's owner. This holds in shared notebooks and shared kernels: when user B runs a cell that reads a credential, the platform authorizes that read against user B's access, on every call. Credential reads are never cached across users.

The practical consequence:

• A notebook that reads the author's private credential works for the author and fails with an access error for everyone else (see section 5).

• There is no supported way for a notebook to "dynamically pick up whichever user's PAT is appropriate" from a single shared credential. Each user references their own credential.

One-time setup (each user)

Step 1 — Generate a PAT in Databricks.
In your Databricks workspace: User Settings → Developer → Access tokens → Generate new token. Give it a comment (e.g. syntasa-notebooks) and a lifetime. Copy the value immediately — Databricks shows it only once.

Step 2 — Store it in a private Syntasa credential.
In Syntasa: Settings → Credentials → Create, e.g.:

• Name: databricks-pat-<your-username> (any unique name works; a per-user naming convention keeps shared notebooks easy to adapt)

• Sharing: PRIVATE

• Secrets: key token = the PAT value. Optionally also store server_hostname and http_path here, or keep those non-secret values in the notebook.

Step 3 — Reference it from your notebook (see section 4).

When the PAT expires or is revoked, generate a new one in Databricks and edit the existing credential to replace the token value. The credential name stays the same, so no notebook code changes are needed.

Notebook usage

Retrieve the PAT with synutils.credentials at run time. Never paste a PAT into notebook source — notebooks are often shared, exported, and versioned.

Python + databricks-sql-connector

import synutils
from databricks import sql

pat = synutils.credentials.get("databricks-pat-alice", "token")  # SecretString, prints as **********

conn = sql.connect(
    server_hostname="adb-1234567890123456.7.azuredatabricks.net",
    http_path="/sql/1.0/warehouses/<warehouse-id>",
    access_token=pat.get(),          # .get() reveals the raw value for the SDK
)
with conn.cursor() as cur:
    cur.execute("SELECT * FROM samples.nyctaxi.trips LIMIT 10")
    rows = cur.fetchall()

Spark JDBC (Databricks JDBC driver)

import synutils

pat = synutils.credentials.get("databricks-pat-alice", "token")

jdbc_url = (
    "jdbc:databricks://adb-1234567890123456.7.azuredatabricks.net:443/default;"
    "transportMode=http;ssl=1;"
    "httpPath=/sql/1.0/warehouses/<warehouse-id>;"
    "AuthMech=3"                      # AuthMech=3 = username/password, where username is the literal string "token"
)

df = (spark.read.format("jdbc")
      .option("url", jdbc_url)
      .option("driver", "com.databricks.client.jdbc.Driver")
      .option("user", "token")
      .option("password", pat.get())
      .option("query", "SELECT * FROM samples.nyctaxi.trips LIMIT 10")
      .load())

Notes:

• synutils.credentials.get(name, key) returns a SecretString that prints redacted (**********); call .get() only at the point you hand it to the SDK. getAll(name) returns a redacted SecretDict of all keys.

• The Databricks JDBC driver jar must be available on the cluster (com.databricks.client.jdbc.Driver).

Making a notebook multi-user friendly

A shared notebook should not hardcode one person's credential name. Two common patterns:

1. Naming convention — every user creates databricks-pat-<username> and the notebook derives the name from the logged-in user.

2. Parameter cell — the first cell defines DATABRICKS_CREDENTIAL = "databricks-pat-alice", and each user edits that single line to point at their own credential before running.

Either way, the platform enforces the rest: a user who forgets and runs the notebook against someone else's private credential gets a clear access error (section 5), not someone else's token.

Shared notebooks: what the other user sees

If user B runs a cell that reads user A's PRIVATE credential, the read is rejected by the platform and the cell fails with:

CredentialError: Failed to fetch credential 'databricks-pat-alice':
API request failed (401): {"detail":"User does not have access to this resource!"}

This is expected and correct behavior — it is the access-control model working, not a bug. The fix is for user B to complete the one-time setup in section 3 and point the notebook at their own credential.

One exception: a system administrator (super role) running the same cell succeeds, because that role bypasses sharing checks — and the notebook would then connect to Databricks as the credential's owner. System admins should also use their own credential rather than relying on this bypass.

A credential name that does not exist at all fails with a similar-looking error — API request failed (401): {"detail":"No credentials found matching the provided criteria"} — so a 401 from a credential read means either the name is wrong or the credential is not shared with you; check the name first.

Token lifespan expectations

[Databricks][JDBCDriver](500593) Communication link failure. Failed to connect to server.
Reason: HTTP Response code: 401, Error message: Invalid access token.

or, from databricks-sql-connector: Error during request to server: Invalid access token.

Recommendations:

• Set a deliberate PAT lifetime (e.g. 90 days) rather than "no expiry", and note the expiry date in the credential's description field.

• When rotating, edit the existing credential in place so notebook code keeps working unchanged.

Error quick reference

The Databricks-side messages vary by driver/connector version — treat "401 / Invalid access token" as the signature of an expired or revoked PAT rather than an exact string match.

Summary

• Databricks PATs are personal: one PAT = one Databricks user identity.

• Store your PAT in a PRIVATE Syntasa credential you own; retrieve it in notebooks via synutils.credentials.get(...); never hardcode it.

• In shared notebooks, each user points the notebook at their own credential. Anyone referencing someone else's private credential gets an explicit "User does not have access to this resource!" error — by design.

• Token expiry is governed by Databricks; rotate by editing the credential value in place.