JupySQL

Common errors

• ModuleNotFoundError: No module named 'jupysql'

  cause The jupysql package is not installed in the current environment.
  fix Run `pip install jupysql` in your terminal or notebook environment.

• NameError: name 'sql' is not defined

  cause The JupySQL IPython extension (`%load_ext sql`) has not been loaded, so the magic commands are not available.
  fix Add `%load_ext sql` at the beginning of your notebook or session before using any `%sql` or `%%sql` commands.

• OperationalError: (psycopg2.OperationalError) connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: database "mydb" does not exist

  cause The database specified in the connection string does not exist, the server is not running, or connection details are incorrect.
  fix Verify that your database server is running, the database 'mydb' exists, and the connection string `%sql postgresql://user:password@localhost:5432/mydb` is correct. Also, ensure the necessary database driver (e.g., `psycopg2`) is installed via `pip install jupysql[postgres]`.

• TypeError: configure() got an unexpected keyword argument 'display_limit'

  cause You are using `jupysql.configure` with an argument that was renamed in version 0.10.0.
  fix Replace `display_limit` with `result_limit` in your `jupysql.configure` call. If you were configuring styles, use `from jupysql import plot; plot.configure_styles(...)` instead.

Warnings

• breaking The `jupysql.configure` function's arguments `display_limit` and `style` were changed. `display_limit` was renamed to `result_limit`, and `style` was moved to `jupysql.plot.configure_styles`.
  Fix: Update your `jupysql.configure` calls: - Replace `display_limit` with `result_limit`. - For style configuration, use `from jupysql import plot; plot.configure_styles(...)`.
• gotcha JupySQL's primary functionality relies on IPython magic commands (`%sql`, `%%sql`). These require `%load_ext sql` to be run at the beginning of each new notebook or IPython session.
  Fix: Always include `%load_ext sql` as the first line in your Jupyter notebooks or when starting an interactive IPython session where you intend to use JupySQL magic commands.
• gotcha JupySQL uses `{{variable}}` syntax for Python variable interpolation within SQL queries, which differs from standard f-strings or `.format()` methods.
  Fix: When embedding Python variables into SQL queries, use the double curly brace syntax: `my_var = 'Sales'; %sql SELECT * FROM employees WHERE department = '{{my_var}}'`.

Install

• pip install jupysql Core Installation
• pip install jupysql[postgres] With PostgreSQL Support (Example)

Imports

• %load_ext sql
  wrong:

  import jupysql

  correct:

  %load_ext sql

  JupySQL functionality is primarily exposed via IPython magic commands, which must be loaded using this extension.
• jupysql.configure

  import jupysql
  jupysql.configure(result_limit=100)

  Used for global configuration of JupySQL settings.
• jupysql.plot

  from jupysql import plot
  plot.configure_styles(template='ggplot')

  For programmatic configuration and access to plotting functions.

Quickstart

This quickstart demonstrates how to load the JupySQL extension, connect to an in-memory SQLite database, create a table, insert data, and execute a simple SQL query using the `%sql` and `%%sql` magic commands.

# Load the JupySQL extension
%load_ext sql

# Connect to an in-memory SQLite database
%sql sqlite:///:memory:

# Create a table and insert some data
%%sql
CREATE TABLE employees (
    id INTEGER PRIMARY KEY,
    name TEXT,
    department TEXT,
    salary INTEGER
);
INSERT INTO employees (id, name, department, salary) VALUES
    (1, 'Alice', 'Sales', 50000),
    (2, 'Bob', 'Marketing', 60000),
    (3, 'Charlie', 'Sales', 55000);

# Query the data
%sql SELECT * FROM employees WHERE department = 'Sales';