{"id":16874548,"url":"https://github.com/joway/sheetsql","last_synced_at":"2025-07-29T16:35:49.908Z","repository":{"id":40357132,"uuid":"283447272","full_name":"joway/sheetsql","owner":"joway","description":"Google Spreadsheet as a Database","archived":false,"fork":false,"pushed_at":"2022-06-25T14:38:11.000Z","size":371,"stargazers_count":188,"open_issues_count":10,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-16T08:51:12.538Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joway.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-29T08:49:39.000Z","updated_at":"2025-03-06T07:36:23.000Z","dependencies_parsed_at":"2022-09-04T13:22:38.149Z","dependency_job_id":null,"html_url":"https://github.com/joway/sheetsql","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joway%2Fsheetsql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joway%2Fsheetsql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joway%2Fsheetsql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joway%2Fsheetsql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joway","download_url":"https://codeload.github.com/joway/sheetsql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243985864,"owners_count":20379219,"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-10-13T15:33:14.481Z","updated_at":"2025-03-17T06:31:24.389Z","avatar_url":"https://github.com/joway.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# SheetSQL\n\n\u003cimg width=\"200px;\" src=\"logo.png\" /\u003e\n\n[![npm](https://img.shields.io/npm/v/sheetsql.svg)](https://www.npmjs.com/package/sheetsql)\n[![CircleCI](https://circleci.com/gh/joway/sheetsql.svg?style=shield)](https://circleci.com/gh/joway/sheetsql)\n\nGoogle Spreadsheet as a Database.\n\n## Purpose\n\nIn the past, I often asked by non-technical colleagues to do some DB scripts jobs to mapping their spreadsheets data to the production database. And when their data changes the same work needs to be done again. Since these data are not changed too frequently(compared with other online data), it's also not worth to make a content management system for them.\n\nBut why don't make their spreadsheets as a real production database?  That's what [\"Single source of truth\"](https://en.wikipedia.org/wiki/Single_source_of_truth) means. What's more, you even could write back some statistical data like \"Page View\" to the spreadsheets, so they could see the feedback clearly and continue to optimize the content.\n\n## Requirements\n\n1. Create a Google Spreadsheet and populate the first row with the columns names, here is an [Example Sheet](https://docs.google.com/spreadsheets/d/1ya2Tl2ev9M80xYwspv7FJaoWq0oVOMBk3VF0f0MXv2s/edit?usp=sharing).\n2. Create a [Google Cloud Service Account](https://cloud.google.com/docs/authentication/production) and download the JSON file that contains your key.\n3. Find your service account email in [credentials console](https://console.cloud.google.com/apis/credentials) which similar with `account-name@project-name.iam.gserviceaccount.com`. \n4. Share your sheets to the above email, and make sure you have assigned it as an editor.\n\n![](./policy.png)\n\n## Usage\n\n### Concepts\n\n#### db\n\n`db` means the Google Spreadsheet ID. You can find it in your sheet's URL: `https://docs.google.com/spreadsheets/d/${YOUR_SHEETS_ID}/edit`\n\n#### table\n\n`table` means the Sheet Name in your Spreadsheet. The default is `Sheet1`.\n\n#### data type\n\nEvery data in sheetsql will be set/get as a string. You need to handle the type mapping on your side.\n\n#### keyFile\n\nYour service account JSON key file.\n\n### Install\n\n```\nnpm i sheetsql -S\n```\n\n### Example\n\n```typescript\nconst db = new Database({\n  db: '1ya2Tl2ev9M80xYwspv7FJaoWq0oVOMBk3VF0f0MXv2s',\n  table: 'Sheet1', // optional, default = Sheet1\n  keyFile: './google-serviceaccount.json',\n  cacheTimeoutMs: 5000, // optional, default = 5000\n})\n\n// load schema and data from google spreadsheet\nawait db.load()\n\n// insert multiple documents\nlet docs = await db.insert([\n  {\n    name: 'joway',\n    age: 18,\n  },\n])\n\n// find documents and update them\ndocs = await db.update(\n  {\n    name: 'joway',\n  },\n  {\n    age: 100,\n  },\n)\n\n// find documents\ndocs = await db.find({\n  name: 'joway',\n})\n\n// find all documents\ndocs = await db.find({})\n\n// find documents and remove them\ndocs = await db.remove({\n  name: 'joway',\n})\n```\n\n### Using a Proxy\n\nsheetsql depend on `googleapis` lib in which you can set the following environment variables to proxy http/https requests:\n\n- `HTTP_PROXY` / `http_proxy`\n- `HTTPS_PROXY` / `https_proxy`\n\nThe two environment variables could let your all requests using the proxy. If that is not your expected behavior and you only need to proxy google APIs, set `NO_PROXY=*`.\n\nHere is the [discuss](https://github.com/joway/sheetsql/issues/4).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoway%2Fsheetsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoway%2Fsheetsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoway%2Fsheetsql/lists"}