nextcord-ormar 0.3.3

Database integration for Nextcord with Ormar

Nextcord-Ormar

Formerly Nextcord-Tortoise

Nextcord-Ormar is a library to help integrate the async Django-inspired ORM Ormar with a Nextcord bot. It's designed to compliment the modular cog system of Nextcord. It also comes with NXAlembic, a preconfigured version of Alembic to help with creating and applying database migrations.

Nextcord-Ormar is still in active development, there may be breaking changes as the library is polished up. If you have any feedback, feel free to open an issue!

Quickstart

Install Nextcord-Ormar and Ormar with the correct database backend.

pip install nextcord-ormar ormar[sqlite]

Import Nextcord-Ormar's bot class and pass it your database URL.

from nextcord_ormar import Bot

bot = Bot(command_prefix="$", database_url="sqlite:///db.sqlite")

In your cog file, import OrmarApp to create an app, then use AppModel to create a database model. Define your model like a normal Ormar model.

If you prefer, you can also define your models elsewhere and import them into your cog.

import ormar
from nextcord_ormar import OrmarApp, AppModel

ModelMeta = OrmarApp.create_app("example")

class ExampleTable(AppModel):
    class Meta(ModelMeta):
        pass
    
    id = ormar.Integer(primary_key=True)
    discord_id = ormar.BigInteger()
    message = ormar.Text()

You can then use this model in your cog.

from nextcord.ext import commands

class Example(commands.Cog):
    def __init__(self, nextcord):
        self.nextcord = nextcord

    @commands.command("example")
    async def example(self, ctx: commands.Context, *args):
        new_example = await ExampleTable.objects.create(discord_id=ctx.author.id, message=args[0])
        await ctx.send("Hello!")

Before you can start the bot though, you'll need to set up migrations and the database. Create a file called nxalembic.ini in your project root folder and tell it how to import your bot.

[nxalembic]
module = example.demo
bot = bot

You can think of this as from module import bot, or in this instance, from example.demo import bot. NXAlembic will use it to import your bot along with your definitions for each model.

In the same folder, you can now use the nxalembic tool. Create migrations with

nxalembic migrate

Upgrade the database

nxalembic update

Your bot is now ready to start!

Roadmap

Other than bug fixes as they arise, the current plan is to just add the rest of the Alembic commands to NXAlembic. If there is a specific feature you want that is missing from either the bot integration or NXAlembic, feel free to open an issue.

Thanks to

Miguel Grinberg for Flask-Migrations which was a useful example.

Mike Bayer for SQLAlchemy and Alembic