Top Related Projects
a small, expressive orm -- supports postgresql, mysql, sqlite and cockroachdb
The Database Toolkit for Python
Async database support for Python. ๐
PostgreSQL database adapter for the Python programming language
aiopg is a library for accessing a PostgreSQL database from the asyncio
MySQL client library for Python
Quick Overview
Records is a simple, lightweight Python library for making raw SQL queries to various databases. It provides a clean and intuitive interface for executing SQL commands and retrieving results, supporting multiple database backends including SQLite, PostgreSQL, and MySQL.
Pros
- Simple and easy-to-use API for database interactions
- Supports multiple database backends
- Lightweight with minimal dependencies
- Allows for raw SQL queries, giving developers full control
Cons
- Limited ORM-like features compared to more comprehensive libraries
- May require more manual SQL writing for complex operations
- Not as actively maintained as some other database libraries
- Limited documentation and examples available
Code Examples
- Connecting to a database and executing a simple query:
import records
db = records.Database('postgresql://user:pass@localhost/mydatabase')
rows = db.query('SELECT * FROM users')
for row in rows:
print(row.name, row.email)
- Executing a parameterized query:
db = records.Database('sqlite:///example.db')
rows = db.query('SELECT * FROM products WHERE price > :price', price=50)
for row in rows:
print(row.name, row.price)
- Inserting data and retrieving the last inserted ID:
db = records.Database('mysql://user:pass@localhost/mydatabase')
query = 'INSERT INTO customers (name, email) VALUES (:name, :email)'
result = db.query(query, name='John Doe', email='john@example.com')
print(f"Last inserted ID: {result.last_insert_id}")
Getting Started
To get started with Records, follow these steps:
-
Install Records using pip:
pip install records
-
Import the library and create a database connection:
import records db = records.Database('sqlite:///example.db')
-
Execute queries and work with the results:
rows = db.query('SELECT * FROM mytable') for row in rows: print(row.column_name)
Competitor Comparisons
a small, expressive orm -- supports postgresql, mysql, sqlite and cockroachdb
Pros of Peewee
- More comprehensive ORM with advanced features like model definition, querying, and migrations
- Supports multiple database backends (SQLite, MySQL, PostgreSQL)
- Active development and larger community support
Cons of Peewee
- Steeper learning curve due to more complex API
- Requires defining models and schema upfront
- May be overkill for simple database operations
Code Comparison
Records:
import records
db = records.Database('postgresql://user:pass@host/dbname')
rows = db.query('SELECT * FROM users')
Peewee:
from peewee import *
db = PostgresqlDatabase('dbname', user='user', password='pass', host='host')
class User(Model):
name = CharField()
class Meta:
database = db
users = User.select()
Summary
Records is designed for simplicity and ease of use, focusing on raw SQL queries and returning results as dictionaries. It's ideal for quick scripts and simple database interactions.
Peewee is a full-featured ORM that provides a higher level of abstraction, making it suitable for larger applications with complex database schemas. It offers more control and features but requires more setup and knowledge of ORM concepts.
Choose Records for straightforward database queries and rapid development, or Peewee for more structured and scalable database interactions in larger projects.
The Database Toolkit for Python
Pros of SQLAlchemy
- More powerful and feature-rich ORM with extensive querying capabilities
- Supports multiple database backends and complex relationships
- Offers fine-grained control over database operations and performance optimization
Cons of SQLAlchemy
- Steeper learning curve due to its complexity and extensive features
- Requires more boilerplate code for simple database operations
- Can be overkill for small projects or simple database interactions
Code Comparison
SQLAlchemy:
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
class User(Base):
__tablename__ = 'users'
id = Column(Integer, primary_key=True)
name = Column(String)
Records:
import records
db = records.Database('postgresql://...')
rows = db.query('SELECT * FROM users')
for row in rows:
print(row.name)
SQLAlchemy provides a more structured approach with ORM capabilities, while Records offers a simpler, SQL-focused interface for quick database interactions. SQLAlchemy is better suited for complex applications with intricate data models, whereas Records excels in scenarios requiring rapid prototyping or simple database queries.
Async database support for Python. ๐
Pros of Databases
- More actively maintained with regular updates
- Supports async operations, beneficial for high-performance applications
- Offers a wider range of database backends, including SQLite, PostgreSQL, and MySQL
Cons of Databases
- Steeper learning curve due to more complex API
- Requires additional dependencies for certain database backends
- May be overkill for simple database operations
Code Comparison
Records:
import records
db = records.Database('postgresql://...')
rows = db.query('SELECT * FROM users')
Databases:
import databases
import sqlalchemy
database = databases.Database('postgresql://...')
metadata = sqlalchemy.MetaData()
users = sqlalchemy.Table('users', metadata, autoload=True, autoload_with=engine)
async def fetch_users():
query = users.select()
return await database.fetch_all(query)
Summary
Records is simpler and more straightforward for basic database operations, making it ideal for quick scripts and small projects. Databases, on the other hand, offers more advanced features and better performance for larger applications, especially those requiring async support. The choice between the two depends on the specific needs of your project and your familiarity with more complex database interactions.
PostgreSQL database adapter for the Python programming language
Pros of psycopg2
- More low-level control over database operations
- Highly optimized for PostgreSQL, offering better performance
- Supports advanced PostgreSQL features and data types
Cons of psycopg2
- Steeper learning curve, especially for beginners
- Requires more boilerplate code for common operations
- Less abstraction, leading to potentially more complex code
Code Comparison
psycopg2:
import psycopg2
conn = psycopg2.connect("dbname=test user=postgres")
cur = conn.cursor()
cur.execute("SELECT * FROM users WHERE name = %s", ("John",))
results = cur.fetchall()
Records:
import records
db = records.Database('postgresql://postgres@localhost/test')
results = db.query('SELECT * FROM users WHERE name = :name', name='John')
Summary
psycopg2 is a powerful, low-level PostgreSQL adapter for Python, offering fine-grained control and optimized performance. It's ideal for advanced users who need direct access to PostgreSQL features. However, it requires more code and has a steeper learning curve.
Records, on the other hand, provides a higher-level abstraction, simplifying database operations with a more user-friendly API. It's built on top of SQLAlchemy and supports multiple database backends, making it more versatile but potentially less optimized for PostgreSQL-specific use cases.
Choose psycopg2 for PostgreSQL-specific projects requiring advanced features and optimized performance. Opt for Records when you need a simpler API, database agnosticism, or rapid development.
aiopg is a library for accessing a PostgreSQL database from the asyncio
Pros of aiopg
- Supports asynchronous programming with Python's asyncio
- Designed specifically for PostgreSQL, offering optimized performance
- Provides both low-level and high-level APIs for flexibility
Cons of aiopg
- Limited to PostgreSQL databases only
- Steeper learning curve due to asynchronous nature
- Requires more complex setup compared to Records
Code Comparison
aiopg example:
async with aiopg.create_pool(dsn) as pool:
async with pool.acquire() as conn:
async with conn.cursor() as cur:
await cur.execute("SELECT * FROM users")
rows = await cur.fetchall()
Records example:
db = records.Database('postgresql://...')
rows = db.query('SELECT * FROM users')
Key Differences
- aiopg is focused on asynchronous operations, while Records provides a simpler synchronous interface
- Records supports multiple database types, whereas aiopg is PostgreSQL-specific
- aiopg offers more fine-grained control over database connections and cursors
- Records provides a more user-friendly API for quick database queries and data manipulation
Use Cases
- Choose aiopg for high-performance, scalable PostgreSQL applications leveraging asyncio
- Opt for Records when simplicity and database agnosticism are priorities, especially for rapid prototyping or small-scale projects
MySQL client library for Python
Pros of PyMySQL
- Direct MySQL database access with low-level control
- Lightweight and focused solely on MySQL connectivity
- Supports both Python 2 and 3
Cons of PyMySQL
- Requires more boilerplate code for common operations
- Limited to MySQL databases only
- No built-in query result abstraction
Code Comparison
PyMySQL:
import pymysql
conn = pymysql.connect(host='localhost', user='user', password='password', db='database')
cursor = conn.cursor()
cursor.execute("SELECT * FROM users")
results = cursor.fetchall()
Records:
import records
db = records.Database('mysql://user:password@localhost/database')
rows = db.query('SELECT * FROM users')
Key Differences
Records provides a higher-level abstraction for database operations, supporting multiple database types and offering a more Pythonic interface. It simplifies common tasks and reduces boilerplate code.
PyMySQL is more focused and provides direct, low-level access to MySQL databases. It offers more control but requires more code for basic operations.
Records is better suited for rapid development and prototyping, while PyMySQL might be preferred for projects requiring fine-grained control over MySQL connections and operations.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Records: SQL for Humansรขยยข
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 RedShift, 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:
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:
>>> rows[0]
<Record {"username": "model-t", "active": true, "name": "Henry Ford", "user_email": "model-t@gmail.com", "timezone": "2016-02-06 22:28:23.894202"}>
Or iterate over them:
for r in rows:
print(r.name, 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:
>>> rows.all()
[<Record {"username": ...}>, <Record {"username": ...}>, <Record {"username": ...}>, ...]
If you're only expecting one result:
>>> 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()
. - Bulk actions:
Database.bulk_query()
&Database.bulk_query_file()
.
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, YAML, or Pandas DataFrames with a single line of code. Excellent for sharing data with friends, or generating reports.
>>> print(rows.dataset)
username|active|name |user_email |timezone
--------|------|----------|-----------------|--------------------------
model-t |True |Henry Ford|model-t@gmail.com|2016-02-06 22:28:23.894202
...
Comma Separated Values (CSV)
>>> print(rows.export('csv'))
username,active,name,user_email,timezone
model-t,True,Henry Ford,model-t@gmail.com,2016-02-06 22:28:23.894202
...
YAML Ain't Markup Language (YAML)
>>> print(rows.export('yaml'))
- {active: true, name: Henry Ford, timezone: '2016-02-06 22:28:23.894202', user_email: model-t@gmail.com, username: model-t}
...
JavaScript Object Notation (JSON)
>>> print(rows.export('json'))
[{"username": "model-t", "active": true, "name": "Henry Ford", "user_email": "model-t@gmail.com", "timezone": "2016-02-06 22:28:23.894202"}, ...]
Microsoft Excel (xls, xlsx)
with open('report.xls', 'wb') as f:
f.write(rows.export('xls'))
Pandas DataFrame
>>> rows.export('df')
username active name user_email timezone
0 model-t True Henry Ford model-t@gmail.com 2016-02-06 22:28:23.894202
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 pipenv:
$ pipenv install records[pandas]
รขยยจรฐยยยฐรขยยจ
รขยยค 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 so we can make Records better, stronger, faster.
Top Related Projects
a small, expressive orm -- supports postgresql, mysql, sqlite and cockroachdb
The Database Toolkit for Python
Async database support for Python. ๐
PostgreSQL database adapter for the Python programming language
aiopg is a library for accessing a PostgreSQL database from the asyncio
MySQL client library for Python
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot