Next-generation ORM for Dart Navtive & Flutter | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB

What is it?

Prisma is a next-generation ORM that consists of these tools:

  • Prisma Dart CLI - A command line tool that allows you to create and manage your Prisma projects.
  • Prisma Dart Runtime - A Dart package, that allows you to use the ORM in your Dart code.

TODO:

  • x format command.
  • generate command.
  • x init command.
  • x db push command.
  • db pull command.

Getting started

Prerequisites: Dart SDK >=2.17.6 <3.0.0

1. Create Dart project and setup Prisma

As a first step, create a simple dart console project

dart create hello
cd hello

Next, add orm package to your project.

dart pub add orm -d

Then, initialize ORM.

dart run rom init

2. Model your data in the Prisma schema

The Prisma schema provides an intuitive way to model data. Add the following models to your schema.prisma file:

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

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

Models in the Prisma schema have two main purposes:

  • Represent the tables in the underlying database
  • Serve as foundation for the generated Prisma Client API

3. Generate the Prisma Client API

dart run rom generate

The Prisma schema

Every project that uses a tool from the Prisma toolkit starts with a Prisma schema file. The Prisma schema allows developers to define their application models in an intuitive data modeling language. It also contains the connection to a database and defines a generator:

// Data source
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// Generator
generator client {
  provider = "dart run orm generate"
}

// Data model
model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields:  [authorId], references: [id])
  authorId  Int?
}

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

In this schema, you configure three things:

  • Data source - Specifies your database connection (via an environment variable)
  • Generator - Indicates that you want to generate Prisma Client
  • Data model - Defines your application models

Accessing your database with Prisma Client

Generating Prisma Client

The first step when using Prisma Client is installing its orm_runtime:

dart pub add orm_runtime

After you change your data model, you'll need to manually re-generate Prisma Client to ensure the code inside lib/src/generated_prisma_client get updated:

dart run orm generate

Using Prisma Client to send queries to your database

Once the Prisma Client is generated, you can import it in your code and send queries to your database. This is what the setup code looks like.

Import and instantiate Prisma Client

import 'lib/src/generated_prisma_client/prisma_client.dart';

final PrismaClient prisma = PrismaClient();

Now you can start sending queries via the generated Prisma Client API, here are few sample queries. Note that all Prisma Client queries return plain old Map<String, dynamic>.

Retrieve all User records from the database

// Run inside `async` function
final allUsers = await prisma.user.findMany();

Include the posts relation on each returned User object

// Run inside `async` function
final allUsers = await prisma.user.findMany(
  include: UserInclude(
    posts: true,
  ),
);

Filter all Post records that contain "odore"

final filteredPosts = await prisma.post.findMany(
  where: PostFindManyWhereInput.or([
    PostFindManyWhereInput(
      title: StringContains("odore"),
    ),
    PostFindManyWhereInput(
      content: StringContains("odore"),
    ),
  ]),
);

Create a new User and a new Post record in the same query

final user = await prisma.user.create({
  data: UserCreateInput(
    name: 'Odore',
    email: 'hello@odore.com',
    posts: UserCreateWithPostInput(
      create: PostCreateInput(
        title: 'My first post',
        content: 'This is my first post',
      ),
    ),
  ),
});

Libraries

orm
version