FAQ
Common questions about how Prisma Postgres works, how queries are billed, and how it integrates with the Prisma ORM.
General
Can I use Prisma Postgres without Prisma ORM?
Prisma Postgres is designed to be used with Prisma ORM and the Accelerate extension for best performance and scalability.
While it is technically possible to connect via the TCP tunnel, this approach is only intended for tooling purposes, such as command line tools or query editors.
We strongly advise against using the TCP tunnel for application-level access. It is not designed for that purpose and using it that way will likely have negative performance implications for your application.
We are planning to enable application-level TCP access in the future so that you can use Prisma Postgres with other ORMs.
How do I switch from GitHub login to email and password login?
If you previously signed up using GitHub and want to switch to email and password login, follow these steps:
1. Verify Your GitHub Email Address
- Check the primary email address associated with your GitHub account (e.g., from your GitHub profile or notification settings).
2. Create a New Email/Password Account
- Go to the email/password sign-up page.
- Use the same email address linked to your GitHub account to create the new account.
- Our system will automatically connect your new email/password account to your existing data.
3. Test Your Login
- Log out and try logging in with your email and the password you just created.
If you encounter any issues, please contact our support team for help linking your accounts.
VS Code does not recognize the $extends method
If you add the Prisma Client extension for Accelerate to an existing project that is currently open in VS Code, the editor might not immediately recognize the $extends method.
This might be an issue with the TypeScript server not yet recognizing the regenerated Prisma Client. To resolve this, you need to restart TypeScript.
- In VS Code, open the Command Palette. You can do so when you press F1 or select View > Command Palette.
- Enter
typescriptand select and run the TypeScript: Restart TS server command.
VS Code should now recognize the $extends method.
Pricing
Does query execution time affect pricing in Prisma Postgres?
No, cost for Prisma Postgres is based solely on the number of operations (i.e. Prisma ORM queries), not the amount of compute required to execute them.
Whether a query takes 10ms or 10sec to execute, its pricing impact remains the same.
Do read and write queries cost the same?
Yes, read and write queries are counted equally as operations and are billed the same way.
Does a SELECT 1 query count as a billable operation?
Yes, if submitted via Prisma ORM, a query like SELECT 1 counts as an operation and will be billed accordingly (even if no actual data is accessed in the query).
Caching
Prisma Postgres includes built-in connection pooling and global caching. These features improve performance by optimizing how your queries are routed and cached.
How does Prisma Postgres's cache layer know what region to fetch the cache from?
Under the hood, Prisma Postgres's cache layer uses Cloudflare, which uses Anycast for network addressing and routing. An incoming request will be routed to the nearest data center or "node" in their network that has the capacity to process the request efficiently. To learn more about how this works, we recommend looking into Anycast.
How can I invalidate a cache for Prisma Postgres?
You can invalidate the cache on-demand via the $accelerate.invalidate API if you're on a paid plan, or you can invalidate your entire cache, on a project level, a maximum of five times a day. This limit is set based on your plan. You can manage this via the Accelerate configuration page.
What is Prisma Postgres's caching layer's consistency model?
The caching layer in Prisma Postgres does not have a consistency model. It is not a distributed system where nodes need to reach a consensus (because data is only stored in the cache node(s) closest to the user). However, the data cached in Prisma Postgres's cache nodes doesn't propagate to other nodes, so the cache layer by design doesn't need a consistency model.
Prisma Postgres implements a read-through caching strategy particularly suitable for read-heavy workloads.
The freshness of the data served by the cache depends on the cache strategy defined in your query. Refer to this section for more information on selecting the right cache strategy for your query.
How is Prisma Postgres's caching layer different from other caching tools, such as Redis?
The caching layer of Prisma Postgres:
- Is a specialized cache that allows you to optimize data access in code at the query level with a cache strategy. On the other hand, tools such as Redis and Memcached are general-purpose caches designed to be adaptable and flexible.
- Is a managed service that reduces the time, risk, and engineering effort of building and maintaining a cache service.
- Is globally distributed, by default, reducing the latency of your queries. Other cache tools would require additional configuration to make them available globally.
When should I not use Prisma Postgres's caching features?
The caching layer of Prisma Postgres is a global data cache and connection pool that allows you to optimize data access in code at the query level. While caching with Prisma Postgres can greatly boost the performance of your app, it may not always the best choice for your use case.
This global cache feature may not be a good fit for your app if:
-
Your app is exclusively used within a specific region and both your application server and database are situated in that same region on the same network. For example, database queries will likely be much faster if your application server and database are in the same region and network. However, If your application server is in different regions or networks from your database, the cache nodes will speed up your queries because the data will be cached in the closest data center to your application.
-
Your application data always needs to be up-to-date on retrieval, making it difficult to establish a reasonable cache strategy.
What is the maximum allowed value for the ttl parameter when configuring cacheStrategy?
The Time-to-live (ttl) parameter can be set for up to a year. However, it's important to note that items within the cache may be evicted if they are not frequently accessed.
Based on our experimentation, we’ve seen cache items persist for around 18 hours. While items may remain in the cache for an extended period if they are actively accessed, there is no guarantee.
:::[note]
Even frequently accessed items may occasionally be evicted from the cache. It's unlikely for an item to survive for up to or longer than a month, regardless of its activity level.
:::
Why do I sometimes see unexpected cache behavior?
Prisma Postgres's cache layer performs best when it observes a higher load from a project. Many cache operations, such as committing data to cache and refreshing stale data, happen asynchronously. When benchmarking the cache layer, we recommend doing so with loops or a load testing approach. This will mimic higher load scenarios better and reduce outliers from low frequency operations.
Prisma operations are sent to Prisma Postgres over HTTP. As a result, the first request to Prisma Postgres must establish an HTTP handshake and may have additional latency as a result. We're exploring ways to reduce this initial request latency in the future.
What regions are Prisma Postgres's cache nodes available in?
Prisma Postgres's cache layer runs on Cloudflare's network and cache hits are served from Cloudflare's 300+ locations. You can find the regions where Prisma Postgres's cache nodes are available here: https://www.cloudflare.com/network/.
How long does it take to invalidate a cache query result?
As the cache needs to be cleared globally, it is difficult to provide a specific time frame. However, the cached data is eventually consistent and typically propagates to all PoPs within a few seconds. In very rare cases, it may take longer.
Here is a demo app to test the time it takes to invalidate a cache query result.
What is the difference between Invalidate and Revalidate?
Invalidate: The cache entry is deleted, and new data will be fetched on the next request, causing a cache miss. This removes stale data but may lead to slower responses until the cache is repopulated.
Revalidate: The cache entry is updated proactively, ensuring the next request uses fresh data from the cache. This keeps the cache valid and maintains faster response times by avoiding cache misses.
What is on-demand cache invalidation?
On-demand cache invalidation lets applications instantly update specific cached data when it changes, instead of waiting for regular cache refresh cycles. This keeps information accurate and up-to-date for users.
When should I use the cache invalidate API?
The cache invalidate API is essential when data consistency cannot wait for the cache’s standard expiration or revalidation. Key use cases include:
- Content updates: When critical changes occur, such as edits to a published article, product updates, or profile modifications, that need to be visible immediately.
- Inventory management: In real-time applications, like inventory or booking systems, where stock levels, availability, or reservation statuses must reflect the latest information.
- High-priority data: For time-sensitive data, like breaking news or urgent notifications, where it’s essential for users to see the most current information right away.
Using on-demand cache invalidation in these scenarios helps keep only the necessary data refreshed, preserving system performance while ensuring accurate, up-to-date information for users.
Connection pooling
Can I increase the query duration and response size limits for my Prisma Postgres instance?
Yes, you can increase your Prisma Postgres limits based on your subscription plan. Here are the configurable limits:
| Limit | Starter | Pro Plan | Business Plan |
|---|---|---|---|
| Query timeout | Up to 10 seconds | Up to 20 seconds | Up to 60 seconds |
| Interactive transactions timeout | Up to 15 seconds | Up to 30 seconds | Up to 90 seconds |
| Response size | Up to 5 MB | Up to 10 MB | Up to 20 MB |
Check the pricing page for more details on the available plans and their corresponding limits.
While you can increase these limits based on your subscription plan, it's still recommended to optimize your database operations. Learn more in our troubleshooting guide.
Query optimization
Prisma Postgres allows query optimization via Prisma Optimize and provides performance recommendations to help improve your database queries during development. You can enable it with Prisma Postgres or also use it with your own database, but setup and integration steps differ.
Can you automatically implement optimizations?
Prisma Postgres's query optimization feature offers insights and recommendations on how to improve your database queries. It does not alter any existing queries or your Prisma schema.
How long is a recording session retained?
There are no limits on the storage retention period. A query performance recording session will be stored until you explicitly delete it.
Do recommendation limits reset monthly?
Yes, the recommendation usage resets at the beginning of each calendar month. For example, if you use 5 recommendations by the end of the month, your usage will reset to 0 at the start of the next month.
Can I get charged for exceeding the recommendation limit on the starter plan?
Yes, if you’re on the starter plan, exceeding 5 recommendations in a billing cycle will result in a $5 charge at the end of that cycle. For more information, visit our pricing page.
How are viewed Prisma AI recommendations tracked for billing? Are they counted based on generated or viewed recommendations?
They are counted based on viewed recommendations. Once you click on a recommendation from the recommendations table and view the recommendation's detail page, it counts as being seen.
Can I enable query optimizations for Prisma Postgres in production?
No, query optimizations for Prisma Postgres is not meant to be enabled for production use. It is specifically designed for local development, providing valuable insights and optimizations during that phase. While it's technically possible to run it in a production environment, doing so could result in performance problems or unexpected behaviors, as this is not built to handle the complexity and scale of production workloads. For the best experience, we recommend testing query optimization solely in your development environment.
You can use the enable property in the client extension to run it only in development environment. By default, the enable property is set to true.
import { PrismaClient } from '@prisma/client'
import { withOptimize } from "@prisma/extension-optimize"
const prisma = new PrismaClient().$extends(
withOptimize({
apiKey: process.env.OPTIMIZE_API_KEY,
enable: process.env.ENVIRONMENT === 'development',
})
);