mirror of
https://github.com/kennethreitz/records.git
synced 2026-06-05 06:46:17 +00:00
122 lines
3.5 KiB
ReStructuredText
122 lines
3.5 KiB
ReStructuredText
Records: Just Write SQL
|
|
=======================
|
|
|
|
Records is a very simple, but powerful, library for making raw SQL queries
|
|
to Postgres databases.
|
|
|
|
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.
|
|
|
|
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')
|
|
|
|
Rows are represented as standard Python dictionaries (``{'column-name': 'value'}``). Grab one row at a time:
|
|
|
|
.. code:: python
|
|
|
|
>>> rows.next()
|
|
{'username': 'hansolo', 'name': 'Henry Ford', 'active': True, 'timezone': datetime.datetime(2016, 2, 6, 22, 28, 23, 894202), 'user_email': 'hansolo@gmail.com'}
|
|
|
|
Or iterate over them:
|
|
|
|
.. code:: python
|
|
|
|
for row in rows:
|
|
spam_user(name=row['name'], email=row['user_email'])
|
|
|
|
Or store them all for later reference:
|
|
|
|
.. code:: python
|
|
|
|
>>> rows.all()
|
|
[{'username': ...}, {'username': ...}, {'username': ...}, ...]
|
|
|
|
Features
|
|
--------
|
|
|
|
- HSTORE support, if available.
|
|
- Iterated rows are cached for future reference.
|
|
- ``$DATABASE_URL`` environment variable support.
|
|
- Convenience ``Database.get_table_names`` method.
|
|
- Queries can be passed as strings or filenames, parameters supported.
|
|
- Query results are iterators of standard Python dictionaries (``{'column-name': 'value'}``)
|
|
|
|
Records is powered by `psycopg2 <https://pypi.python.org/pypi/psycopg2>`_
|
|
and `Tablib <http://docs.python-tablib.org/en/latest/>`_.
|
|
|
|
Data Export Functionality
|
|
-------------------------
|
|
|
|
Records also features full Tablib integration, and allows you to export
|
|
your results to CSV, XLS, JSON, or YAML with a single line of code. Excellent
|
|
for sharing data with friends, or generating reports.
|
|
|
|
.. code:: python2
|
|
|
|
>>> print rows.dataset
|
|
username|active|name |user_email |timezone
|
|
--------|------|----------|-----------------|--------------------------
|
|
hansolo |True |Henry Ford|hansolo@gmail.com|2016-02-06 22:28:23.894202
|
|
...
|
|
|
|
Export your query results to CSV:
|
|
|
|
.. code:: python2
|
|
|
|
>>> print rows.dataset.csv
|
|
username,active,name,user_email,timezone
|
|
hansolo,True,Henry Ford,hansolo@gmail.com,2016-02-06 22:28:23.894202
|
|
...
|
|
|
|
YAML:
|
|
|
|
.. code:: python
|
|
|
|
>>> print rows.dataset.yaml
|
|
- {active: true, name: Henry Ford, timezone: '2016-02-06 22:28:23.894202', user_email: hansolo@gmail.com, username: hansolo}
|
|
...
|
|
|
|
JSON:
|
|
|
|
.. code:: python
|
|
|
|
>>> print rows.dataset.json
|
|
[{"username": "hansolo", "active": true, "name": "Henry Ford", "user_email": "hansolo@gmail.com", "timezone": "2016-02-06 22:28:23.894202"}, ...]
|
|
|
|
|
|
Excel:
|
|
|
|
.. code:: python
|
|
|
|
with open('report.xls', 'wb') as f:
|
|
f.write(rows.dataset.xls)
|
|
|
|
You get the point. Of course, all other features of Tablib are also
|
|
available, so you can add/remove columns/rows, add seperators,
|
|
slice data by column, and more.
|
|
|
|
See the `Tablib Documentation <http://docs.python-tablib.org/en/latest/>`_
|
|
for more details.
|
|
|
|
Installation
|
|
------------
|
|
|
|
Of course, the recommended installation method is pip::
|
|
|
|
$ pip install records
|
|
|
|
|
|
Thank You
|
|
---------
|
|
|
|
Thanks for checking this library out! I hope you find it useful.
|
|
|
|
Of course, there's always room for improvement. Feel free to `open an issue <https://github.com/kennethreitz/records/issues>`_ so we can make Records better, stronger, faster.
|