Prisma Client Python

Prisma Client Python is Caspian's type-safe, auto-generated async database client for Python applications. It turns your Prisma schema into a Python API that fits Caspian's FastAPI-based runtime, so you can query your database with await, relations, typed filters, transactions, and raw SQL fallbacks without hand-writing an ORM layer.

This package powers the database workflow described in the Caspian docs: define your schema once, generate the client with ppy, then use the preconfigured global prisma instance inside your app.

Why This Package Exists

Caspian is built around native async Python, reactive UI, and direct server-side workflows. Prisma Client Python covers the database side of that stack by providing:

• Type-safe client generation from prisma/schema.prisma
• Async query execution for Caspian and FastAPI applications
• Familiar Prisma-style CRUD, filtering, relations, and ordering
• Transaction support for multi-step writes
• Raw SQL escape hatches when the ORM API is not enough

Installation

New Caspian Project

Create a new app with Caspian, then generate the client after defining your schema:

npx create-caspian-app@latest
npx ppy generate

Existing Project

Add the package to an existing project, then run the initializer:

npm install --save-dev prisma-client-python
npx ppy init

ppy init bootstraps the Prisma dependencies and starter files needed for Caspian's database workflow. After that, use npx ppy generate whenever your Prisma schema changes.

Database Workflow

The recommended flow matches the Caspian database guide.

1. Configure DATABASE_URL

Set the connection string in .env.

# SQLite is convenient for local development
DATABASE_URL="file:./prisma/dev.db"

# PostgreSQL / MySQL are recommended for async production workloads
# DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

2. Configure Prisma

Use prisma.config.ts for seeding and client-level options.

export default {
  seed: {
   import: "./prisma/seed.ts",
   autoRun: true,
  },
  client: {
   logLevel: "info",
  },
}

3. Define Your Schema

Model your database in prisma/schema.prisma.

datasource db {
  provider = "sqlite"
}

model User {
  id    String @id @default(cuid())
  email String @unique
  name  String?
  posts Post[]
}

model Post {
  id        String  @id @default(cuid())
  title     String
  published Boolean @default(false)
  authorId  String
  author    User    @relation(fields: [authorId], references: [id])
}

4. Generate The Client

npx ppy generate

This compiles the Prisma schema into Caspian's Python client. Run it after every schema change.

5. Apply Schema Changes

Use the Prisma CLI alongside ppy.

npx prisma migrate dev

For quick local prototyping you can also use:

npx prisma db push

Command Reference

| Command | Purpose | | --- | --- | | npx ppy init | Installs required Prisma dependencies and prepares the project for Caspian's Python client workflow. | | npx ppy generate | Generates the async Python client from prisma/schema.prisma. Run this after every schema change. | | npx prisma migrate dev | Creates and applies a development migration. | | npx prisma migrate deploy | Applies pending migrations in production environments. | | npx prisma db push | Syncs the schema without creating a migration file. | | npx prisma db seed | Runs the configured seed script. | | npx prisma studio | Opens Prisma Studio to inspect and edit records visually. |

Usage

Import the global prisma instance and await operations directly.

from src.lib.prisma.db import prisma


async def create_user():
   user = await prisma.user.create(
      data={
         "email": "[email protected]",
         "name": "Alice",
      }
   )
   return user


async def list_posts():
   posts = await prisma.post.find_many(
      where={
         "published": True,
         "title": {"contains": "Caspian"},
      },
      order_by={"createdAt": "desc"},
   )
   return posts


async def update_login_count(user_id: str):
   user = await prisma.user.update(
      where={"id": user_id},
      data={
         "loginCount": {"increment": 1},
      },
   )
   return user

Relations And Selection

from src.lib.prisma.db import prisma


async def get_user_with_role(email: str):
   return await prisma.user.find_unique(
      where={"email": email},
      include={"userRole": True},
      select={"id": True, "name": True},
   )

Transactions

from src.lib.prisma.db import prisma


async def create_user_with_audit(data: dict):
   async with prisma.tx() as tx:
      user = await tx.user.create(data=data)
      await tx.log.create(
         data={
            "action": "CREATED_USER",
            "userId": user.id,
         }
      )
      return user

Raw SQL

from src.lib.prisma.db import prisma


async def gmail_users():
   return await prisma.query_raw(
      "SELECT * FROM User WHERE email LIKE ?",
      "%@gmail.com",
   )

Caspian Context

Prisma Client Python is designed for the Caspian stack. Caspian combines a FastAPI engine, file-system routing, direct async RPC, and a Python-first component model. This package is the database layer that makes those workflows feel native on the server side.

If you are already using Caspian, the intended setup is:

1. Define models in prisma/schema.prisma.
2. Run npx ppy generate.
3. Import prisma from src.lib.prisma.db.
4. Use async queries directly in routes, actions, and RPC handlers.

Contributing

Issues and pull requests are welcome.

License

MIT. See LICENSE.txt for details.

Author

Maintained by The Steel Ninja Code.

Contact

For support or collaboration, contact [email protected].