records
Records is a lightweight Python library for executing raw SQL queries against relational databases (Postgres, MySQL, SQLite, Oracle, RedShift, MS-SQL) with a simple, human-friendly API. It wraps SQLAlchemy and Tablib to provide straightforward query execution, result iteration, and data export to CSV, JSON, YAML, Excel, and Pandas DataFrames.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | kennethreitz/records |
| Owner | kennethreitz |
| Primary language | Python |
| License | ISC — OSI-approved |
| Stars | 7.2k |
| Forks | 567 |
| Open issues | 46 |
| Latest release | v0.6.0 (2024-03-29) |
| Last updated | 2026-02-09 |
| Source | https://github.com/kennethreitz/records |
What records is
Records abstracts SQLAlchemy's connection handling and result set management, offering a minimal query interface with safe parameterization, transaction support, and bulk operations. Results are exposed as Record objects supporting attribute and index access, with integrated Tablib-powered export for multiple formats.
Get the records source
Clone the repository and explore it locally.
git clone https://github.com/kennethreitz/records.gitcd records# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Database driver installation must be handled separately (psycopg2 for Postgres, mysqlclient for MySQL, etc.); Records does not bundle drivers.
- Connection string management via DATABASE_URL environment variable or direct instantiation; ensure secrets are not logged or hardcoded.
- Result caching occurs in-memory for iterated rows; large result sets may consume significant memory—consider pagination or streaming alternatives.
- Parameterized queries use `:parameter` syntax; validate and escape user input to prevent SQL injection, though safe parameterization is built-in.
- Transaction handling is manual (begin/commit/rollback); application must manage transaction scope and error handling explicitly.
When to avoid it — and what to weigh
- Complex ORM modeling required — If your project needs relationship mapping, lazy loading, migrations, or schema generation, use SQLAlchemy directly or Django ORM instead.
- High-performance query optimization critical — Records provides no query optimization or caching layer; raw SQLAlchemy or database-specific drivers may be more suitable for latency-sensitive workloads.
- Multi-database vendor abstraction essential — While Records supports multiple databases, dialect-specific SQL features can still cause portability issues; verify your SQL works across your target vendors.
- Active Framework Integration — Standalone library with no built-in support for Flask, Django, FastAPI, or other web frameworks; integration requires custom wiring.
License & commercial use
Records is distributed under the ISC License, a permissive, BSD-like open-source license.
ISC License permits commercial use, modification, and distribution with minimal restrictions. Requires preservation of copyright and license notice in source. No warranty or liability clause restricts commercial deployment. Consult legal counsel if bundling or modifying for mission-critical systems.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Adequate |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
Records uses SQLAlchemy's parameterized query interface, which mitigates SQL injection when parameters are properly bound (`:param` syntax). Connection strings should be managed via environment variables, not hardcoded. No security audit data or vulnerability disclosure process is documented. Input validation and authentication are the application's responsibility. Test parameterization thoroughly before production use.
Alternatives to consider
SQLAlchemy Core (direct use)
Offers identical underlying query execution with more control and no abstraction; eliminates a dependency layer for teams already using SQLAlchemy.
Django ORM
Full ORM with migrations, relationships, and admin UI; better for web applications but adds overhead if only raw SQL is needed.
Pandas + SQLAlchemy
Directly load query results into DataFrames for data science workflows; Records offers this but Pandas + SQLAlchemy is more flexible for data manipulation.
Build on records with DEV.co software developers
Devco's experienced Python engineers can help you design database layers, optimize queries, and deploy robust data pipelines using Records or other lightweight SQL libraries.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
records FAQ
Does Records support async queries?
How do I handle large result sets without loading everything into memory?
Can I use Records with an ORM?
What database drivers must I install?
Work with a software development agency
DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If records is part of your open-source databases roadmap, our team can implement, customize, migrate, and maintain it.
Need help integrating Records into your Python application?
Devco's experienced Python engineers can help you design database layers, optimize queries, and deploy robust data pipelines using Records or other lightweight SQL libraries.