Connect notebooks to Exasol

Learn how to connect Jupyter and marimo notebooks to your Exasol database.

You can connect Jupyter notebooks and marimo notebooks to your Exasol database for interactive data science and ML work. This article covers the available options, from a pre-configured environment to connecting your own notebook setup.

Choose your notebook environment

All options use PyExasol (the official Python connector) or sqlalchemy-exasol (the SQLAlchemy dialect) under the hood. Both require Python 3.10+ and Exasol 7.1+.

Exasol AI Lab

Exasol AI Lab is a Docker container with a Jupyter server, all Exasol AI extensions, and example notebooks pre-installed. It is the fastest way to start working with Exasol data in a notebook.

docker run --publish 0.0.0.0:49494:49494 exasol/ai-lab

Open http://localhost:49494 and log in with the password ailab. Run main_config.ipynb to configure your database connection. The Notebook Connector stores your credentials in an encrypted local file, so you only enter them once.

Jupyter with PyExasol

If you run your own Jupyter environment, connect to Exasol with PyExasol. It uses a WebSocket connection with encryption enabled by default, and supports fast data export to pandas, parquet, and polars.

Install:

pip install pyexasol

Connect and query:

import pyexasol

conn = pyexasol.connect(
    dsn="your-exasol-host:8563",
    user="your_user",
    password="your_password"
)

# Export query results directly to a pandas DataFrame
df = conn.export_to_pandas("SELECT * FROM my_schema.my_table LIMIT 1000")

# Or iterate over results
stmt = conn.execute("SELECT * FROM my_schema.my_table LIMIT 10")
for row in stmt:
    print(row)

PyExasol can also read and write data in parallel using multiple processes, which is useful for large datasets. See the PyExasol documentation on GitHub for parallel export/import patterns.

Jupyter with JupySQL

JupySQL adds %sql and %%sql magic commands to Jupyter, so you can write SQL directly in notebook cells. It connects to databases through SQLAlchemy. With the sqlalchemy-exasol dialect installed, you can point JupySQL at your Exasol database.

Install:

pip install jupysql sqlalchemy-exasol

Load the extension and connect:

%load_ext sql
%sql exa+websocket://your_user:your_password@your-exasol-host:8563

Run queries in SQL cells:

%%sql
SELECT department, COUNT(*) AS headcount
FROM hr.employees
GROUP BY department
ORDER BY headcount DESC

JupySQL returns results as pandas DataFrames, so you can mix SQL cells with Python analysis in the same notebook.

marimo

marimo is a reactive Python notebook where cells re-execute automatically when their dependencies change. You can connect to Exasol using PyExasol for direct queries or SQLAlchemy for marimo's built-in SQL cells.

Install:

pip install marimo pyexasol sqlalchemy-exasol

Connect with PyExasol and export to pandas:

import pyexasol

conn = pyexasol.connect(
    dsn="your-exasol-host:8563",
    user="your_user",
    password="your_password"
)

df = conn.export_to_pandas("SELECT * FROM my_schema.my_table LIMIT 1000")

For marimo's SQL cells, create a SQLAlchemy engine. marimo auto-discovers SQLAlchemy engines in your notebook namespace and makes them available in SQL cells:

from sqlalchemy import create_engine

engine = create_engine(
    "exa+websocket://your_user:your_password@your-exasol-host:8563"
)

You can then use mo.sql() to run queries that feed into downstream Python cells reactively.

Credential management

Avoid hardcoding passwords in notebook cells. Here are the recommended approaches for each environment:

For Exasol AI Lab, the Notebook Connector handles encryption of credentials automatically after you run main_config.ipynb. For standalone setups, you can use this simple pattern:

import os
import pyexasol

conn = pyexasol.connect(
    dsn=os.environ["EXASOL_DSN"],
    user=os.environ["EXASOL_USER"],
    password=os.environ["EXASOL_PASSWORD"]
)

Next steps

• Set up Exasol AI Lab for the pre-configured Jupyter environment
• Connect to AI models to run ML models on your Exasol data
• PyExasol documentation for the full connector API
• sqlalchemy-exasol on GitHub for the SQLAlchemy dialect