Add how-to guide on integrating with Tortoise ORM

[florimondmanca]

Complementary to #4 , we should write how-to guides explaining how to configure and use an async database client in order to perform database queries asynchronously in a Bocadillo app.

Note: this is a temporary but reasonable solution waiting for a sane async ORM to come around, like Tortoise.

Available async clients for popular databases are:

• asyncpg: async PostgreSQL client
• aiomysql: async version of PyMySQL
• aiosqlite: async version of sqlite3

If possible and relevant, we should also provide snippets that abstract away common logic such as connecting to the database or handling cursors, so that app-side code looks something like:

from asyncdb import query  # <- snippet

async def get_products(req, res):
    results = await query('SELECT id, name, price FROM products;')
    # do something with `results`

Guidelines on contributing documentation have been added to CONTRIBUTING.md. Feel free to reach out to discuss any ideas!

Edit (Dec 19th): it actually seems like a good idea to make databases more approachable and suggest an integration with Tortoise ORM in the how-to guide.

[florimondmanca]

@alin23 If you're interested in giving the asyncpg guide a go, I'd be more than happy to see what you come up with based on your past experience! 👍

[alin23]

@florimondmanca I'd be glad to help! Probably this weekend as my daily job is quite demanding nowadays. In the meantime, can you take a look here: #3 (comment)
I'd really like to see that PR merged ^_^

[florimondmanca]

Thanks @alin23.

I'd really like to see that PR merged ^_^

Just a note: keep in mind that Bocadillo is still in alpha, so I wouldn't advise using it in production (if that's what you're planning to do). Beyond possible API changes, there are still some important aspects that haven't been dealt with yet, such as security. 😉

[florimondmanca]

Hi @alin23, have you got any chance to look at the asyncpg guide yet? 😊

[alin23]

Nope, not yet. The company I'm working with is on a last-mile talk with investors and I have to make sure everything's on track here. So I won't have much time for open source work these weeks.

Sorry for overpromising, I'd really like to contribute to this but I don't have the time yet

[florimondmanca]

I've just read more thoroughly through the Tortoise ORM docs and I thought — Tortoise may actually be sufficient for this how-to guide. At least, it's a more user-friendly advice than resorting to a raw client, and it will be very familiar to those who have used Django in the past.

I'm leaving a link to their Get started guide here for reference. Might be worth adapting it to show how to setup the DB, create a model and use it in some views.

[alin23]

It definitely looks much better than raw sql ^_^
I think we need a startup event that runs after the loop is initialized but before the server is started to allow initialization for this. Do we have anything like this?

[florimondmanca]

We don't yet, but that's definitely doable (at worst wrapping around Starlette's event handling). Plus I've been thinking we'd need this at some point.

It looks like opening connections needs the startup event and cleaning up needs shutdown.

If you're feeling like it you can open a feature request for that? :)

[alin23]

Sure!

[florimondmanca]

Hi @alin23, #62 (startup and shutdown events) has just been merged. 👍

[alin23]

Awesome work! On 19th I'm getting back from a trip and I can hop on this db stuff.

[florimondmanca]

Just for my information, have you been working on this @alin23? I just found myself in a mood to tackle this today, with the second goal of showing an example "blog" app as described in #25.

[alin23]

Go for it! I'm buried in work and side-projects, I won't be able to get to it soon enough. 😞

[florimondmanca]

No worries, understood!