{"_id":"@clarityengineering/extension-read-replicas","_rev":"2-58df48c3b25b0816adca1872fa9a6574","name":"@clarityengineering/extension-read-replicas","dist-tags":{"latest":"0.6.5"},"versions":{"0.6.3":{"name":"@clarityengineering/extension-read-replicas","version":"0.6.3","keywords":[],"author":{"name":"Clarity Pediatrics"},"license":"Apache-2.0","_id":"@clarityengineering/extension-read-replicas@0.6.3","maintainers":[{"name":"cp-scott","email":"scott@claritypediatrics.com"}],"homepage":"https://github.com/claritypediatrics/extension-read-replicas","bugs":{"url":"https://github.com/claritypediatrics/extension-read-replicas/issues"},"dist":{"shasum":"5e3843bcaf33ddab33c12be5846f61daa59851b0","tarball":"https://registry.npmjs.org/@clarityengineering/extension-read-replicas/-/extension-read-replicas-0.6.3.tgz","fileCount":7,"integrity":"sha512-H4+THdddjN0HpxsBV58o1gQCFgtcFnIeMlg2N54OD4vAP+qSSkGWGKPoqs4gtm8c4ulDFwTxOeNrV3vk7kFl9w==","signatures":[{"sig":"MEQCIDC3Z1btnl4bzzP7eNqTBYArdyU709GKWvL2VuCKyyNGAiBdsCaczVbGfg/IGc1yRDxzKMqHWdVnOMkbCMQcs313RQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@clarityengineering%2fextension-read-replicas@0.6.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":28001},"main":"dist/index.js","_from":"file:clarityengineering-extension-read-replicas-0.6.3.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.js"}}},"scripts":{"demo":"node -r esbuild-register demo/index.ts","lint":"eslint . && prettier -c .","test":"jest","build":"tsup src/index.ts --format=cjs,esm --dts","typecheck":"tsc"},"_npmUser":{"name":"cp-scott","email":"scott@claritypediatrics.com"},"_resolved":"/tmp/2037aa55daf2fc8af71d565351294cba/clarityengineering-extension-read-replicas-0.6.3.tgz","_integrity":"sha512-H4+THdddjN0HpxsBV58o1gQCFgtcFnIeMlg2N54OD4vAP+qSSkGWGKPoqs4gtm8c4ulDFwTxOeNrV3vk7kFl9w==","repository":{"url":"git+https://github.com/claritypediatrics/extension-read-replicas.git","type":"git"},"_npmVersion":"10.8.2","description":"Prisma Read Replica Extension","directories":{"test":"tests"},"_nodeVersion":"20.18.1","dependencies":{"eslint-scope":"^7.2.2","eslint-visitor-keys":"^3.4.2"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.6.2","tsup":"^7.2.0","execa":"^5.1.1","husky":"^8.0.3","eslint":"^8.46.0","prisma":"6.1.0","esbuild":"^0.18.17","prettier":"^3.0.0","@swc/core":"^1.3.73","@swc/jest":"^0.2.27","typescript":"^5.1.6","@types/jest":"^29.5.3","@types/node":"16","lint-staged":"^13.2.3","@types/debug":"^4.1.8","@prisma/client":"5.2.0","esbuild-register":"^3.4.2","esbuild-node-externals":"^1.8.0","eslint-config-prettier":"^8.9.0","@typescript-eslint/parser":"^6.2.1","@typescript-eslint/eslint-plugin":"^6.2.1"},"peerDependencies":{"@prisma/client":">=5.2.0"},"_npmOperationalInternal":{"tmp":"tmp/extension-read-replicas_0.6.3_1737877854098_0.4855095676378123","host":"s3://npm-registry-packages-npm-production"}},"0.6.4":{"name":"@clarityengineering/extension-read-replicas","version":"0.6.4","keywords":[],"author":{"name":"Clarity Pediatrics"},"license":"Apache-2.0","_id":"@clarityengineering/extension-read-replicas@0.6.4","maintainers":[{"name":"cp-scott","email":"scott@claritypediatrics.com"}],"homepage":"https://github.com/claritypediatrics/extension-read-replicas","bugs":{"url":"https://github.com/claritypediatrics/extension-read-replicas/issues"},"dist":{"shasum":"4511c2a769cae74b177c162564ce13f0f7e26699","tarball":"https://registry.npmjs.org/@clarityengineering/extension-read-replicas/-/extension-read-replicas-0.6.4.tgz","fileCount":7,"integrity":"sha512-Ivgyv2NI9N3YePiI6lrznDGZ+fEDql/FQMuFSyOSsJHjrKMHjy+57Q8wbQ4pI93R8CSAxIpo1IG0TW/IJO0/BQ==","signatures":[{"sig":"MEYCIQCeLyM1i59WhmttjoKaqnMk+8UULTRnzV/LpFzsdbQyIgIhAIjsGC+purSHes/6uCGGHGRFkR7m8L8W8HQl3AprEgZJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@clarityengineering%2fextension-read-replicas@0.6.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":28061},"main":"dist/index.js","_from":"file:clarityengineering-extension-read-replicas-0.6.4.tgz","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.js"}}},"scripts":{"demo":"node -r esbuild-register demo/index.ts","lint":"eslint . && prettier -c .","test":"jest","build":"tsup src/index.ts --format=cjs,esm --dts","typecheck":"tsc"},"_npmUser":{"name":"cp-scott","email":"scott@claritypediatrics.com"},"_resolved":"/tmp/6f52b5dc33e02dca4867dabf42c3fa2f/clarityengineering-extension-read-replicas-0.6.4.tgz","_integrity":"sha512-Ivgyv2NI9N3YePiI6lrznDGZ+fEDql/FQMuFSyOSsJHjrKMHjy+57Q8wbQ4pI93R8CSAxIpo1IG0TW/IJO0/BQ==","repository":{"url":"git+https://github.com/claritypediatrics/extension-read-replicas.git","type":"git"},"_npmVersion":"10.8.2","description":"Prisma Read Replica Extension","directories":{"test":"tests"},"_nodeVersion":"20.18.1","dependencies":{"eslint-scope":"^7.2.2","eslint-visitor-keys":"^3.4.2"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.6.2","tsup":"^7.2.0","execa":"^5.1.1","husky":"^8.0.3","eslint":"^8.46.0","prisma":"6.1.0","esbuild":"^0.18.17","prettier":"^3.0.0","@swc/core":"^1.3.73","@swc/jest":"^0.2.27","typescript":"^5.1.6","@types/jest":"^29.5.3","@types/node":"16","lint-staged":"^13.2.3","@types/debug":"^4.1.8","@prisma/client":"5.2.0","esbuild-register":"^3.4.2","esbuild-node-externals":"^1.8.0","eslint-config-prettier":"^8.9.0","@typescript-eslint/parser":"^6.2.1","@typescript-eslint/eslint-plugin":"^6.2.1"},"peerDependencies":{"@prisma/client":">=5.2.0"},"_npmOperationalInternal":{"tmp":"tmp/extension-read-replicas_0.6.4_1737878648602_0.9557907314909981","host":"s3://npm-registry-packages-npm-production"}},"0.6.5":{"name":"@clarityengineering/extension-read-replicas","version":"0.6.5","description":"Prisma Read Replica Extension","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","homepage":"https://github.com/claritypediatrics/extension-read-replicas","repository":{"type":"git","url":"git+https://github.com/claritypediatrics/extension-read-replicas.git"},"exports":{".":{"require":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"}}},"keywords":[],"author":{"name":"Clarity Pediatrics"},"license":"Apache-2.0","peerDependencies":{"@prisma/client":">=5.2.0"},"devDependencies":{"@prisma/client":"5.2.0","@swc/core":"^1.3.73","@swc/jest":"^0.2.27","@types/debug":"^4.1.8","@types/jest":"^29.5.3","@types/node":"16","@typescript-eslint/eslint-plugin":"^6.2.1","@typescript-eslint/parser":"^6.2.1","esbuild":"^0.18.17","esbuild-node-externals":"^1.8.0","esbuild-register":"^3.4.2","eslint":"^8.46.0","eslint-config-prettier":"^8.9.0","execa":"^5.1.1","husky":"^8.0.3","jest":"^29.6.2","lint-staged":"^13.2.3","prettier":"^3.0.0","prisma":"6.2.1","tsup":"^7.2.0","typescript":"^5.1.6"},"directories":{"test":"tests"},"dependencies":{"eslint-scope":"^7.2.2","eslint-visitor-keys":"^3.4.2"},"bugs":{"url":"https://github.com/claritypediatrics/extension-read-replicas/issues"},"scripts":{"build":"tsup src/index.ts --format=cjs,esm --dts","demo":"node -r esbuild-register demo/index.ts","lint":"eslint . && prettier -c .","test":"jest","typecheck":"tsc"},"_id":"@clarityengineering/extension-read-replicas@0.6.5","_integrity":"sha512-ZQ+WDXpQ9tUd275ja1QFKJPe2b9+3rhDhK8GvnOYty6Iudjn1knXQOiDpOKhnRbptCTVylhnxeb+iW0VkAs8ow==","_resolved":"/tmp/d7977a79729a24deeb377cbcb41e919e/clarityengineering-extension-read-replicas-0.6.5.tgz","_from":"file:clarityengineering-extension-read-replicas-0.6.5.tgz","_nodeVersion":"20.18.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-ZQ+WDXpQ9tUd275ja1QFKJPe2b9+3rhDhK8GvnOYty6Iudjn1knXQOiDpOKhnRbptCTVylhnxeb+iW0VkAs8ow==","shasum":"8c677d128176b57ac39d749f352c69d8aa0ba440","tarball":"https://registry.npmjs.org/@clarityengineering/extension-read-replicas/-/extension-read-replicas-0.6.5.tgz","fileCount":7,"unpackedSize":28061,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@clarityengineering%2fextension-read-replicas@0.6.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGeZj6ISs+YjEbJoGHKKDCy0yOv5PlsOc3y4HGEVw8t1AiEAhyffN3feZFI9X6nq0yaxxL/G2Dvcw581Hh/aitqkyWo="}]},"_npmUser":{"name":"cp-scott","email":"scott@claritypediatrics.com"},"maintainers":[{"name":"cp-scott","email":"scott@claritypediatrics.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/extension-read-replicas_0.6.5_1737881302351_0.3830284411223017"},"_hasShrinkwrap":false}},"time":{"created":"2025-01-26T07:50:53.982Z","modified":"2025-01-26T08:48:23.009Z","0.6.3":"2025-01-26T07:50:54.254Z","0.6.4":"2025-01-26T08:04:08.799Z","0.6.5":"2025-01-26T08:48:22.547Z"},"bugs":{"url":"https://github.com/claritypediatrics/extension-read-replicas/issues"},"author":{"name":"Clarity Pediatrics"},"license":"Apache-2.0","homepage":"https://github.com/claritypediatrics/extension-read-replicas","keywords":[],"repository":{"type":"git","url":"git+https://github.com/claritypediatrics/extension-read-replicas.git"},"description":"Prisma Read Replica Extension","maintainers":[{"name":"cp-scott","email":"scott@claritypediatrics.com"}],"readme":"# @clarityengineering/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 @clarityengineering/extension-read-replicas\n```\n\n### `yarn`\n\n```sh\nyarn add @clarityengineering/extension-read-replicas\n```\n\n### `pnpm`\n\n```sh\npnpm add @clarityengineering/extension-read-replicas\n```\n\n## Usage\n\n### Initialization\n\n```ts\nimport { PrismaClient } from '@prisma/client'\nimport { readReplicas } from '@clarityengineering/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) => 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\n## Development\n\nNote: To run the tests, you need to have Docker installed and running.\n\n- Run `docker-compose up` to start the Postgres primary and replica\n- Set the environment variables `DATABASE_URL` and `REPLICA_URL` to the connection strings for the primary and replica:\n\n  ```sh\n  export DATABASE_URL='postgresql://prisma:prisma@localhost:6432/test'\n  export REPLICA_URL='postgresql://prisma:prisma@localhost:7432/test'\n  ```\n\n- Run `pnpm test` to run the tests\n","readmeFilename":"README.md"}