Intro - Database Support
This section of the documentation describes what databases pydapper supports and how pydapper manages (or allows you to manage) connections.
There are four core concepts to understand about each dbapi pydapper supports:
- The dbapi package name
- The name of the dbapi package that pydapper supports.
- Default
/
- Is the dbapi the default for the dbms? the dbapi indicated as the default can be declared in the DSN as
either
dbms+dbapi
or simplydbms
. - For example, a DSN for psycopg2 (the PostsgreSQL default) can be declared as
postgresql://user:pw@server:port/dbname
ORpostgresql+psycopg2://user:pw@server:port/dbname
- Driver name
- The name of the driver that should be included in the dsn passed to the
connect
method (see examples). - Base connection class
- The class path of the connection class that must be passed or inherited from when passed into the
using
method (see examples).
Connection Management🔗
pydapper supports BYOC (bring your own connection) via the using
entry point or will manage the connection
lifecyle for you using connect
.
connect
🔗
connect will manage the connection for you. When instantiating connect using a context manager, connect will use the context manager that is implemented on the dbapi you are using.
You can optionally not pass the dsn into connect and set the PYDAPPER_DSN
environment variable instead.
Below is a generic example of using pydapper to connect to sqlite
.
import pydapper
with pydapper.connect() as commands:
# do stuff
connect_async
🔗
connect_async will manage an asynchronous connection for you when using a dsn of a supported async dbapi. The api is almost identical to that of the sync api.
import pydapper
import asyncio
async def main():
async with pydapper.connect_async() as commands:
# do stuff
asyncio.run(main())
using
🔗
You should use the using
method when you want to use your own connection. A use case
for this could be if you have a custom connection pool in your application and you don't want a framework
to get in the way of using it. Another example is reuse of connection objects from a framework like Django ORM
or SQLAlchemy.
In order to use this entry point, the connection object you are passing in must be an instance of or inherit from one of the dbapi connection objects that pydapper supports.
Below is a generic example using pydapper with a connection managed by django
.
from django.db import connection
import pydapper
dbapi_connection_object = connection.connection
commands = pydapper.using(dbapi_connection_object)
What's going on here?
- importing the connection object proxy from
django.db
- grab the actual dbapi connection object, which is stored in the
connection
property of the Django connection proxy - pass the dbapi connection object into
pydapper.using
and get a pydapperCommands
instance back
using_async
🔗
You should use the using_async
method when you want to use your own connection. The api is almost identical to that
of the sync api.
import pydapper
some_pool = ConnectionPool()
conn = await some_pool.acquire()
commands = pydapper.using_async(conn)