Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This quickstart connects a local Jupyter notebook to Fabric HorizonDB by using Psycopg 3 and a Microsoft Entra access token. It queries the sample schema and creates a chart without displaying credentials.
Important
Fabric HorizonDB is in public preview. Capabilities, limits, and behavior might change before general availability. For more information, see Microsoft Fabric preview features.
Prerequisites
- Python 3.10 or later and Visual Studio Code with the Python and Jupyter extensions, or another local Jupyter environment.
- A HorizonDB database and the sample data from Load sample data.
- Sign-in as the Microsoft Entra user who created the database. Other users and application principals can't connect in the current preview.
- The released Fabric HorizonDB host, port, database, user format, token scope, and TLS mode.
- A browser for interactive Microsoft Entra sign-in.
This procedure doesn't assume that a hosted Fabric notebook identity or outbound network path can connect to Fabric HorizonDB. Use that path only when it is explicitly documented for the release.
Create the notebook environment
Create and activate a virtual environment, and then install:
python -m pip install "psycopg[binary]" azure-identity pandas matplotlib ipykernel
Create a notebook named horizondb-quickstart.ipynb and select the virtual environment as its kernel.
Configure connection values
Set connection coordinates outside the notebook, for example in the environment that launches Visual Studio Code:
HORIZONDB_HOST=<postgresql-endpoint>
HORIZONDB_PORT=<port>
HORIZONDB_DATABASE=postgres
HORIZONDB_USER=<entra-identity>
HORIZONDB_TENANT_ID=<your-tenant-id>
HORIZONDB_SSLMODE=<documented-mode>
HORIZONDB_TOKEN_SCOPE=<released-token-scope>
Don't put a token, complete connection string, or secret in a notebook cell. Don't print os.environ or a credential object.
Import packages
In the first cell, run:
import os
import matplotlib.pyplot as plt
import pandas as pd
import psycopg
from azure.identity import InteractiveBrowserCredential
Connect and validate
Create a fresh token and connection in one cell:
credential = InteractiveBrowserCredential(
tenant_id=os.environ["HORIZONDB_TENANT_ID"]
)
access_token = credential.get_token(
os.environ["HORIZONDB_TOKEN_SCOPE"]
).token
connection = psycopg.connect(
host=os.environ["HORIZONDB_HOST"],
port=int(os.environ["HORIZONDB_PORT"]),
dbname=os.environ["HORIZONDB_DATABASE"],
user=os.environ["HORIZONDB_USER"],
password=access_token,
sslmode=os.environ["HORIZONDB_SSLMODE"],
connect_timeout=30,
application_name="horizondb-jupyter-quickstart",
autocommit=True,
)
Validate the session without displaying the token or connection string:
with connection.cursor() as cursor:
cursor.execute(
"""
SELECT
current_database(),
current_user,
current_setting('server_version'),
clock_timestamp()
"""
)
print(cursor.fetchone())
Sign in as the creator in the browser. Expected output contains the database name from the connection pane (postgres in the current preview), the effective identity, engine version, and connection time.
Query sample data
Use parameters for values:
query = """
SELECT
customer.segment,
count(order_row.order_id) AS order_count,
coalesce(sum(order_row.total), 0) AS order_total
FROM horizon_sample.customers AS customer
LEFT JOIN horizon_sample.orders AS order_row
ON order_row.customer_id = customer.customer_id
WHERE order_row.status <> %s
GROUP BY customer.segment
ORDER BY customer.segment
"""
with connection.cursor() as cursor:
cursor.execute(query, ("cancelled",))
rows = cursor.fetchall()
columns = [column.name for column in cursor.description]
results = pd.DataFrame(rows, columns=columns)
results["order_total"] = pd.to_numeric(results["order_total"])
results
The result contains one row per customer segment. Rerunning the cell doesn't modify data.
Create a chart
axis = results.plot.bar(
x="segment",
y="order_total",
legend=False,
title="Order total by customer segment",
)
axis.set_xlabel("Segment")
axis.set_ylabel("Order total")
plt.tight_layout()
plt.show()
Close the connection
Run this cell before stopping the kernel:
connection.close()
credential.close()
Acquire a fresh token and create a new connection if the notebook remains open long enough for the credential to expire, or after Fabric HorizonDB pauses or a disruptive transition occurs.
Make notebook reruns predictable
- Keep setup, authentication, query, visualization, and cleanup in separate cells.
- Use read-only queries unless the notebook explicitly demonstrates a transaction.
- Use
CREATE ... IF NOT EXISTSand conflict handling for rerunnable setup. - Parameterize values.
- Close stale connections before recreating them.
- Clear outputs before sharing the notebook if they include real data, endpoints, user names, item IDs, or errors that can contain credentials.
Troubleshoot
| Symptom | Resolution |
|---|---|
| Kernel can't import a package | Select the environment where you installed the packages and restart the kernel. |
| Credential acquisition fails | Sign in through a supported local credential and verify the tenant. |
| Authentication fails | Verify the released token scope, user format, token freshness, and system time. |
| Connection times out | The database might be resuming. Recreate the connection with bounded retry. |
| Permission denied | Confirm that you're the database creator, inspect object ownership, and verify that the operation is supported. |
| Chart is empty | Display results, verify the filter, and confirm the sample data exists. |
| A rerun reports a closed connection | Rerun the connection cell to acquire a fresh token and session. |