Basic Usage

A Minimal Application

Note

This example application will not go into details as to how the ORM works. You can refer to the Orator documentation for more information.

Setting up Flask-Orator for a single Flask application is quite simple. Create your application, load its configuration and then create an Orator object.

The Orator object behaves like a DatabaseManager instance set up to work flawlessly with Flask.

from flask import Flask
from flask_orator import Orator

app = Flask(__name__)
app.config['ORATOR_DATABASES'] = {
    'development': {
        'driver': 'sqlite',
        'database': '/tmp/test.db'
    }
}

db = Orator(app)


class User(db.Model):

    __fillable__ = ['name', 'email']

    def __repr__(self):
        return '<User %r>' % self.name

Now, you need to create the database and the users table using the embedded CLI application. Let’s create a file named db.py which has the following content:

from your_application import db

if __name__ == '__main__':
    db.cli.run()

This file, when executed, gives you access to useful commands to manage you databases.

Note

For the exhaustive list of commands see the CLI section.

You first need to make a migration file to create the table:

python db.py make:migration create_users_table --table users --create

This will add a file in the migrations folder named create_users_table and prefixed by a timestamp:

from orator.migrations import Migration


class CreateTableUsers(Migration):

    def up(self):
        """
        Run the migrations.
        """
        with self.schema.create('users') as table:
            table.increments('id')
            table.timestamps()

    def down(self):
        """
        Revert the migrations.
        """
        self.schema.drop('users')

You need to modify this file to add the name and email columns:

with self.schema.create('users') as table:
    table.increments('id')
    table.string('name').unique()
    table.string('email').unique()
    table.timestamps()

Then, you can run the migration:

python db.py migrate

Confirm and you database and the table will be created.

Once your database set up, you can create some users:

from your_application import User

admin = User.create(name='admin', email='admin@example.com')
guest = Guest.create(name='guest', email='guest@example.com')

The create() method will create the users instantly. But you can also initiate them and save them later:

admin = User(name='admin', email='admin@example.com')
# Do something else...
admin.save()

Note

Optionally you can use a transaction.

from your_application import db, User

with db.transaction():
    admin = User.create(name='admin', email='admin@example.com')
    guest = Guest.create(name='guest', email='guest@example.com')

You can now retrieve them easily from the database:

users = User.all()

admin = User.where('name', 'admin').first()

Relationships

Setting up relationships between tables is a breeze. Let’s create a Post model with the User model as a parent:

from orator.orm import belongs_to


class Post(db.Model):

    __fillable__ = ['title', 'content']

    @belongs_to
    def user(self):
        return User

And we add the posts relationship to the User model:

from orator.orm import has_many


class User(db.Model):

    @has_many
    def posts(self):
        return Post

Before we can play with these models we need to create the posts table and set up the relationship at database level:

python db.py make:migration create_posts_table --table posts --create

And we modify the generated file to look like this:

from orator.migrations import Migration


class CreatePostsTable(Migration):

    def up(self):
        """
        Run the migrations.
        """
        with self.schema.create('posts') as table:
            table.increments('id')
            table.string('title')
            table.text('content')
            table.integer('user_id', unsigned=True)
            table.timestamps()

            table.foreign('user_id').references('id').on('users')

    def down(self):
        """
        Revert the migrations.
        """
        self.schema.drop('posts')

Finally we run it:

python db.py migrate

We can now instantiate some posts:

admin_post = Post(title='Admin Post',
                  description='This is a restricted post')

guest_post = Post(title='Guest Post',
                  description='This is a guest post')

and associate them with users:

# Associate from user.posts relation
admin.posts().save(admin_post)

# Associate from post.user relation
guest_post.user().associate(guest)

Note

You can also create the posts directly.

admin.posts().create(
    title='Admin Post',
    description='This is a restricted post'
)

Relationships properties are dynamic properties meaning that user.posts is the underlying collection of posts so we can do things like:

user.posts.first()
user.posts[2:7]
user.posts.is_empty()

But, if we need to retrieve a more fine-grained portion of posts we can actually to so:

user.posts().where('title', 'like', '%admin%').get()
user.posts().first()

What’s more?

Like said in the introduction Flask-Orator is a wrapper around Orator to integrate it more easily with Flask applications. So, basically, everything you can do with Orator is also possible with Flask-Orator.

Referer to the Orator documentation to see the features available.