{"id":19683886,"url":"https://github.com/prisma/extension-read-replicas","last_synced_at":"2025-04-12T15:32:18.663Z","repository":{"id":185910942,"uuid":"672001074","full_name":"prisma/extension-read-replicas","owner":"prisma","description":"Prisma Client Extension to add read replica support to your Prisma Client","archived":false,"fork":false,"pushed_at":"2025-03-25T08:53:23.000Z","size":156,"stargazers_count":115,"open_issues_count":20,"forks_count":13,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-05T14:02:02.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prisma.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-28T16:49:02.000Z","updated_at":"2025-04-04T04:35:57.000Z","dependencies_parsed_at":"2023-08-16T17:17:01.526Z","dependency_job_id":"4b38ba38-fca0-464c-b884-e5f9c9bb6c09","html_url":"https://github.com/prisma/extension-read-replicas","commit_stats":null,"previous_names":["prisma/extension-read-replicas"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prisma%2Fextension-read-replicas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prisma%2Fextension-read-replicas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prisma%2Fextension-read-replicas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prisma%2Fextension-read-replicas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prisma","download_url":"https://codeload.github.com/prisma/extension-read-replicas/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248173809,"owners_count":21059594,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T18:15:59.080Z","updated_at":"2025-04-12T15:32:18.635Z","avatar_url":"https://github.com/prisma.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @prisma/extension-read-replicas\n\nThis [Prisma Client Extension](https://www.prisma.io/docs/concepts/components/prisma-client/client-extensions) adds read replica support to your Prisma Client. Under the hood, this extension creates additional Prisma Clients for the read replica database connection strings, and then routes read queries to these Clients instead of using the primary Prisma Client.\n\n## Requirements\n\nRequires Prisma 5.2+.\n\n## Installation\n\nDepending on the package manager of your choice:\n\n### `npm`\n\n```sh\nnpm install @prisma/extension-read-replicas\n```\n\n### `yarn`\n\n```sh\nyarn add @prisma/extension-read-replicas\n```\n\n### `pnpm`\n\n```sh\npnpm add @prisma/extension-read-replicas\n```\n\n## Usage\n\n### Initialization\n\n```ts\nimport { PrismaClient } from '@prisma/client'\nimport { readReplicas } from '@prisma/extension-read-replicas'\n\nconst prisma = new PrismaClient().$extends(\n  readReplicas({\n    url: 'postgresql://replica.example.com:5432/db',\n  }),\n)\n```\n\nAll non-transactional read queries will now be executed against the defined replica.  \nWrite queries and transactions will be executed against the primary server.\n\n**Note**: `queryRaw` and `executeRaw` are always executed against the primary server by default since\nthe extension can not know for sure if a particular raw query would read or write to the database.\nUse the `$replica()` method to explicitly route the request to a read replica.\n\n### Multiple replicas\n\nYou can also initialize the extension with an array of replica connection strings:\n\n```ts\nconst prisma = new PrismaClient().$extends(\n  readReplicas({\n    url: [\n      'postgresql://replica-1.example.com:5432/db',\n      'postgresql://replica-2.example.com:5432/db',\n    ],\n  }),\n)\n```\n\nIn this case, a replica for each read query will be selected randomly.\n\n### Pre-configured clients\n\nIf you want to supply additional options to replica client, you can also pass pre-configured read clients instead of urls:\n\n```ts\nconst replicaClient = new PrismaClient({\n  datasourceUrl: 'postgresql://replica.example.com:5432/db'\n  log: [{ level: 'query', emit: 'event' }]\n})\n\nreplicaClient.$on('query', (event) =\u003e console.log('Replica event', event))\n\nconst prisma = new PrismaClient().$extends(\n  readReplicas({\n    replicas: [\n      replicaClient\n    ],\n  }),\n)\n```\n\n### Bypassing the replicas\n\nIf you want to execute a read query against the primary server, you can use the `$primary()` method on your extended client:\n\n```ts\nprisma.$primary().user.findMany({ where: { ... }})\n```\n\n### Forcing request to go through a replica\n\nSometimes you might want to do the opposite and route the request to a replica even though\nit will be routed to primary by default. In that case, you can use the `$replica()` method:\n\n```ts\nprisma.$replica().$queryRaw`SELECT ...`\n```\n\n### Caveats and limitations\n\n- At the moment, if you are using this read replicas extension alongside other extensions, this extension should be applied last:\n\n  ```ts\n  const prisma = new PrismaClient()\n    .$extends(withAccelerate())\n    .$extends(rlsExtension())\n    .$extends(\n      readReplicas({\n        url: 'postgresql://replica.example.com:5432/db',\n      }),\n    )\n  ```\n\n- If you use the read replicas extension with Prisma version below 5.1, any result extensions will not work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprisma%2Fextension-read-replicas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprisma%2Fextension-read-replicas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprisma%2Fextension-read-replicas/lists"}