kennethreitz/records

Records is a Python library for running raw SQL queries against relational databases with as little setup as possible. It is designed for people who already know SQL and want to write queries directly rather than learning a separate object-relational mapping framework. The library handles the connection and wraps the results in convenient row objects, then stays out of the way. Connecting to a database takes one line using a standard URL string. Queries are passed as plain SQL strings or loaded from a file. Results can be iterated, accessed by index, or accessed by column name using simple attribute syntax such as row.email. Safe query parameterization is supported to avoid injection risks. Rows are cached after the first iteration so the result set can be accessed multiple times without hitting the database again. Transactions and bulk inserts are also available. One of the more useful features is the built-in export capability. Query results can be exported in a single line to CSV, JSON, YAML, HTML tables, Excel files, or Pandas DataFrames. This is powered by the Tablib library under the hood. A command-line tool is also included for running queries and exporting results without writing any Python code. The library works with PostgreSQL, MySQL, SQLite, Oracle, Microsoft SQL Server, and Amazon Redshift. Database drivers are not included and need to be installed separately for the specific database being used. The underlying database connection is managed by SQLAlchemy, which handles the compatibility across all those databases. Records is a straightforward utility for situations where a full ORM would add unnecessary complexity. It is well suited to data exports, reporting scripts, and one-off analysis tasks where SQL is already the natural language and the goal is just to get the results out cleanly.