Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Turn your IPython console into a cross-database SQL client

Project description

ipydb is an IPython plugin for running SQL queries and viewing their results.


Some demonstration videos are available in the documentation

$ ipython
In [1] : %load_ext ipydb
In [2] : %automagic on
Automagic is ON, % prefix IS NOT needed for line magics.

In [3] : connecturl mysql://user:pass@localhost/employees
In [4] localhost/employees: tables

In [5] localhost/employees: fields departments
    dept_name                          VARCHAR(40)
    dept_no                            CHAR(4)

In [6] localhost/employees: select * from departments order by dept_name
| dept_no | dept_name          |
| d009    | Customer Service   |
| d005    | Development        |
| d002    | Finance            |
| d003    | Human Resources    |
| d001    | Marketing          |
| d004    | Production         |
| d006    | Quality Management |
| d008    | Research           |
| d007    | Sales              |


  • Tab-completion of table names, fields and joins
  • View query results in ascii-table format piped through less
  • Single-line or multi-line query editing
  • Tab-completion metadata is read in the background and persisted across sessions
  • Cross-database support, thanks to SqlAlchemy: supported databases


To install ipydb:

$ pip install ipydb

You will need a python driver for your database of choice. For example:

$ pip install mysql-python

ipydb uses SqlAlchemy to interact with databases. See the Supported Databases page for a (large!) list of supported DB-API 2.0 drivers and how to write a connection URL for your particular database.

Start ipython and load the ipydb plugin:

$ ipython
In [1]: load_ext ipydb


Documentation is available at:

Connecting to Databases

There are two ways to connect to a database with ipydb. Directly via a connection url, using the connecturl magic function, or, using a connection ‘nickname’ with the connect magic function.

1. Using connecturl

You can connect to a database using an SqlAlchemy style url as follows:

%connecturl drivername://username:password@host/database

Some examples:

In [3] : connecturl mysql://myuser:mypass@localhost/mydatabase
In [4] : connecturl sqlite:///path/to/mydb.sqlite
In [5] : connecturl sqlite:///:memory:

See the SqlAlchemy Documentation for further information.

2. Using connect and a .db-connections configuration file

For this to work, you need to create a file called .db-connections located in your home directory. .db-connections is an “ini” formatted file, parsable by python’s ConfigParser module.

Here’s an example of what ~/.db-connections might look like:

type = mysql
username = root
password = xxxx
host = localhost
database = employees

type = sqlite
database = /path/to/file.sqlite

Each database connection defined in ~/.db-connections is then referenceable via its [section heading]. So with the above .db-connections file, the following examples would work:

In [6] : connect mydb
In [7] mydb : connect myotherdb

Project details

Release history Release notifications

This version
History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
ipydb-0.0.2.tar.gz (24.7 kB) Copy SHA256 hash SHA256 Source None Sep 22, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page