Getting Started
Installation

Installation

Prisma Client Rust's installation operates in a different way to most Rust projects.

prisma-client-rust contains the query builders, traits, and type definitions. Some of these - eg. Direction - may be used in your own code.

prisma-client-rust-cli contains the Prisma generator and access to the Prisma CLI, but does not provide an executable binary - this must be created yourself.

Prisma Client Rust requires a minimum Rust version of v1.62.0.

Creating a CLI Binary

Inside Your Crate

First, the main library and CLI package must be added to your project's Cargo.toml:

[dependencies]
prisma-client-rust = { git = "https://github.com/Brendonovich/prisma-client-rust", tag = "0.6.9" }
prisma-client-rust-cli = { git = "https://github.com/Brendonovich/prisma-client-rust", tag = "0.6.9" }

The generated client will need serde, so run cargo add to install it:

cargo add serde

You'll also need to make sure you're using edition 2021 of Rust.

[package]
# ... package stuff
edition = "2021"

The easiest way to create a binary to access the CLI through is by creating a src/bin folder if you don't already have one, and inside it creating a file called something like prisma.rs (This will determine the name of your binary). Inside this file put the following:

fn main() {
    prisma_client_rust_cli::run();
}

Technically, this is all that is required! Just run the following to access the CLI:

$ cargo run --bin <prisma binary name> -- <command>

If using Apple Silicon it is recommended to ensure Rosetta is installed, even if you have installed it previously. Run softwareupdate --install-rosetta --agree-to-license to install it. Not doing so may result in nondescript errors from Prisma's query-engine binary.

This isn't a very friendly command to run, though. Luckily Cargo allows us to define project-wide aliases for running commands! Create a folder at the root of your project called .cargo and inside it create a file config.toml containing the following:

[alias]
prisma = "run --bin <prisma binary name> --"

Now you can run cargo prisma <command> anywhere in your project to access the CLI!

This approach has some problems though:

  1. prisma-client-rust-cli is included as a dependency in your crate, which is likely not desirable.
  2. If your crate has errors during compilation then you aren't able to generate the client, since the CLI will also fail to compile!

Thankfully, there's a more reliable method:

As a Workspace Crate

Move the CLI binary to a separate crate and configure your project to use Cargo workspaces (opens in a new tab). Below is a sample project structure that has one binary target in src/main.rs, and a separate crate for the CLI named prisma-cli which is included in the workspace members of Cargo.toml.

Cargo.toml
.cargo/
    config.toml
src/
    main.rs
prisma-cli/
    Cargo.toml
    src/
        main.rs

For the above example, Cargo.toml would include prisma-client-rust as a dependency as it is required by the generated file, whereas prisma-cli/Cargo.toml would include prisma-client-rust-cli as a dependency, and so the binary in src/main.rs would not be bundled with all the CLI code, only the required library code.

You will also need to update the cargo prisma alias to run the new crate:

[alias]
prisma = "run -p <prisma crate name> --"

A Note on Virtual Workspaces

If the root Cargo.toml of your workspace has no [package] section (only a [workspace] section) then you are using a virtual workspace.

For Prisma Client Rust to compile properly, you'll need to instruct Cargo to use version 2 of the feature resolver (opens in a new tab).

[workspace]
# ... workspace stuff
resolver = "2"

This is not necessary for regular workspaces & single packages since they can use edition = "2021", but virtual workspaces are special for some reason.

Specifying Your Database

As of version 0.6.3, Prisma Client Rust allows you to specify precisely which database connectors your project uses, in order to avoid compiling the other connectors that Prisma supports. This reduces compile times and binary sizes.

To start, set default-features = false for both prisma-client-rust and prisma-client-rust-cli. Then add each database you would like to support as a feature for both crates. The possible values are postgresql, mysql, sqlite, mssql and mongodb.

Why is a CLI Binary Not Provided?

In older versions of Prisma Client Rust, it was possible to cargo install prisma-client-rust-cli and have a global install of the CLI available to use at any time. This had a major problem though: Versioning. Managing multiple projects that used different versions of Prisma Client Rust got very annoying very quickly, plus it went against the recommmended installation instructions of Prisma Client JS (opens in a new tab), Go (opens in a new tab), and Python (opens in a new tab).

Unlike these three languages, Rust (or more specifically Cargo) does not provide a method for executing binaries available inside dependencies. Since installing a globally available binary was ruled out, providing the CLI as a library was seen as the only other option, plus personally I think that being able to run cargo prisma <command> is quite a nice experience and matches with clients in other languages.