records 0,5,2,1,9,4,3 python

SQL for Humans™

2 years after ISC

Records: SQL for Humans™

.. image:: :target:

.. image:: :target:

.. image::☼-1EAEDB.svg :target:

Records is a very simple, but powerful, library for making raw SQL queries to most relational databases.

Just write SQL. No bells, no whistles. This common task can be surprisingly difficult with the standard tools available. This library strives to make this workflow as simple as possible, while providing an elegant interface to work with your query results.

Database support includes Postgres, MySQL, SQLite, Oracle, and MS-SQL (drivers not included).

☤ The Basics

We know how to write SQL, so let's send some to our database:

.. code:: python

import records

db = records.Database('postgres://...')
rows = db.query('select * from active_users')    # or db.query_file('sqls/active-users.sql')

Grab one row at a time:

.. code:: python

>>> rows[0]
<Record {"username": "model-t", "active": true, "name": "Henry Ford", "user_email": "[email protected]", "timezone": "2016-02-06 22:28:23.894202"}>

Or iterate over them:

.. code:: python

for r in rows:
    print(, r.user_email)

Values can be accessed many ways: row.user_email, row['user_email'], or row[3].

Fields with non-alphanumeric characters (like spaces) are also fully supported.

Or store a copy of your record collection for later reference:

.. code:: python

>>> rows.all()
[<Record {"username": ...}>, <Record {"username": ...}>, <Record {"username": ...}>, ...]

If you're only expecting one result:

.. code:: python

>>> rows.first()
<Record {"username": ...}>

Other options include rows.as_dict() and rows.as_dict(ordered=True).

☤ Features

  • Iterated rows are cached for future reference.
  • $DATABASE_URL environment variable support.
  • Convenience Database.get_table_names method.
  • Command-line records tool for exporting queries.
  • Safe parameterization: Database.query('life=:everything', everything=42)
  • Queries can be passed as strings or filenames, parameters supported.
  • Transactions: t = Database.transaction(); t.commit()

Records is proudly powered by SQLAlchemy <> and Tablib <>.

☤ Data Export Functionality

Records also features full Tablib integration, and allows you to export your results to CSV, XLS, JSON, HTML Tables, or YAML with a single line of code. Excellent for sharing data with friends, or generating reports.

.. code:: pycon

>>> print(rows.dataset)
username|active|name      |user_email       |timezone
model-t |True  |Henry Ford|[email protected]|2016-02-06 22:28:23.894202

Comma Separated Values (CSV)

.. code:: pycon

>>> print(rows.export('csv'))
model-t,True,Henry Ford,[email protected],2016-02-06 22:28:23.894202

YAML Ain't Markup Language (YAML)

.. code:: python

>>> print(rows.export('yaml'))
- {active: true, name: Henry Ford, timezone: '2016-02-06 22:28:23.894202', user_email: [email protected], username: model-t}

JavaScript Object Notation (JSON)

.. code:: python

>>> print(rows.export('json'))
[{"username": "model-t", "active": true, "name": "Henry Ford", "user_email": "[email protected]", "timezone": "2016-02-06 22:28:23.894202"}, ...]

Microsoft Excel (xls, xlsx)

.. code:: python

with open('report.xls', 'wb') as f:

You get the point. All other features of Tablib are also available, so you can sort results, add/remove columns/rows, remove duplicates, transpose the table, add separators, slice data by column, and more.

See the Tablib Documentation <>_ for more details.

☤ Installation

Of course, the recommended installation method is pip::

$ pip install records

Related Repositories



a command line tool for generating DNS records from EC2 instances ...



commandline tools for slicing and dicing JSON records. ...



Cache Active Model Records in Rails 3 ...



Labeled records for Scala based on structural refinement types and macros. ...



Active Record like wrapper for Google App Engine Datasource in Go ...

Top Contributors

kennethreitz hrldcpr mcdallas dorosch homeworkprod btubbs Brobin whit537 EmilStenstrom radarhere jmcs marksteve tuladhar kleiram Cabalist sk2 Phrohdoh waldyrious


-   v0.4.3 zip tar
-   v0.4.2 zip tar
-   v0.4.1 zip tar
-   v0.4.0 zip tar
-   v0.3.0 zip tar
-   v0.2.0 zip tar
-   v0.1.0 zip tar