connection.md

Connection

Using edgy is extremely simple and easy to do but there are some steps you might want to take into consideration like connections and what it can happen if this is not done properly.

Edgy is on SQLAlechemy core but is an async version of it and therefore what happens if you want to use it within your favourite frameworks like Esmerald, Starlette or even FastAPI?

Well, Edgy is framework agnostic so it will fit in any framework you want, even in those that are not listed above that support lifecycle events.

Lifecycle events

These are very common amongst those frameworks that are based on Starlette, like Esmerald or FastAPI but other might have a similar approach but using different approaches.

The common lifecycle events are the following:

• on_startup
• on_shutdown
• lifespan

This document will focus on the one more commonly used, lifespan.

Hooking your database connection into your application

Hooking a connection is as easy as putting them inside those events in your framework.

For this example, since the author is the same as the one of Esmerald, we will be using it for explanatory purposes, feel free to apply the same principle in your favourite framework.

with the ASGI integration:

{!> ../docs_src/connections/asgi.py !}

Or doing it manually (that applies to every framework):

{!> ../docs_src/connections/simple.py !}

And that is pretty much this. Once the connection is hooked into your application lifecycle. Otherwise you will get warnings about decreased performance because the databasez backend is not connected and will be reininitialized for each operation.

You are now free to use the ORM anywhere in your application. As well as extra defined database connections in registry.

Django integration

Django currently doesn't support the lifespan protocol. So we have a keyword parameter to handle it ourselves.

{!> ../docs_src/connections/django.py !}

Manual integration

The __aenter__ and __aexit__ methods support also being called like connect and disconnect. It is however not recommended as contextmanagers have advantages in simpler error handling.

{!> ../docs_src/connections/manual.py !}

You can use this however for an integration via on_startup & on_shutdown.

{!> ../docs_src/connections/manual_esmerald.py !}

DatabaseNotConnectedWarning warning

This warning appears, when an unconnected Database object is used for an operation.

Despite bailing out the warning DatabaseNotConnectedWarning is raised. You should connect correctly like shown above.

!!! Note When passing Database objects via using, make sure they are connected. They are not necessarily connected when not in extra.

Querying other schemas

Edgy supports that as well. Have a look at the tenancy section for more details.

Having multiple connections

Edgy Registry has an extra parameter where named additional Database objects or strings can be defined. Having them there is useful because they will be connected/disconnected too.

You can switch to them on the fly via using.

Migrate from flask-migrate

See Migrations for more informations.

Note

Check the tips and tricks and learn how to make your connections even cleaner.