Eloquent Documentation: Release 0.4

Eloquent Documentation
Release 0.4
Sbastien Eustace
May 24, 2015
Contents
Installation
Basic Usage
2.1 Configuration . . . . . . .
2.2 Read / Write connections .
2.3 Running queries . . . . .
2.4 Database transactions . .
2.5 Accessing connections . .
2.6 Query logging . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5
5
5
6
7
7
8
Query Builder
3.1 Introduction . . .
3.2 Selects . . . . . .
3.3 Joins . . . . . . .
3.4 Advanced where .
3.5 Aggregates . . . .
3.6 Raw expressions .
3.7 Inserts . . . . . .
3.8 Updates . . . . . .
3.9 Deletes . . . . . .
3.10 Unions . . . . . .
3.11 Pessimistic locking
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9
9
9
11
12
12
13
13
14
14
14
15
The ORM
4.1 Introduction . . . . . . . .
4.2 Basic Usage . . . . . . . .
4.3 Mass assignment . . . . . .
4.4 Insert, update and delete . .
4.5 Soft deleting . . . . . . . .
4.6 Relationships . . . . . . . .
4.7 Querying relations . . . . .
4.8 Eager loading . . . . . . . .
4.9 Inserting related models . .
4.10 Touching parent timestamps
4.11 Working with pivot table . .
4.12 Timestamps . . . . . . . . .
4.13 Query Scopes . . . . . . . .
4.14 Global Scopes . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
17
17
17
19
20
21
22
27
29
30
32
32
33
33
34
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4.15
4.16
4.17
4.18
5
ii
Accessors & mutators . . . . . .

Date mutators . . . . . . . . . . .
Attributes casting . . . . . . . . .
Converting to dictionaries / JSON
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
35
36
37
38
Schema Builder
5.1 Introduction . . . . . . . . . . . . .
5.2 Creating and dropping tables . . . . .
5.3 Adding columns . . . . . . . . . . .
5.4 Changing columns . . . . . . . . . .
5.5 Renaming columns . . . . . . . . . .
5.6 Dropping columns . . . . . . . . . .
5.7 Checking existence . . . . . . . . . .
5.8 Adding indexes . . . . . . . . . . . .
5.9 Dropping indexes . . . . . . . . . . .
5.10 Foreign keys . . . . . . . . . . . . .
5.11 Dropping timestamps and soft deletes
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
41
41
41
42
43
43
43
44
44
44
44
45
Migrations
6.1 Creating Migrations . .
6.2 Running Migrations . .
6.3 Rolling back migrations
6.4 Getting migrations status
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
47
47
49
49
49
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Eloquent Documentation, Release 0.4
The Eloquent ORM provides a simple yet beautiful ActiveRecord implementation.

It is inspired by the database part of the Laravel framework, but modified to be more pythonic.
Contents
Contents
CHAPTER 1
Installation
You can install Eloquent in 2 different ways:

