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 simply dbms.

For example, a DSN for psycopg2 (the PostsgreSQL default) can be declared as postgresql://user:pw@server:port/dbname OR postgresql+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 used by the built-in automatic-selection predicate. Ordinary subclasses are recognized through their class MRO; wrappers and proxies should use explicit adapter= selection (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.

Without an explicit adapter name, using runs the registered sync adapter predicates and requires exactly one match. Native DB-API connection objects and ordinary subclasses of the supported connection classes are recognized. Pass a registered adapter name with adapter= to override automatic selection when needed.

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 pydapper Commands instance back

To override automatic selection, select the adapter directly. Explicit selection bypasses all predicates:

commands = pydapper.using(dbapi_connection_object, adapter="psycopg2")

using_async

You should use the using_async method when you want to use your own asynchronous connection. The API is almost identical to the sync API: it automatically selects exactly one registered async adapter, or accepts adapter= to override automatic selection.

import pydapper

some_pool = ConnectionPool()
conn = await some_pool.acquire()
commands = pydapper.using_async(conn)

# Explicit adapter selection also works for async connections.
commands = pydapper.using_async(conn, adapter="psycopg")