Convert Figma logo to code with AI

kennethreitz logorecords

SQL for Humansโ„ข

7,154
574
7,154
42

Top Related Projects

11,053

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

1,399

aiopg is a library for accessing a PostgreSQL database from the asyncio

7,662

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

  1. 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)
  1. 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)
  1. 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:

  1. Install Records using pip:

    pip install records
    
  2. Import the library and create a database connection:

    import records
    
    db = records.Database('sqlite:///example.db')
    
  3. Execute queries and work with the results:

    rows = db.query('SELECT * FROM mytable')
    for row in rows:
        print(row.column_name)
    

Competitor Comparisons

11,053

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.

1,399

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
7,662

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 Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Records: SQL for Humansรขย„ยข

image

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

image

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.


Star History Chart