The easier and more straightforward is to use pip
pip install eloquent
Install from source using the official repository (https://github.com/sdispater/eloquent)

Note: The different dbapi packages are not part of the package dependencies, so you must install them in order to
connect to corresponding databases:
PostgreSQL: pyscopg2
MySQL: PyMySQL or mysqlclient
SQLite: The sqlite3 module is bundled with Python by default
Chapter 1. Installation
CHAPTER 2
Basic Usage
2.1 Configuration
All you need to get you started is the configuration describing your database connections and passing it to a
DatabaseManager instance.
from eloquent import DatabaseManager
config = {
'mysql': {
'driver': 'mysql',
'host': 'localhost',
'database': 'database',
'user': 'root',
'password': '',
'prefix': ''
}
}
db = DatabaseManager(config)
If you have multiple databases configured you can specify which one is the default:
config = {
'default': 'mysql',
'mysql': {
'driver': 'mysql',
'user': 'root',
'password': '',
'prefix': ''
}
}
2.2 Read / Write connections

Sometimes you may wish to use one database connection for SELECT statements, and another for INSERT, UPDATE,
and DELETE statements. Eloquent makes this easy, and the proper connections will always be used whether you use
raw queries, the query builder or the actual ORM
Here is an example of how read / write connections should be configured:

config = {
'mysql': {
'read': [
'host': '192.168.1.1'
],
'read': [
'host': '192.168.1.2'
],
'driver': 'mysql',
'username': 'root',
'password': '',
'prefix': ''
}
}
Note that two keys have been added to the configuration dictionary: read and write. Both of these keys have dictionary values containing a single key: host. The rest of the database options for the read and write connections will
be merged from the main mysql dictionary. So, you only need to place items in the read and write dictionaries
if you wish to override the values in the main dictionary. So, in this case, 192.168.1.1 will be used as the read
connection, while 192.168.1.2 will be used as the write connection. The database credentials, prefix, character
set, and all other options in the main mysql dictionary will be shared across both connections.
2.3 Running queries

Once you have configured your database connection, you can run queries.
2.3.1 Running a select query

results = db.select('select * from users where id = ?', [1])
The select method will always return a list of results.
2.3.2 Running an insert statement

db.insert('insert into users (id, name) values (?, ?)', [1, 'John'])
2.3.3 Running an update statement

db.update('update users set votes = 100 where name = ?', ['John'])
2.3.4 Running a delete statement

db.delete('delete from users')
Note: The update and delete statements return the number of rows affected by the operation.
Chapter 2. Basic Usage
2.3.5 Running a general statement

db.statement('drop table users')
2.4 Database transactions

To run a set of operations within a database transaction, you can use the transaction method which is a context
manager:
with db.transaction():
db.table('users').update({votes: 1})
db.table('posts').delete()
Note: Any exception thrown within a transaction block will cause the transaction to be rolled back automatically.
Sometimes you may need to start a transaction yourself:
db.begin_transaction()
You can rollback a transaction with the rollback method:

db.rollback()
You can also commit a transaction via the commit method:

db.commit()
Warning: By default, all underlying DBAPI connections are set to be in autocommit mode meaning that you
dont need to explicitly commit after each operation.
2.5 Accessing connections

When using multiple connections, you can access them via the connection() method:
users = db.connection('foo').table('users').get()
You also can access the raw, underlying dbapi connection instance:
db.connection().get_connection()
Sometimes, you may need to reconnect to a given database:

db.reconnect('foo')
If you need to disconnect from the given database, use the disconnect method:
db.disconnect('foo')
2.4. Database transactions
2.6 Query logging

Eloquent can log all queries that are executed. By default, this is turned off to avoid unnecessary overhead, but if you
want to activate it you can either add a log_queries key to the config dictionary:
config = {
'mysql': {
'driver': 'mysql',
'username': 'root',
'password': '',
'prefix': '',
'log_queries': True
}
}
or activate it later on:

db.connection().enable_query_log()
Now, the logger eloquent.connection.queries will be logging queries at debug level:

Executed SELECT COUNT(*) AS aggregate FROM "users" in 1.18ms
Executed INSERT INTO "users" ("email", "name", "updated_at") VALUES ('[email protected]', 'foo', '2015-04-0
Note: These log messages above are those logged for MySQL and PostgreSQL connections which support displaying full request sent to the database. For SQLite connections, the format is as follows:
Executed ('SELECT COUNT(*) AS aggregate FROM "users"', []) in 0.12ms
2.6.1 Customizing log messages

Each log record sent by the logger comes with the query and elapsed_time keywords so that you can customize
the log message:
import logging
logger = logging.getLogger('eloquent.connection.queries')
logger.setLevel(logging.DEBUG)
formatter = logging.Formatter('It took %(elapsed_time)sms to execute the query %(query)s')
handler = logging.StreamHandler()
handler.setFormatter(formatter)
logger.addHandler(handler)
Chapter 2. Basic Usage
CHAPTER 3
Query Builder
3.1 Introduction
The database query builder provides a fluent interface to create and run database queries. It can be used to perform
most database operations in your application, and works on all supported database systems.
Note: Since Eloquent uses DBAPI packages under the hood, there is no need to clean parameters passed as bindings.
Note: The underlying DBAPI connections are automatically configured to return dictionaries rather than the default
tuple representation.
3.2 Selects
3.2.1 Retrieving all row from a table
users = db.table('users').get()
for user in users:
print(user['name'])
3.2.2 Chunking results from a table

for users in db.table('users').chunk(100):
for user in users:
# ...
3.2.3 Retrieving a single row from a table

user = db.table('users').where('name', 'John').first()
print(user['name'])
3.2.4 Retrieving a single column from a row

user = db.table('users').where('name', 'John').pluck('name')
3.2.5 Retrieving a list of column values

roles = db.table('roles').lists('title')
This method will return a list of role titles. It can return a dictionary if you pass an extra key parameter.
roles = db.table('roles').lists('title', 'name')
3.2.6 Specifying a select clause

users = db.table('users').select('name', 'email').get()
users = db.table('users').distinct().get()
users = db.table('users').select('name as user_name').get()
3.2.7 Adding a select clause to an existing query

query = db.table('users').select('name')
users = query.add_select('age').get()
3.2.8 Using where operators

users = db.table('users').where('age', '>', 25).get()
3.2.9 Or statements
users = db.table('users').where('age', '>', 25).or_where('name', 'John').get()
3.2.10 Using Where Between

users = db.table('users').where_between('age', [25, 35]).get()
3.2.11 Using Where Not Between

users = db.table('users').where_not_between('age', [25, 35]).get()
10
Chapter 3. Query Builder
3.2.12 Using Where In

users = db.table('users').where_in('id', [1, 2, 3]).get()
users = db.table('users').where_not_in('id', [1, 2, 3]).get()
3.2.13 Using Where Null to find records with null values

users = db.table('users').where_null('updated_at').get()
3.2.14 Order by, group by and having

query = db.table('users').order_by('name', 'desc')
query = query.group_by('count')
query = query.having('count', '>', 100)
users = query.get()
3.2.15 Offset and limit

users = db.table('users').skip(10).take(5).get()
users = db.table('users').offset(10).limit(5).get()
3.3 Joins
The query builder can also be used to write join statements.
3.3.1 Basic join statement

db.table('users') \
.join('contacts', 'users.id', '=', 'contacts.user_id') \
.join('orders', 'users.id', '=', 'orders.user_id') \
.select('users.id', 'contacts.phone', 'orders.price') \
.get()
3.3.2 Left join statement

db.table('users').left_join('posts', 'users.id', '=', 'posts.user_id').get()
You can also specify more advance join clauses:

clause = JoinClause('contacts').on('users.id', '=', 'contacts.user_id').or_on(...)
db.table('users').join(clause).get()
3.3. Joins
11
If you would like to use a where style clause on your joins, you may use the where and orWhere methods on a join.
Instead of comparing two columns, these methods will compare the column against a value:
clause = JoinClause('contacts').on('users.id', '=', 'contacts.user_id').where('contacts.user_id', '>'

db.table('users').join(clause).get()
3.4 Advanced where

Sometimes you may need to create more advanced where clauses such as where exists or nested parameter groupings. It is pretty easy to do with the Eloquent query builder
3.4.1 Parameter grouping

db.table('users') \
.where('name', '=', 'John') \
.or_where(
db.query().where('votes', '>', 100).where('title', '!=', 'admin')
).get()
The query above will produce the following SQL:

SELECT * FROM users WHERE name = 'John' OR (votes > 100 AND title != 'Admin')
3.4.2 Exists statement

db.table('users').where_exists(
db.table('orders').select(db.raw(1)).where_raw('order.user_id = users.id')
)
The query above will produce the following SQL:

SELECT * FROM users
WHERE EXISTS (
SELECT 1 FROM orders WHERE orders.user_id = users.id
)
3.5 Aggregates
The query builder also provides a variety of aggregate methods, such as count, max, min, avg, and sum.
users = db.table('users').count()
price = db.table('orders').max('price')
price = db.table('orders').min('price')
price = db.table('orders').avg('price')
total = db.table('users').sum('votes')
12
3.6 Raw expressions

Sometimes you may need to use a raw expression in a query. These expressions will be injected into the query as
strings, so be careful not to create any SQL injection points! To create a raw expression, you may use the raw()
method:
db.table('users') \
.select(db.raw('count(*) as user_count, status')) \
.where('status', '!=', 1) \
.group_by('status') \
.get()
3.7 Inserts
3.7.1 Insert records into a table
db.table('users').insert(email='[email protected]', votes=0)
db.table('users').insert({
'email': '[email protected]',
'votes': 0
})
Note: It is important to note that there is two notations available. The reason is quite simple: the dictionary notation,
though a little less practical, is here to handle columns names which cannot be passed as keywords arguments.
3.7.2 Inserting records into a table with an auto-incrementing ID

If the table has an auto-incrementing id, use insert_get_id to insert a record and retrieve the id:
id = db.table('users').insert_get_id({
'email': '[email protected]',
'votes': 0
})
3.7.3 Inserting multiple record into a table

db.table('users').insert([
{'email': '[email protected]', 'votes': 0},
{'email': '[email protected]', 'votes': 0}
])
3.6. Raw expressions
13
3.8 Updates
3.8.1 Updating records
db.table('users').where('id', 1).update(votes=1)
db.table('users').where('id', 1).update({'votes': 1})
Note: Like the insert statement, there is two notations available. The reason is quite simple: the dictionary
notation, though a little less practical, is here to handle columns names which cannot be passed as keywords arguments.
3.8.2 Incrementing or decrementing the value of a column

db.table('users').increment('votes')
# Increment the value by 1
db.table('users').increment('votes', 5)
db.table('users').decrement('votes')
# Increment the value by 5
# Decrement the value by 1
db.table('users').decrement('votes', 5)
# Decrement the value by 5
You can also specify additional columns to update:

db.table('users').increment('votes', 1, name='John')
3.9 Deletes
3.9.1 Deleting records
db.table('users').where('age', '<', 25).delete()
3.9.2 Delete all records

db.table('users').delete()
3.9.3 Truncate
db.table('users').truncate()
3.10 Unions
The query builder provides a quick and easy way to union two queries:
14
first = db.table('users').where_null('first_name')
users = db.table('users').where_null('last_name').union(first).get()
The union_all method is also available.
3.11 Pessimistic locking

The query builder includes a few functions to help you do pessimistic locking on your SELECT statements.
To run the SELECT statement with a shared lock, you may use the shared_lock method on a query:
db.table('users').where('votes', '>', 100).shared_lock().get()
To lock for update on a SELECT statement, you may use the lock_for_update method on a query:
db.table('users').where('votes', '>', 100).lock_for_update().get()
3.11. Pessimistic locking
15
16
CHAPTER 4
The ORM
4.1 Introduction
The ORM provides a simple ActiveRecord implementation for working with your databases. Each database table has
a corresponding Model which is used to interact with that table.
Before getting started, be sure to have configured a DatabaseManager as seen in the Basic Usage section.
from eloquent import DatabaseManager
config = {
'mysql': {
'driver': 'mysql',
'username': 'root',
'password': '',
'prefix': ''
}
}
4.2 Basic Usage

To actually get started, you need to tell the ORM to use the configured DatabaseManager for all models inheriting
from the Model class:
from eloquent import Model
Model.set_connection_resolver(db)
And thats pretty much it. You can now define your models.
4.2.1 Defining a Model

class User(Model):
pass
17
Note that we did not tell the ORM which table to use for the User model. The plural snake case name of the class
name will be used as the table name unless another name is explicitly specified. In this case, the ORM will assume the
User model stores records in the users table. You can specify a custom table by defining a __table__ property
on your model:
class User(Model):
__table__ = 'my_users'
Note: The ORM will also assume that each table has a primary key column named id. You can define a
__primary_key__ property to override this convention. Likewise, you can define a __connection__ property to override the name of the database connection that should be used when using the model.
Once a model is defined, you are ready to start retrieving and creating records in your table. Note that you will need to
place updated_at and created_at columns on your table by default. If you do not wish to have these columns
automatically maintained, set the __timestamps__ property on your model to False.
4.2.2 Retrieving all models

users = User.all()
4.2.3 Retrieving a record by primary key

user = User.find(1)
print(user.name)
Note: All methods available on the Query Builder are also available when querying models.
4.2.4 Retrieving a Model by primary key or raise an exception

Sometimes it may be useful to throw an exception if a model is not found. You can use the find_or_fail method
for that, which will raise a ModelNotFound exception.
model = User.find_or_fail(1)
model = User.where('votes', '>', 100).first_or_fail()
4.2.5 Querying using models

users = User.where('votes', '>', 100).take(10).get()
for user in users:
print(user.name)
4.2.6 Aggregates
You can also use the query builder aggregate functions:
18
Chapter 4. The ORM
count = User.where('votes', '>', 100).count()
If you feel limited by the builders fluent interface, you can use the where_raw method:
users = User.where_raw('age > ? and votes = 100', [25]).get()
4.2.7 Chunking Results

If you need to process a lot of records, you can use the chunk method to avoid consuming a lot of RAM:
for users in User.chunk(100):
for user in users:
# ...
4.2.8 Specifying the query connection

You can specify which database connection to use when querying a model by using the on method:
user = User.on('connection-name').find(1)
If you are using Read / Write connections, you can force the query to use the write connection with the following
method:
user = User.on_write_connection().find(1)
4.3 Mass assignment

When creating a new model, you pass attributes to the model constructor. These attributes are then assigned to the
model via mass-assignment. Though convenient, this can be a serious security concern when passing user input into a
model, since the user is then free to modify any and all of the models attributes. For this reason, all models protect
against mass-assignment by default.
To get started, set the __fillable__ or __guarded__ properties on your model.
4.3.1 Defining fillable attributes on a model

The __fillable__ property specifies which attributes can be mass-assigned.
class User(Model):
__fillable__ = ['first_name', 'last_name', 'email']
4.3.2 Defining guarded attributes on a model

The __guarded__ is the inverse and acts as blacklist.
class User(Model):
__guarded__ = ['id', 'password']
4.3. Mass assignment
19
Warning: When using __guarded__, you should still never pass any user input directly since any attribute that
is not guarded can be mass-assigned.
You can also block all attributes from mass-assignment:
__guarded__ = ['*']
4.4 Insert, update and delete

4.4.1 Saving a new model
To create a new record in the database, simply create a new model instance and call the save method.
user = User()
user.name = 'John'
user.save()
Note: Your models will probably have auto-incrementing primary keys. However, if you wish to maintain your own
primary keys, set the __autoincrementing__ property to False.
You can also use the create method to save a model in a single line, but you will need to specify either the
__fillable__ or __guarded__ property on the model since all models are protected against mass-assigment by
default.
After saving or creating a new model with auto-incrementing IDs, you can retrieve the ID by accessing the objects
id attribute:
inserted_id = user.id
4.4.2 Using the create method

# Create a new user in the database
user = User.create(name='John')
# Retrieve the user by attributes, or create it if it does not exist
user = User.first_or_create(name='John')
# Retrieve the user by attributes, or instantiate it if it does not exist
user = User.first_or_new(name='John')
4.4.3 Updating a retrieved model

user = User.find(1)
user.name = 'Foo'
user.save()
You can also run updates as queries against a set of models:
20
Chapter 4. The ORM
affected_rows = User.where('votes', '>', 100).update(status=2)
4.4.4 Saving a model and relationships

Sometimes you may wish to save not only a model, but also all of its relationships. To do so, you can use the push
method:
user.push()
4.4.5 Deleting an existing model

To delete a model, simply call the delete model:
user = User.find(1)
user.delete()
4.4.6 Deleting an existing model by key

User.destroy(1)
User.destroy(1, 2, 3)
You can also run a delete query on a set of models:

affected_rows = User.where('votes', '>' 100).delete()
4.4.7 Updating only the models timestamps

If you want to only update the timestamps on a model, you can use the touch method:
user.touch()
4.5 Soft deleting

When soft deleting a model, it is not actually removed from your database. Instead, a deleted_at timestamp is set
on the record. To enable soft deletes for a model, make it inherit from the SoftDeletes mixin:
from eloquent import Model, SoftDeletes
class User(Model, SoftDeletes):

__dates__ = ['deleted_at']
To add a deleted_at column to your table, you may use the soft_deletes method from a migration (see
Schema Builder):
4.5. Soft deleting
21
table.soft_deletes()
Now, when you call the delete method on the model, the deleted_at column will be set to the current timestamp.
When querying a model that uses soft deletes, the deleted models will not be included in query results.
4.5.1 Forcing soft deleted models into results

To force soft deleted models to appear in a result set, use the with_trashed method on the query:
users = User.with_trashed().where('account_id', 1).get()
The with_trashed method may be used on a defined relationship:

user.posts().with_trashed().get()
4.6 Relationships
Eloquent makes managing and working with relationships easy. It supports many types of relationships:
One To One
One To Many
Many To Many
Has Many Through
Polymorphic relations
Many To Many polymorphic relations
4.6.1 One To One

Defining a One To One relationship
A one-to-one relationship is a very basic relation. For instance, a User model might have a Phone. We can define
this relation with the ORM:
class User(Model):
@property
def phone(self):
return self.has_one(Phone)
The first argument passed to the has_one method is the class of the related model. Once the relationship is defined,
we can retrieve it using Dynamic properties:
phone = User.find(1).phone
The SQL performed by this statement will be as follow:

SELECT * FROM users WHERE id = 1
SELECT * FROM phones WHERE user_id = 1
22
Chapter 4. The ORM
The Eloquent ORM assumes the foreign key of the relationship based on the model name. In this case, Phone model
is assumed to use a user_id foreign key. If you want to override this convention, you can pass a second argument
to the has_one method. Furthermore, you may pass a third argument to the method to specify which local column
should be used for the association:
return self.has_one(Phone, 'foreign_key')
return self.has_one(Phone, 'foreign_key', 'local_key')
Defining the inverse of the relation

To define the inverse of the relationship on the Phone model, you can use the belongs_to method:
class Phone(Model):
@property
def user(self):
return self.belongs_to(User)
In the example above, the Eloquent ORM will look for a user_id column on the phones table. You can define a
different foreign key column, you can pass it as the second argument of the belongs_to method:
return self.belongs_to(User, 'local_key')
Additionally, you pass the third parameter which specifies the name of the associated column on the parent table:
return self.belongs_to(User, 'local_key', 'parent_key')
4.6.2 One To Many

An example of a one-to-many relation is a blog post that has many comments:
class Post(Model):
@property
def comments(self):
return self.has_many(Comment)
Now you can access the posts comments via Dynamic properties:
comments = Post.find(1).comments
Again, you may override the conventional foreign key by passing a second argument to the has_many method. And,
like the has_one relation, the local column may also be specified:
return self.has_many(Comment, 'foreign_key')
return self.has_many(Comment, 'foreign_key', 'local_key')
Defining the inverse of the relation:

To define the inverse of the relationship on the Comment model, we use the belongs_to method:
4.6. Relationships
23
class Comment(Model):
@property
def post(self):
return self.belongs_to(Post)
4.6.3 Many To Many

Many-to-many relations are a more complicated relationship type. An example of such a relationship is a user with
many roles, where the roles are also shared by other users. For example, many users may have the role of Admin.
Three database tables are needed for this relationship: users, roles, and roles_users. The roles_users
table is derived from the alphabetical order of the related table names, and should have the user_id and role_id
columns.
We can define a many-to-many relation using the belongs_to_many method:
class User(Model):
@property
def roles(self):
return self.belongs_to_many(Role)
Now, we can retrieve the roles through the User model:

roles = User.find(1).roles
If you want to use an unconventional table name for your pivot table, you can pass it as the second argument to the
belongs_to_many method:
return self.belongs_to_many(Role, 'user_role')
You can also override the conventional associated keys:

return self.belongs_to_many(Role, 'user_role', 'user_id', 'foo_id')
Of course, you also can define the inverse og the relationship on the Role model:
class Role(Model):
@property
def users(self):
return self.belongs_to_many(Role)
4.6.4 Has Many Through

The has many through relation provides a convenient short-cut for accessing distant relations via an intermediate
relation. For example, a Country model might have many Post through a User model. The tables for this
relationship would look like this:
countries
id - integer
name - string
users:
id - integer
country_id - integer
24
Chapter 4. The ORM
name - string
posts:
id - integer
user_id - integer
title - string
Even though the posts table does not contain a country_id column, the has_many_through relation will
allow access a countrys posts via country.posts:
class Country(Model):
@property
def posts(self):
return self.has_many_through(Post, User)
If you want to manually specify the keys of the relationship, you can pass them as the third and fourth arguments to
the method:
return self.has_many_through(Post, User, 'country_id', 'user_id')
4.6.5 Polymorphic relations

New in version 0.3.
Polymorphic relations allow a model to belong to more than one other model, on a single association. For example,
you might have a Photo model that belongs to either a Staff model or an Order model.
class Photo(Model):
@property
def imageable(self):
return self.morph_to()
class Staff(Model):
@property
def photos(self):
return self.morph_many(Photo, 'imageable')
class Order(Model):
@property
def photos(self):
return self.morph_many(Photo, 'imageable')
Retrieving a polymorphic relation

Now, we can retrieve the photos for either a staff member or an order:
staff = Staff.find(1)
for photo in staff.photos:
# ...
4.6. Relationships
25
Retrieving the owner of a polymorphic relation

You can also, and this is where polymorphic relations shine, access the staff or order model from the Photo model:
photo = Photo.find(1)
imageable = photo.imageable
The imageable relation on the Photo model will return either a Staff or Order instance, depending on which
type of model owns the photo.
Polymorphic relation table structure
To help understand how this works, lets explore the database structure for a polymorphic relation:
staff
id - integer
name - string
orders
id - integer
price - integer
photos
id - integer
path - string
imageable_id - integer
imageable_type - string
The key fields to notice here are the imageable_id and imageable_type on the photos table. The ID will
contain the ID value of, in this example, the owning staff or order, while the type will contain the class name of the
owning model. This is what allows the ORM to determine which type of owning model to return when accessing the
imageable relation.
4.6.6 Many To Many polymorphic relations

New in version 0.3.
Polymorphic Many To Many Relation Table Structure
In addition to traditional polymorphic relations, you can also specify many-to-many polymorphic relations. For example, a blog Post and Video model could share a polymorphic relation to a Tag model. First, lets examine the table
structure:
posts
id - integer
name - string
videos
id - integer
name - string
tags
id - integer
name - string
26
Chapter 4. The ORM
taggables
tag_id - integer
taggable_id - integer
taggable_type - string
The Post and Video model will both have a morph_to_many relationship via a tags method:
class Post(Model):
@property
def tags(self):
return self.morph_to_many(Tag, 'taggable')
The Tag model can define a method for each of its relationships:
class Tag(Model):
@property
def posts(self):
return self.morphed_by_many(Post, 'taggable')
@property
def videos(self):
return self.morphed_by_many(Video, 'taggable')
4.7 Querying relations

4.7.1 Querying relations when selection
When accessing the records for a model, you may wish to limit the results based on the exeistence of a relationship.
For example, you may wish to retrieve all blog posts that have at least one comment. To actually do so, you can use
the has method:
posts = Post.has('comments').get()
This would execute the following SQL query:

SELECT * FROM posts
WHERE (
SELECT COUNT(*) FROM comments
WHERE comments.post_id = posts.id
) >= 1
You can also specify an operator and a count:

posts = Post.has('comments', '>', 3).get()
This would execute:

SELECT * FROM posts
WHERE (
) > 3
4.7. Querying relations
27
Nested has statements can also be constructed using dot notation:

posts = Post.has('comments.votes').get()
And the corresponding SQL query:

SELECT * FROM posts
WHERE (
AND (
SELECT COUNT(*) FROM votes
WHERE votes.comment_id = comments.id
) >= 1
) >= 1
If you need even more power, you can use the where_has and or_where_has methods to put where conditions
on your has queries:
posts = Post.where_has(
'comments',
lambda q: q.where('content', 'like', 'foo%')
).get()
4.7.2 Dynamic properties

The Eloquent ORM allows you to access your relations via dynamic properties. It will automatically load the relationship for you. It will then be accessible via a dynamic property by the same name as the relation. For example, with
the following model Post:
class Phone(Model):
@property
def user(self):
return self.belongs_to(User)
phone = Phone.find(1)
You can then print the users email like this:

print(phone.user.email)
Now, for one-to-many relationships:

class Post(Model):
@property
def comments(self):
return self.has_many(Comment)
post = Post.find(1)
You can then access the posts comments like this:

comments = post.comments
If you need to add further constraints to which comments are retrieved, you may call the comments method and
continue chaining conditions:
28
Chapter 4. The ORM
comments = post.comments().where('title', 'foo').first()
Note: Relationships that return many results will return an instance of the Collection class.
4.8 Eager loading

Eager loading exists to alleviate the N + 1 query problem. For example, consider a Book that is related to an Author:
class Book(Model):
@property
def author(self):
return self.belongs_to(Author)
Now, consider the following code:

for book in Book.all():
print(book.author.name)
This loop will execute 1 query to retrieve all the books on the table, then another query for each book to retrieve the
author. So, if we have 25 books, this loop will run 26 queries.
To drastically reduce the number of queries you can use eager loading. The relationships that should be eager loaded
can be specified via the with_ method.
for book in Book.with_('author').get():
print(book.author.name)
In this loop, only two queries will be executed:

SELECT * FROM books
SELECT * FROM authors WHERE id IN (1, 2, 3, 4, 5, ...)
You can eager load multiple relationships at one time:

books = Book.with_('author', 'publisher').get()
You can even eager load nested relationships:

books = Book.with_('author.contacts').get()
In this example, the author relationship will be eager loaded as well as the authors contacts relation.
4.8.1 Eager load constraints

Sometimes you may wish to eager load a relationship but also specify a condition for the eager load. Heres an
example:
users = User.with_({
'posts': Post.query().where('title', 'like', '%first%')
}).get()
4.8. Eager loading
29
In this example, were eager loading the users posts only if the posts title contains the word first.
When passing a query as a constraint, only the where clause is supported, if you want to be more specific you can use
a callback:
users = User.with_({
'posts': lambda q: q.where('title', 'like', '%first%').order_by('created_at', 'desc')
})
4.8.2 Lazy eager loading

It is also possible to eagerly load related models directly from an already existing model collection. This may be useful
when dynamically deciding whether to load related models or not, or in combination with caching.
books = Book.all()
books.load('author', 'publisher')
You can also pass conditions:

books.load({
'author': Author.query().where('name', 'like', '%foo%')
})
4.9 Inserting related models

You will often need to insert new related models, like inserting a new comment for a post. Instead of manually setting
the post_id foreign key, you can insert the new comment from its parent Post model directly:
comment = Comment(message='A new comment')
post = Post.find(1)
comment = post.comments().save(comment)
If you need to save multiple comments:

comments = [
Comment(message='Comment 1'),
Comment(message='Comment 2'),
Comment(message='Comment 3')
]
post = Post.find(1)
post.comments().save_many(comments)
4.9.1 Associating models (Belongs To)

When updatings a belongs_to relationship, you can use the associate method:
account = Account.find(1)
user.account().associate(account)
30
Chapter 4. The ORM
user.save()
4.9.2 Inserting related models (Many to Many)

You can also insert related models when working with many-to-many relationship. For example, with User and
Roles models:
Attaching many to many models
user = User.find(1)
role = Roles.find(3)
user.roles().attach(role)
# or
user.roles().attach(3)
You can also pass a dictionary of attributes that should be stored on the pivot table for the relation:
user.roles().attach(3, {'expires': expires})
The opposite of attach is detach:

user.roles().detach(3)
Both attach and detach also take list of IDs as input:

user = User.find(1)
user.roles().detach([1, 2, 3])
user.roles().attach([{1: {'attribute1': 'value1'}}, 2, 3])
Using sync to attach many to many models

You can also use the sync method to attach related models. The sync method accepts a list of IDs to place on the
pivot table. After this operation, only the IDs in the list will be on the pivot table:
user.roles().sync([1, 2, 3])
Adding pivot data when syncing

You can also associate other pivot table values with the given IDs:
user.roles().sync([{1: {'expires': True}}])
Sometimes you might want to create a new related model and attach it in a single command. For that, you can use the
save method:
role = Role(name='Editor')
User.find(1).roles().save(role)
4.9. Inserting related models
31
You can also pass attributes to place on the pivot table:

User.find(1).roles().save(role, {'expires': True})
4.10 Touching parent timestamps

When a model belongs_to another model, like a Comment belonging to a Post, it is often helpful to update the
parents timestamp when the chil model is updated. For instance, when a Comment model is updated, you may want
to automatically touch the updated_at timestamp of the owning Post. For this to actually happen, you just have
to add a __touches__ property containing the names of the relationships:
class Comment(Model):
__touches__ = ['posts']
@property
def post(self):
return self.belongs_to(Post)
Now, when you update a Comment, the owning Post will have its updated_at column updated.
4.11 Working with pivot table

Working with many-to-many reationships requires the presence of an intermediate table. Eloquent makes it easy to
interact with this table. Lets take the User and Roles models and see how you can access the pivot table:
user = User.find(1)
for role in user.roles:
print(role.pivot.created_at)
Note that each retrieved Role model is automatically assigned a pivot attribute. This attribute contains e model
instance representing the intermediate table, and can be used as any other model.
By default, only the keys will be present on the pivot object. If your pivot table contains extra attributes, you must
specify them when defining the relationship:
return self.belongs_to_many(Role).with_pivot('foo', 'bar')
Now the foo and bar attributes will be accessible on the pivot object for the Role model.
If you want your pivot table to have automatically maintained created_at and updated_at timestamps, use the
with_timestamps method on the relationship definition:
return self.belongs_to_many(Role).with_timestamps()
4.11.1 Deleting records on a pivot table

To delete all records on the pivot table for a model, you can use the detach method:
User.find(1).roles().detach()
32
Chapter 4. The ORM
4.11.2 Updating a record on the pivot table

Sometimes you may need to update your pivot table, but not detach it. If you wish to update your pivot table in place
you may use update_existing_pivot method like so:
User.find(1).roles().update_existing_pivot(role_id, attributes)
4.12 Timestamps
By default, the ORM will maintain the created_at and updated_at columns on your database table automatically. Simply add these timestamp columns to your table. If you do not wish for the ORM to maintain these
columns, just add the __timestamps__ property:
class User(Model):
__timestamps__ = False
4.12.1 Providing a custom timestamp format

If you whish to customize the format of your timestamps (the default is the ISO Format) that will be returned when
using the to_dict or the to_json methods, you can override the get_date_format method:
class User(Model):
def get_date_format(self):
return 'DD-MM-YY'
4.13 Query Scopes

4.13.1 Defining a query scope
Scopes allow you to easily re-use query logic in your models. To define a scope, simply prefix a model method with
scope:
class User(Model):
def scope_popular(self, query):
return query.where('votes', '>', 100)
def scope_women(self, query):
return query.where_gender('W')
4.13.2 Using a query scope

users = User.popular().women().order_by('created_at').get()
4.12. Timestamps
33
4.13.3 Dynamic scopes

Sometimes you may wish to define a scope that accepts parameters. Just add your parameters to your scope function:
class User(Model):
def scope_of_type(self, query, type):
return query.where_type(type)
Then pass the parameter into the scope call:

users = User.of_type('member').get()
4.14 Global Scopes

Sometimes you may wish to define a scope that applies to all queries performed on a model. In essence, this is
how Eloquents own soft delete feature works. Global scopes are defined using a combination of mixins and an
implementation of the Scope class.
First, lets define a mixin. For this example, well use the SoftDeletes that ships with Eloquent:
from eloquent import SoftDeletingScope
class SoftDeletes(object):
@classmethod
def boot_soft_deletes(cls, model_class):
"""
Boot the soft deleting mixin for a model.
"""
model_class.add_global_scope(SoftDeletingScope())
If an Eloquent model inherits from a mixin that has a method matching the boot_name_of_trait naming convention, that mixin method will be called when the Eloquent model is booted, giving you an opportunity to register
a global scope, or do anything else you want. A scope must be an instance of the Scope class, which specifies two
methods: apply and remove.
The apply method receives an Builder query builder object and the Model its applied to, and is responsible for
adding any additional where clauses that the scope wishes to add. The remove method also receives a Builder
object and Model and is responsible for reversing the action taken by apply. In other words, remove should
remove the where clause (or any other clause) that was added. So, for our SoftDeletingScope, it would look
something like this:
from eloquent import Scope
class SoftDeletingScope(Scope):
def apply(self, builder, model):
"""
Apply the scope to a given query builder.
:param builder: The query builder
:type builder: eloquent.orm.builder.Builder
34
Chapter 4. The ORM
:param model: The model

:type model: eloquent.orm.Model
"""
builder.where_null(model.get_qualified_deleted_at_column())
def remove(self, builder, model):
"""
Remove the scope from a given query builder.
:param builder: The query builder
:type builder: eloquent.orm.builder.Builder
:param model: The model
:type model: eloquent.orm.Model
"""
column = model.get_qualified_deleted_at_column()
query = builder.get_query()
wheres = []
for where in query.wheres:
# If the where clause is a soft delete date constraint,
# we will remove it from the query and reset the keys
# on the wheres. This allows the developer to include
# deleted model in a relationship result set that is lazy loaded.
if not self._is_soft_delete_constraint(where, column):
wheres.append(where)
query.wheres = wheres
4.15 Accessors & mutators

Eloquent provides a convenient way to transform your model attributes when getting or setting them.
4.15.1 Defining an accessor

Simply use the accessor decorator on your model to declare an accessor:
from eloquent.orm import Model, accessor
class User(Model):
@accessor
def first_name(self):
first_name = self.get_raw_attribute('first_name')
return first_name[0].upper() + first_name[1:]
In the example above, the first_name column has an accessor.

Note: The name of the decorated function must match the name of the column being accessed.
4.15. Accessors & mutators
35
4.15.2 Defining a mutator

Mutators are declared in a similar fashion:
from eloquent.orm import Model, mutator
class User(Model):
@mutator
def first_name(self, value):
self.set_raw_attribute(value.lower())
Note: If the column being mutated already has an accessor, you can use it has a mutator:
from eloquent.orm import Model, accessor
class User(Model):
@accessor
def first_name(self):
@first_name.mutator
def set_first_name(self, value):
The inverse is also possible:

from eloquent.orm import Model, mutator
class User(Model):
@mutator
def first_name(self, value):
@first_name.accessor
def get_first_name(self):
4.16 Date mutators

By default, the ORM will convert the created_at and updated_at columns to instances of Arrow, which eases
date and datetime manipulation while behaving pretty much like the native Python date and datetime.
You can customize which fields are automatically mutated, by either adding them with the __dates__ property or
by completely overriding the get_dates method:
36
Chapter 4. The ORM
class User(Model):
__dates__ = ['synchronized_at']
class User(Model):
def get_dates(self):
return ['created_at']
When a column is considered a date, you can set its value to a UNIX timestamp, a date string YYYY-MM-DD, a
datetime string, a native date or datetime and of course an Arrow instance.
To completely disable date mutations, simply return an empty list from the get_dates method.
class User(Model):
def get_dates(self):
return []
4.17 Attributes casting

If you have some attributes that you want to always convert to another data-type, you may add the attribute to the
__casts__ property of your model. Otherwise, you will have to define a mutator for each of the attributes, which
can be time consuming. Here is an example of using the __casts__ property:
__casts__ = {
'is_admin': 'bool'
}
Now the is_admin attribute will always be cast to a boolean when you access it, even if the underlying value is
stored in the database as an integer. Other supported cast types are: int, float, str, bool, dict, list.
The dict cast is particularly useful for working with columns that are stored as serialized JSON. For example, if your
database has a TEXT type field that contains serialized JSON, adding the dict cast to that attribute will automatically
deserialize the attribute to a dictionary when you access it on your model:
__casts__ = {
'options': 'dict'
}
Now, when you utilize the model:

user = User.find(1)
# options is a dict
options = user.options
# options is automatically serialized back to JSON
user.options = {'foo': 'bar'}
4.17. Attributes casting
37
4.18 Converting to dictionaries / JSON

4.18.1 Converting a model to a dictionary
When building JSON APIs, you may often need to convert your models and relationships to dictionaries or JSON. So,
Eloquent includes methods for doing so. To convert a model and its loaded relationship to a dictionary, you may use
the to_dict method:
user = User.with_('roles').first()
return user.to_dict()
Note that entire collections of models can also be converted to dictionaries:

return User.all().to_dict()
4.18.2 Converting a model to JSON

To convert a model to JSON, you can use the to_json method!
return User.find(1).to_json()
4.18.3 Hiding attributes from dictionary or JSON conversion

Sometimes you may wish to limit the attributes that are included in you models dictionary or JSON form, such as
passwords. To do so, add a __hidden__ property definition to you model:
class User(model):
__hidden__ = ['password']
Alternatively, you may use the __visible__ property to define a whitelist:

__visible__ = ['first_name', 'last_name']
4.18.4 Appendable attributes

Occasionally, you may need to add dictionary attributes that do not have a corresponding column in your database. To
do so, simply define an accessor for the value:
class User(Model):
@accessor
def is_admin(self):
return self.get_raw_attribute('admin') == 'yes'
Once you have created the accessor, just add the value to the __appends__ property on the model:
class User(Model):
__append__ = ['is_admin']
@accessor
38
Chapter 4. The ORM
def is_admin(self):
return self.get_raw_attribute('admin') == 'yes'
Once the attribute has been added to the __appends__ list, it will be included in both the models dictionary and
JSON forms. Attributes in the __appends__ list respect the __visible__ and __hidden__ configuration on
the model.
4.18. Converting to dictionaries / JSON
39
40
Chapter 4. The ORM
CHAPTER 5
Schema Builder
5.1 Introduction
The Schema class provides a database agnostic way of manipulating tables.
Before getting started, be sure to have configured a DatabaseManager as seen in the Basic Usage section.
from eloquent import DatabaseManager, Schema
config = {
'mysql': {
'driver': 'mysql',
'username': 'root',
'password': '',
'prefix': ''
}
}
schema = Schema(db)
5.2 Creating and dropping tables

To create a new database table, the create method is used:
with schema.create('users') as table:
table.increments('id')
The table variable is a Blueprint instance which can be used to define the new table.
To rename an existing database table, the rename method can be used:
schema.rename('from', 'to')
To specify which connection the schema operation should take place on, use the connection method:
with schema.connection('foo').create('users') as table:
41
To drop a table, you can use the drop or drop_if_exists methods:

schema.drop('users')
schema.drop_if_exists('users')
5.3 Adding columns

To update an existing table, you can use the table method:
with schema.table('users') as table:
table.string('email')
The table builder contains a variety of column types that you may use when building your tables:
Command
table.big_increments(id)
table.big_integer(votes)
table.binary(data)
table.boolean(confirmed)
table.char(name, 4)
table.date(created_on)
table.datetime(created_at)
table.decimal(amount, 5, 2)
table.double(column, 15, 8)
table.enum(choices, [foo, bar])
table.float(amount)
table.increments(id)
table.integer(votes)
table.json(options)
table.long_text(description)
table.medium_integer(votes)
table.medium_text(description)
table.morphs(taggable)
table.nullable_timestamps()
table.small_integer(votes)
table.soft_deletes()
table.string(email)
table.string(votes, 100)
table.text(description)
table.time(sunrise)
table.timestamp(added_at)
table.timestamps()
.nullable()
.default(value)
.unsigned()
42
Description
Incrementing ID using a big integer equivalent
BIGINT equivalent to the table
BLOB equivalent to the table
BOOLEAN equivalent to the table
CHAR equivalent with a length
DATE equivalent to the table
DATETIME equivalent to the table
DECIMAL equivalent to the table with a precision and scale
DOUBLE equivalent to the table with precision, 15 digits in total and 8 afte
ENUM equivalent to the table
FLOAT equivalent to the table
Incrementing ID to the table (primary key)
INTEGER equivalent to the table
JSON equivalent to the table
LONGTEXT equivalent to the table
MEDIUMINT equivalent to the table
MEDIUMTEXT equivalent to the table
Adds INTEGER taggable_id and STRING taggable_type
Same as timestamps(), except allows NULLs
SMALLINT equivalent to the table
Adds deleted_at column for soft deletes
VARCHAR equivalent column
VARCHAR equivalent with a length
TEXT equivalent to the table
TIME equivalent to the table
TIMESTAMP equivalent to the table
Adds created_at and updated_at columns
Designate that the column allows NULL values
Declare a default value for a column
Set INTEGER to UNSIGNED
Chapter 5. Schema Builder
5.4 Changing columns

Sometimes you may need to modify an existing column. For example, you may wish to increase the size of a string
column. To do so, you can use the change method. For example, lets increase the size of the name column from 25
to 50:
table.string('name', 50).change()
You could also modify the column to be nullable:

with schema.table('user') as table:
table.string('name', 50).nullable().change()
Warning: The column change feature, while tested, is still considered in beta stage. Please report any encountered
issue or bug on the Github project
5.5 Renaming columns

To rename a column, you can use use the rename_column method on the Schema builder:
table.rename('from', 'to')
Warning: Prior to MySQL 5.6.6, foreign keys are NOT automatically updated when renaming columns. Therefore, you will need to drop the foreign key constraint, rename the column and recreate the constraint to avoid an
error.
with schema.table('posts') as table:
table.drop_foreign('posts_user_id_foreign')
table.rename('user_id', 'author_id')
table.foreign('author_id').references('id').on('users')
In future versions, Eloquent might handle this automatically.

Warning: The rename column feature, while tested, is still considered in beta stage (especially for SQLite).
Please report any encountered issue or bug on the Github project
5.6 Dropping columns

To drop a column, you can use use the drop_column method on the Schema builder:
5.6.1 Dropping a column from a database table

table.drop_column
5.4. Changing columns
43
5.6.2 Dropping multiple columns from a database table

table.drop_column('votes', 'avatar', 'location')
5.7 Checking existence

You can easily check for the existence of a table or column using the has_table and has_column methods:
5.7.1 Checking for existence of a table

if schema.has_table('users'):
# ...
Checking for existence of a column:

if schema.has_column('users', 'email'):
# ...
5.8 Adding indexes

The schema builder supports several types of indexes. There are two ways to add them. First, you may fluently define
them on a column definition:
table.string('email').unique()
Or, you may choose to add the indexes on separate lines. Below is a list of all available index types:
Command
table.primary(id)
table.primary([first, last])
table.unique(email)
table.index(state)
Description
Adds a primary key
Adds composite keys
Adds a unique index
Adds a basic index
5.9 Dropping indexes

To drop an index you must specify the indexs name. Eloquent assigns a reasonable name to the indexes by default.
Simply concatenate the table name, the names of the column in the index, and the index type. Here are some examples:
Command
table.drop_primary(user_id_primary)
table.drop_unique(user_email_unique)
table.drop_index(geo_state_index)
Description
Drops a primary key from the users table
Drops a unique index from the users table
Drops a basic index from the geo table
5.10 Foreign keys

Eloquent also provides support for adding foreign key constraints to your tables:
44
table.integer('user_id').unsigned()
table.foreign('user_id').references('id').on('users')
In this example, we are stating that the user_id column references the id column on the users table. Make sure
to create the foreign key column first!
You may also specify options for the on delete and on update actions of the constraint:
table.foreign('user_id')\
.references('id').on('users')\
.on_delete('cascade')
To drop a foreign key, you may use the drop_foreign method. A similar naming convention is used for foreign
keys as is used for other indexes:
table.drop_foreign('posts_user_id_foreign')
Note: When creating a foreign key that references an incrementing integer, remember to always make the foreign key
column unsigned.
5.11 Dropping timestamps and soft deletes

To drop the timestamps, nullable_timestamps or soft_deletes column types, you may use the following methods:
Command
table.drop_timestamps()
table.drop_soft_deletes()
Description
Drops the created_at and deleted_at columns
Drops the deleted_at column
5.11. Dropping timestamps and soft deletes
45
46
CHAPTER 6
Migrations
Migrations are a type of version control for your database. They allow a team to modify the database schema and stay
up to date on the current schema state. Migrations are typically paired with the Schema Builder to easily manage your
databases schema.
Note: For the migrations to actually work, you need a configuration file describing your databases in a DATABASES
dict, like so:
DATABASES = {
'mysql': {
'driver': 'mysql',
'username': 'root',
'password': '',
'prefix': ''
}
}
This file needs to be precised when using migrations commands.
6.1 Creating Migrations

To create a migration, you can use the migrations:make command on the Eloquent CLI:
eloquent migrations:make create_users_table -c databases.py
This will create a migration file that looks like this:

from eloquent.migrations import Migration
class CreateTableUsers(Migration):
def up(self):
"""
Run the migrations.
"""
pass
def down(self):
47
"""
Revert the migrations.
"""
pass
By default, the migration will be placed in a migrations folder relative to where the command has been executed,
and will contain a timestamp which allows the framework to determine the order of the migrations.
If you want the migrations to be stored in another folder, use the --path/-p option:
eloquent migrations:make create_users_table -c databases.py -p my/path/to/migrations
The --table and --create options can also be used to indicate the name of the table, and whether the migration
will be creating a new table:
eloquent migrations:make add_votes_to_users_table -c databases.py --table=users
eloquent migrations:make create_users_table -c databases.py --table=users --create
These commands would respectively create the following migrations:

class AddVotesToUsersTable(Migration):
def up(self):
"""
Run the migrations.
"""
with self.schema.table('users') as table:
pass
def down(self):
"""
"""
with self.schema.table('users') as table:
pass
class CreateTableUsers(Migration):
def up(self):
"""
Run the migrations.
"""
with self.schema.create('users') as table:
table.timestamps()
def down(self):
"""
"""
self.schema.drop('users')
48
Chapter 6. Migrations
6.2 Running Migrations

To run all outstanding migrations, just use the migrations:run command:
eloquent migrations:run -c databases.py
6.3 Rolling back migrations

6.3.1 Rollback the last migration operation
eloquent migrations:rollback -c databases.py
6.3.2 Rollback all migrations

eloquent migrations:reset -c databases.py
6.4 Getting migrations status

To see the status of the migrations, just use the migrations:status command:
eloquent migrations:status -c databases.py
This would output something like this:

+----------------------------------------------------+------+
| Migration
| Ran? |
+----------------------------------------------------+------+
| 2015_05_02_04371430559457_create_users_table
| Yes |
| 2015_05_04_02361430725012_add_votes_to_users_table | No
|
+----------------------------------------------------+------+
6.2. Running Migrations
49

Eloquent Documentation: Release 0.4

Uploaded by

Copyright:

Available Formats

Eloquent Documentation: Release 0.4

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Eloquent Documentation: Release 0.4

Uploaded by

Copyright:

Available Formats

Eloquent Documentation

May 24, 2015

Accessors & mutators . . . . . .

Eloquent Documentation, Release 0.4

The Eloquent ORM provides a simple yet beautiful ActiveRecord implementation.

Eloquent Documentation, Release 0.4

You can install Eloquent in 2 different ways:

Install from source using the official repository (https://github.com/sdispater/eloquent)

Eloquent Documentation, Release 0.4

2.2 Read / Write connections

Eloquent Documentation, Release 0.4

Here is an example of how read / write connections should be configured:

2.3 Running queries

2.3.1 Running a select query

The select method will always return a list of results.

2.3.2 Running an insert statement

2.3.3 Running an update statement

2.3.4 Running a delete statement

Chapter 2. Basic Usage

Eloquent Documentation, Release 0.4

2.3.5 Running a general statement

2.4 Database transactions

You can rollback a transaction with the rollback method:

You can also commit a transaction via the commit method:

2.5 Accessing connections

Sometimes, you may need to reconnect to a given database:

2.4. Database transactions

Eloquent Documentation, Release 0.4

2.6 Query logging

or activate it later on:

Now, the logger eloquent.connection.queries will be logging queries at debug level:

2.6.1 Customizing log messages

Chapter 2. Basic Usage

3.2.2 Chunking results from a table

3.2.3 Retrieving a single row from a table

Eloquent Documentation, Release 0.4

3.2.4 Retrieving a single column from a row

3.2.5 Retrieving a list of column values

3.2.6 Specifying a select clause

3.2.7 Adding a select clause to an existing query

3.2.8 Using where operators

3.2.10 Using Where Between

3.2.11 Using Where Not Between

Chapter 3. Query Builder

Eloquent Documentation, Release 0.4

3.2.12 Using Where In

3.2.13 Using Where Null to find records with null values

3.2.14 Order by, group by and having

3.2.15 Offset and limit

3.3.1 Basic join statement

3.3.2 Left join statement

You can also specify more advance join clauses:

Eloquent Documentation, Release 0.4

clause = JoinClause('contacts').on('users.id', '=', 'contacts.user_id').where('contacts.user_id', '>'

3.4 Advanced where

3.4.1 Parameter grouping

The query above will produce the following SQL:

3.4.2 Exists statement