Prisma Error Management
Last edited: 1/17/2025
This guide has been deprecated. Please use the troubleshooting guide in the Supabase docs.
Addressing specific errors:
Prisma, unlike other libraries, uses query parameters for configurations.
Some can be used to address specific errors and can be appended to end of your connection string like so:
_10.../postgres?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE
Can't reach database server at:
Increase connect_timeout to 30s and check to make sure you are using a valid connection string.
_10.../postgres?connect_timeout=30
Timed out fetching a new connection from the connection pool:
Increase pool_timeout to 30s .
_10.../postgres?pool_timeout=30
... prepared statement "" already exists
Add pgbouncer=true to the connection string.
_10.../postgres?pgbouncer=true
Max client connections reached
Checkout this guide for managing this error
Server has closed the connection
According to this GitHub Issue for Prisma, it may be related to large return values for queries. Try to limit the total amount of rows returned for particularly large requests.
Drift detected: Your database schema is not in sync with your migration history
Prisma will try to act as the source of truth for your database structures. If you CREATE, DROP, or ALTER database objects outside of a Prisma Migration, it is likely to detect drift and may offer to correct the situation by purging your schemas. To circumvent this issue, try baselining your migrations.
Some users have discussed how they managed this problem in a GitHub Discussion.
Management suggestions
Make a custom role for Prisma to increase observability
Imagine your database as a house, and users as the people with keys.
- By default, most developers use the "master key" (the
postgresrole) to access everything. But it's safer to give Prisma its own key! This way, it can only access the rooms (tables) it needs. - it's usually safer to give Prisma its own key! This way, it can only access the rooms (tables) it needs.
- Plus, with separate keys, it's easier to see what Prisma is doing in your house with monitoring tools, such as PGAudit and pg_stat_activity.
Creating the Prisma user:
_10create user "prisma" with password 'secret_password' bypassrls createdb;
Prisma requires the createdb modifier to create shadow databases. It uses them to help manage migrations.
Give Postgres ownership of the new user:
This allows you to view Prisma migration changes in the Dashboard
_10grant "prisma" to "postgres";
Keep it safe!
Use a strong password for Prisma. Bitwarden provides a free and simple password generator that can make one for you.
If you need to change it later, you can use the below SQL:
_10alter user "prisma" with password 'new_password';
Grant Prisma access
The below example gives Prisma full authority over all database objects in the public schema:
_10 -- Grant it necessary permissions over the relevant schemas (public)_10 grant usage on schema public to prisma;_10 grant create on schema public to prisma;_10 grant all on all tables in schema public to prisma;_10 grant all on all routines in schema public to prisma;_10 grant all on all sequences in schema public to prisma;_10 alter default privileges for role postgres in schema public grant all on tables to prisma;_10 alter default privileges for role postgres in schema public grant all on routines to prisma;_10 alter default privileges for role postgres in schema public grant all on sequences to prisma;
For more guidance on specifying access, check out this article on privileges
Optimize Prisma queries:
In the Query Performance Advisor, you can view long-running or frequently accessed queries by role:
Selecting a query can reveal suggestions to improve its performance
Configuring connections
Useful Links:
Supabase provides 3 connection strings in the Database Settings. You can use all three or just the ones most relevant to your project.
Direct connection:
Best used with stationary servers, such as VMs and long-standing containers, but it only works in IPv6 environments unless the IPv4 Add-On is enabled. If you are unsure if your network is IPv6 compatible, check here.
_10# Example Connection_10_10postgresql://postgres:[PASSWORD]@db.[PROJECT REF].supabase.co:5432/postgres
Supavisor in session mode (port 5432):
_10# Example Connection_10_10postgres://[DB-USER].[PROJECT REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
An alternative to direct connections when working in IPv4-only environments.
Session mode is a good option for migrations
Supavisor in transaction mode (port 6543):
_10# Example Connection_10_10postgres://[DB-USER].[PROJECT REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres
Should be used when deploying to:
- Horizontally auto-scaling servers
- Edge/Serverless deployments
When working in serverless/edge environments, it is recommended to set the connection_limit=1 and then gradually increase it if necessary.