-
Notifications
You must be signed in to change notification settings - Fork 250
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore(docs): Add "how to" README sections to public-facing Driver Adapters #4377
Changes from 4 commits
14112b0
d43cdf3
bc37c24
3389c21
85dfe0d
946b5d0
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,3 +3,93 @@ | |
Prisma driver adapter for Turso and libSQL. | ||
|
||
See https://prisma.io/turso for details. | ||
|
||
The following usage tutorial is valid for Prisma 5.4.2 and later versions. | ||
|
||
## How to install | ||
|
||
After [getting started with Turso](https://www.prisma.io/blog/prisma-turso-ea-support-rXGd_Tmy3UXX#create-a-database-on-turso), you can use the Turso serverless driver to connect to your database. You will need to install the `@prisma/adapter-libsql` driver adapter and the `@libsql/client` serverless driver. | ||
|
||
```sh | ||
npm install @prisma/adapter-libsql | ||
npm install @libsql/client | ||
``` | ||
|
||
Make sure your Turso database connection string and authentication token is copied over to your `.env` file. The connection string will start with `libsql://`. | ||
|
||
```env | ||
# .env | ||
TURSO_AUTH_TOKEN="eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..." | ||
TURSO_DATABASE_URL="libsql://turso-prisma-random-user.turso.io" | ||
``` | ||
|
||
You can now reference this environment variable in your `schema.prisma` datasource. Make sure you also include the `driverAdapters` Preview feature. | ||
|
||
```prisma | ||
// schema.prisma | ||
generator client { | ||
provider = "prisma-client-js" | ||
previewFeatures = ["driverAdapters"] | ||
} | ||
datasource db { | ||
provider = "sqlite" | ||
url = "file:./dev.db" | ||
} | ||
``` | ||
|
||
Now run `npx prisma generate` to re-generate Prisma Client. | ||
|
||
## How to setup migrations | ||
|
||
As Turso needs to sync between a local sqlite database and another one hosted on Turso Cloud, an additional migration setup is needed. In particular, anytime you modify models and relations in your `schema.prisma` file, you should: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The first sentence here is just wrong. There is no local SQLite database involved when using Prisma. There might be weird things needed for our migration flow as we do not support Migrations with Turso yet. |
||
|
||
1. Create a baseline migration | ||
|
||
```sh | ||
npx prisma migrate diff --from-empty \ | ||
--to-schema-datamodel prisma/schema.prisma \ | ||
--script > baseline.sql | ||
``` | ||
|
||
2. Apply the migration to your Turso database | ||
|
||
```sh | ||
turso db shell turso-prisma < baseline.sql | ||
``` | ||
|
||
## How to use | ||
|
||
In TypeScript, you will need to: | ||
|
||
1. Import packages | ||
2. Set up the libSQL serverless database driver | ||
3. Instantiate the Prisma libSQL adapter with the libSQL serverless database driver | ||
4. Pass the driver adapter to the Prisma Client instance | ||
|
||
```typescript | ||
// Import needed packages | ||
import { PrismaClient } from '@prisma/client'; | ||
import { PrismaLibSQL } from '@prisma/adapter-libsql'; | ||
import { createClient } from '@libsql/client'; | ||
|
||
// Setup | ||
const connectionString = `${process.env.TURSO_DATABASE_URL}`; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This might be confusing to users, in the text above where I previously commented, it was said:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I believe the clarification feedback should also be made on https://www.prisma.io/blog/prisma-turso-ea-support-rXGd_Tmy3UXX. |
||
const authToken = `${process.env.TURSO_AUTH_TOKEN}`; | ||
|
||
// Init prisma client | ||
const libsql = createClient({ | ||
url: connectionString, | ||
authToken, | ||
}); | ||
const adapter = new PrismaLibSQL(libsql); | ||
const prisma = new PrismaClient({ adapter }); | ||
|
||
// Use Prisma Client as normal | ||
``` | ||
|
||
Your Prisma Client instance now uses a **single** remote Turso database. | ||
You can take it a step further by setting up database replicas. Turso automatically picks the closest replica to your app for read queries when you create replicas. No additional logic is required to define how the routing of the read queries should be handled. Write queries will be forwarded to the primary database. | ||
We encourage you to create an issue if you find something missing or run into a bug. | ||
|
||
If you have any feedback about our libSQL Serverless Driver support, please leave a comment on our [dedicated GitHub issue](https://github.com/prisma/prisma/discussions/21345) and we'll use it as we continue development. |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,4 +2,70 @@ | |
|
||
Prisma driver adapter for [Neon Serverless Driver](https://github.com/neondatabase/serverless). | ||
|
||
See https://github.com/prisma/prisma/releases/tag/5.4.0 for details. | ||
See https://github.com/prisma/prisma/releases/tag/5.4.0 and https://www.prisma.io/blog/serverless-database-drivers-KML1ehXORxZV for details. | ||
|
||
The following usage tutorial is valid for Prisma 5.4.2 and later versions. | ||
|
||
## How to install | ||
|
||
After [creating your database on Neon](https://neon.tech/docs/get-started-with-neon/setting-up-a-project), you'll need to install the `@prisma/adapter-neon` driver adapter, Neon’s serverless database driver `@neondatabase/serverless`, and `ws` to set up a WebSocket connection for use by Neon. | ||
|
||
```sh | ||
npm install @prisma/adapter-neon | ||
npm install @neondatabase/serverless | ||
npm install ws | ||
``` | ||
|
||
Make sure your [Neon database connection string](https://neon.tech/docs/connect/connect-from-any-app) is copied over to your `.env` file. The connection string will start with `postgres://`. | ||
|
||
```env | ||
# .env | ||
DATABASE_URL="postgres://..." | ||
``` | ||
|
||
You can now reference this environment variable in your `schema.prisma` datasource. Make sure you also include the `driverAdapters` Preview feature. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I see, maybe in the case of turso, the text was wrong due to copypasta? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Exactly There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🍝
jkomyno marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```prisma | ||
// schema.prisma | ||
generator client { | ||
provider = "prisma-client-js" | ||
previewFeatures = ["driverAdapters"] | ||
} | ||
|
||
datasource db { | ||
provider = "postgresql" | ||
url = env("DATABASE_URL") | ||
} | ||
``` | ||
|
||
Now run `npx prisma generate` to re-generate Prisma Client. | ||
|
||
## How to use | ||
|
||
In TypeScript, you will need to: | ||
|
||
1. Import packages | ||
2. Set up the Neon serverless database driver | ||
3. Instantiate the Prisma Neon adapter with the Neon serverless database driver | ||
4. Pass the driver adapter to the Prisma Client instance | ||
|
||
```typescript | ||
// Import needed packages | ||
import { Pool, neonConfig } from '@neondatabase/serverless'; | ||
import { PrismaNeon } from '@prisma/adapter-neon'; | ||
import { PrismaClient } from '@prisma/client'; | ||
import ws from 'ws'; | ||
|
||
// Setup | ||
neonConfig.webSocketConstructor = ws; | ||
const connectionString = `${process.env.DATABASE_URL}`; | ||
|
||
// Init prisma client | ||
const pool = new Pool({ connectionString }); | ||
const adapter = new PrismaNeon(pool); | ||
const prisma = new PrismaClient({ adapter }); | ||
|
||
// Use Prisma Client as normal | ||
``` | ||
|
||
Now your code has built-in benefits of the Neon serverless driver, such as WebSocket connections and [message pipelining](https://neon.tech/blog/quicker-serverless-postgres), while Prisma covers connection creation and destruction, error handling, and type safety. If you have any feedback about our Neon Serverless Driver support, please leave a comment on our [dedicated GitHub issue](https://github.com/prisma/prisma/discussions/21346) and we'll use it as we continue development. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't see any env var referenced in the datasource block of the schema.prisma, but instead a local URL.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you, this is a copy-paste error of me trying to fit Turso snippets with the same structure used in PlanetScale and Neon's blog post.