{"id":13504376,"url":"https://github.com/planetscale/database-js","last_synced_at":"2025-05-14T14:08:40.060Z","repository":{"id":56857080,"uuid":"518574859","full_name":"planetscale/database-js","owner":"planetscale","description":"A Fetch API-compatible PlanetScale database driver","archived":false,"fork":false,"pushed_at":"2024-10-29T18:01:04.000Z","size":549,"stargazers_count":1180,"open_issues_count":16,"forks_count":37,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-28T13:59:41.598Z","etag":null,"topics":["database","edge-computing","mysql","serverless","vercel"],"latest_commit_sha":null,"homepage":"https://planetscale.com/docs/tutorials/planetscale-serverless-driver","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/planetscale.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":"2022-07-27T18:43:03.000Z","updated_at":"2025-04-25T17:24:22.000Z","dependencies_parsed_at":"2024-01-13T19:20:11.904Z","dependency_job_id":"e35564a0-17ce-4514-b471-6be1fd9b488b","html_url":"https://github.com/planetscale/database-js","commit_stats":{"total_commits":237,"total_committers":23,"mean_commits":"10.304347826086957","dds":0.5485232067510548,"last_synced_commit":"f62005c7e5d31a1e1b475ee6aad7f20ca3dba911"},"previous_names":["planetscale/edge-js"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planetscale%2Fdatabase-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planetscale%2Fdatabase-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planetscale%2Fdatabase-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planetscale%2Fdatabase-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/planetscale","download_url":"https://codeload.github.com/planetscale/database-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159924,"owners_count":22024566,"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":["database","edge-computing","mysql","serverless","vercel"],"created_at":"2024-08-01T00:00:35.717Z","updated_at":"2025-05-14T14:08:40.038Z","avatar_url":"https://github.com/planetscale.png","language":"TypeScript","readme":"![PlanetScale serverless driver for JavaScript](https://github.com/planetscale/database-js/assets/440926/0dfab33f-b01f-4814-ae40-c5fe5cbe94e3)\n\n# PlanetScale serverless driver for JavaScript\n\nA Fetch API-compatible PlanetScale database driver for serverless and edge compute platforms that require HTTP external connections, such as Cloudflare Workers or Vercel Edge Functions\n\n## Installation\n\n```sh\nnpm install @planetscale/database\n```\n\n## Usage\n\n```ts\nimport { connect } from '@planetscale/database'\n\nconst config = {\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n}\n\nconst conn = connect(config)\nconst results = await conn.execute('select 1 from dual where 1=?', [1])\nconsole.log(results)\n```\n\n### Database URL\n\nA single database URL value can be used to configure the `host`, `username`, and `password` values.\n\n```ts\nimport { connect } from '@planetscale/database'\n\nconst config = {\n  url: process.env['DATABASE_URL'] || 'mysql://user:pass@host'\n}\n\nconst conn = connect(config)\n```\n\n### Connection factory\n\nUse the `Client` connection factory class to create fresh connections for each transaction or web request handler.\n\n```ts\nimport { Client } from '@planetscale/database'\n\nconst client = new Client({\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n})\n\nconst conn = client.connection()\nconst results = await conn.execute('select 1 from dual')\nconsole.log(results)\n```\n\n### Transactions\n\nUse the `transaction` function to safely perform database transactions. If any unhandled errors are thrown during execution of the transaction, the transaction will be rolled back.\n\nThe following example is based on [the Slotted Counter Pattern](https://planetscale.com/blog/the-slotted-counter-pattern).\n\n```ts\nimport { connect } from '@planetscale/database'\n\nconst config = {\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n}\n\nconst conn = connect(config)\nconst results = await conn.transaction(async (tx) =\u003e {\n  const whenBranch = await tx.execute('INSERT INTO branches (database_id, name) VALUES (?, ?)', [42, \"planetscale\"])\n  const whenCounter = await tx.execute('INSERT INTO slotted_counters(record_type, record_id, slot, count) VALUES (?, ?, RAND() * 100, 1) ON DUPLICATE KEY UPDATE count = count + 1', ['branch_count', 42])\n  return [whenBranch, whenCounter]\n})\nconsole.log(results)\n```\n\n### Custom fetch function\n\nNode.js version 18 includes a built-in global `fetch` function. When using an older version of Node.js, you can provide a custom fetch function implementation. We recommend the [`undici`][1] package on which Node's built-in fetch is based.\n\n[1]: https://github.com/nodejs/undici\n\n```ts\nimport { connect } from '@planetscale/database'\nimport { fetch } from 'undici'\n\nconst config = {\n  fetch,\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n}\n\nconst conn = connect(config)\nconst results = await conn.execute('select 1 from dual')\nconsole.log(results)\n```\n\nTo leverage HTTP/2, you can use the [`fetch-h2`][2] shim. `fetch-h2` also supports Node.js 12+.\n\n[2]: https://www.npmjs.com/package/fetch-h2\n\n```ts\nimport { connect } from '@planetscale/database'\nimport { context } from 'fetch-h2'\nconst { fetch, disconnectAll } = context()\n\nconst config = {\n  fetch,\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n}\n\nconst conn = connect(config)\nconst results = await conn.execute('select 1 from dual')\nconsole.log(results)\nawait disconnectAll()\n```\n\n### Custom query parameter format function\n\nQuery replacement parameters identified with `?` are replaced with escaped values. Named replacement parameters are supported with a colon prefix.\n\n```ts\nconst results1 = await conn.execute('select 1 from dual where 1=?', [42])\nconst results2 = await conn.execute('select 1 from dual where 1=:id', { id: 42 })\n```\n\nProviding a custom format function overrides the built-in escaping with an external library, like [`sqlstring`](https://github.com/mysqljs/sqlstring).\n\n```ts\nimport { connect } from '@planetscale/database'\nimport SqlString from 'sqlstring'\n\nconst config = {\n  format: SqlString.format,\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n}\n\nconst conn = connect(config)\nconst results = await conn.execute('select 1 from dual where 1=?', [42])\nconsole.log(results)\n```\n\n### Custom type casting function\n\nColumn values are converted to their corresponding JavaScript data types. This can be customized by providing a `cast` function.\n\n```ts\nimport { connect, cast } from '@planetscale/database'\n\nfunction inflate(field, value) {\n  if (field.type === 'INT64' || field.type === 'UINT64') {\n    return BigInt(value)\n  }\n  return cast(field, value)\n}\n\nconst config = {\n  cast: inflate,\n  host: '\u003chost\u003e',\n  username: '\u003cuser\u003e',\n  password: '\u003cpassword\u003e'\n}\n\nconst conn = connect(config)\n```\n\nYou can also pass a custom `cast` function to `execute`. If present, this will override the `cast` function set by the connection:\n\n```ts\nconst result = await conn.execute(\n  'SELECT userId, SUM(balance) AS balance FROM UserBalanceItem GROUP BY userId',\n  {},\n  {\n    cast: (field, value) =\u003e {\n      if (field.name === 'balance') {\n        return BigInt(value)\n      }\n      return cast(field, value)\n    }\n  }\n)\n```\n\n### Row return values\n\nRows can be returned as an object or an array of column values by passing an `as` option to `execute`.\n\n```ts\nconst query = 'select 1 as one, 2 as two where 1=?'\nconst objects = conn.execute(query, [1], { as: 'object' })\n// objects.rows =\u003e [{one: '1', two: '2'}]\n\nconst arrays = conn.execute(query, [1], { as: 'array' })\n// arrays.rows =\u003e [['1', '2']]\n```\n\n## Development\n\n```sh\nnpm install\nnpm test\n```\n\n## Need help?\n\nGet help from [the PlanetScale support team](https://support.planetscale.com/), or [join our community on Discord](https://discord.gg/EqrcEf2dGv) or [GitHub discussion board](https://github.com/planetscale/discussion/discussions) to see how others are using PlanetScale.\n\n## License\n\nDistributed under the Apache 2.0 license. See LICENSE for details.\n","funding_links":[],"categories":["Database Tools","TypeScript","vercel"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplanetscale%2Fdatabase-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplanetscale%2Fdatabase-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplanetscale%2Fdatabase-js/lists"}