{"id":15041214,"url":"https://github.com/zaadevofc/spreadsheet-db","last_synced_at":"2026-01-07T11:15:17.249Z","repository":{"id":204871398,"uuid":"712378164","full_name":"zaadevofc/spreadsheet-db","owner":"zaadevofc","description":"Using Google Sheets API as a fast and efficient SQL Database alternative, just kidding :/","archived":false,"fork":false,"pushed_at":"2023-11-01T11:37:22.000Z","size":16,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-02T17:03:45.263Z","etag":null,"topics":["database","db","node","spread-db","spreadsheet","spreadsheets","sql"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@zaadevofc/spreadsheet-db","language":"JavaScript","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/zaadevofc.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-31T10:58:36.000Z","updated_at":"2023-11-01T12:04:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"442117e0-2d47-4d37-949a-80904cfe05bd","html_url":"https://github.com/zaadevofc/spreadsheet-db","commit_stats":null,"previous_names":["zaadevofc/spreadsheet-db"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaadevofc%2Fspreadsheet-db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaadevofc%2Fspreadsheet-db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaadevofc%2Fspreadsheet-db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaadevofc%2Fspreadsheet-db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaadevofc","download_url":"https://codeload.github.com/zaadevofc/spreadsheet-db/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245814748,"owners_count":20676808,"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","db","node","spread-db","spreadsheet","spreadsheets","sql"],"created_at":"2024-09-24T20:45:46.117Z","updated_at":"2026-01-07T11:15:17.215Z","avatar_url":"https://github.com/zaadevofc.png","language":"JavaScript","readme":"# @zaadevofc/spreadsheet-db\n\u003e Using [Google Sheets API](https://developers.google.com/sheets/api/guides/concepts) as a fast and efficient SQL Database alternative, just kidding :/\nfull thanks for library support by ❤️ [google-spreadsheet](https://www.npmjs.com/package/google-spreadsheet) ❤️\n\n[![NPM version](https://img.shields.io/npm/v/@zaadevofc/spreadsheet-db)](https://www.npmjs.com/package/@zaadevofc/spreadsheet-db)\n[![Known Vulnerabilities](https://snyk.io/test/github/zaadevofc/spreadsheet-db/badge.svg?targetFile=package.json)](https://snyk.io/test/github/zaadevofc/spreadsheet-db?targetFile=package.json)\n[![NPM](https://img.shields.io/npm/dw/@zaadevofc/spreadsheet-db)](https://www.npmtrends.com/@zaadevofc/spreadsheet-db)\n\n- **CRUD** - to eazy and very simple like a database\n- **JSON FORMAT** - the results will be in JSON format which is very easy for management\n- **EXPORT** - download sheet/docs in various formats `xlsx,ods,tsv,csv,pdf,zip`\n\n**Docs -**\nMeanwhile, currently the documentation is only in the readme file for this library [https://github.com/zaadevofc/spreadsheet-db#readme](https://github.com/zaadevofc/spreadsheet-db#readme)\n\n-------------\n\n\u003e 🔥 **Installation** - `npm i @zaadevofc/spreadsheet-db --save` or `yarn add @zaadevofc/spreadsheet-db`\n\n## ~ Authentication 🔓\n\u003e first of all, we need the `private_key` and `client_email` from your Service account, follow the steps below:\n\n### @ Create Project \n1. visit google console to create new project [here](https://console.cloud.google.com/projectcreate)\n2. follow the commands requested, then when finished proceed to the next step\n\n### @ Create Credentials\n1. visit [Service accounts page](https://console.cloud.google.com/apis/credentials)\n2. click blue **+ CREATE CREDENTIALS** and select **Service account** option\n3. enter name, description, click **CREATE**\n4. you can skip permissions, click **CONTINUE**\n5. click your project select tab **keys** and click **ADD KEY** anda then click **Create new key** button\n6. select the **JSON** key type option\n7. click **Create** button\n8. your JSON key file is generated and downloaded to your machine (it is the only copy!)\n9. click **DONE**\n\n\u003e and you must enable sheets APi :\n\n1. click [here](https://console.cloud.google.com/apis/library/sheets.googleapis.com) to enable the sheets APi\n2. **enable** the api\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-7.png)\n\n## ~ Congrats 🎉\n\nyour credentials more or less will look like this :\n\n```json\n{\n    \"type\": \"\",\n    \"project_id\": \"\",\n    \"private_key_id\": \"\",\n    \"private_key\": \"\",\n    \"client_email\": \"\",\n    \"client_id\": \"\",\n    \"auth_uri\": \"\",\n    \"token_uri\": \"\",\n    \"auth_provider_x509_cert_url\": \"\",\n    \"client_x509_cert_url\": \"\",\n    \"universe_domain\": \"\"\n}\n```\n\nthis library only requires `private_key` and `client_email` properties. so you can save the file safely, and put the required properties into the `.env` file\n\n### ~ Preparing 🔨\n\n\u003e **Note** - you have to create a _spreadsheet_ first on the [Google Sheets page](https://docs.google.com/spreadsheets) and you have to update its privacy to **public** and **be allowed to edit it**\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-1.png)\n\n\nlater we will register your **spreadsheets ID**, below is where the ID is located :\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-2.png)\n\n\n## ~ Configuration ⚙️\n\n```js\nconst SpreadDB = require('@zaadevofc/spreadsheet-db')\nconst spreadDB = new SpreadDB({ \n    client_email: process.env.SERVICE_CLIENT_EMAIL, \n    private_key: process.env.GOOGLE_PRIVATE_KEY \n});\n```\n\n\u003e **Note** - To keep the examples concise, I'm calling await at the top level which is not allowed by default in most versions of node. If you need to call await in a script at the root level, you must instead wrap it in an async function like so:\n\n```js\n(async () =\u003e {\n    // async function here\n})()\n```\n\n## ~ How to use 🌈\n\n#### 🛠️ register your spreadsheets id :\n\n```js\nconst db = await spreadDB.register(/* your spreadsheets id */)\n\n// if you want to use multiple id\nconst db1 = await spreadDB.register(/* your spreadsheets id */)\nconst db2 = await spreadDB.register(/* your spreadsheets id */)\n```\n\n#### 🛠️ create new sheet :\n\n\u003e **Note** - the sheet display is something like this :\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-3.png)\n\n\n```js\nawait db.addSheet(/* name your new sheet */)\n// example\nawait db.addSheet('users')\n```\n\nthe changes will look like this:\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-5.png)\n\n#### 🛠️ adding value to sheet\n\u003e **Note** - i recommend that you create a header first before giving it a value with this program, you can see the example below:\n\n\u003e _**you must place the header starting from column A1 and add at least 1 value so that the program follows the previous style**_\n\n#### ✅ correct header\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-12.png)\n\n#### ❌ wrong header\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-13.png)\n\n#### example table :\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-9.png)\n\ncode :\n\n```js\n// add multiple value\nawait db.addValue('users', [\n    [12345, 'alex', 12],\n    [12346, 'dodo', 18],\n    [12347, 'adit', 22],\n]);\n```\n\nresult :\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-10.png)\n\nthe contents of the array depend on how many rows there are in your header\n\n| ID | NAME | AGE | HOBBY | WORK |\n|:----:|:------:|:-----:|:-------:|:------:|\n|  array[0]  |   array[1]   |  array[2]   |   array[3]    |   array[4]\n\n#### code :\n\n```js\nawait db.addValue('users', [\n    [/* value array [0] */, /* value array [1] */, /* value array [2] */, /* value array [3] */, /* value array [4] */],\n]);\n```\n\n#### 🛠️ delete latest rows from sheet\n\nexample table :\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  2 | rosyid |  20 |\n|  3 |   ditha  |  21 |\n|  4 |  keja  |  25 |\n\nwith this function :\n\n```js\nawait db.deleteLatestRows(/* your sheet title/name */);\n//example\nawait db.deleteLatestRows('users');\n```\n\nlater it will be like this :\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  2 | rosyid |  20 |\n|  3 |   ditha  |  21 |\n\n#### 🛠️ delete rows by criteria\n\nexample table :\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  2 | rosyid |  20 |\n|  3 |   ditha  |  21 |\n|  4 |  keja  |  25 |\n\n```js\nawait db.deleteRowsByCriteria(/* your sheet title/name */, { \n    key: /* this key alias the header */, \n    value: /* value of key */ \n});\n// example\nawait db.deleteRowsByCriteria('users', { \n    key: 'AGE', \n    value: 20 \n});\n```\n\nresult :\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  3 |   ditha  |  21 |\n|  4 |  keja  |  25 |\n\n#### 🛠️ delete sheet :\n\nthis function will delete a sheet based on existing properties:\n\n```js\nawait db.deleteSheetById(/* your sheet id */);\nawait db.deleteSheetByIndex(/* your sheet index */);\nawait db.deleteSheetByTitle(/* your sheet name/title */);\n```\n\n#### 🛠️ update rows by criteria\n\nexample table :\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  2 | rosyid |  20 |\n|  3 |   ditha  |  21 |\n|  4 |  keja  |  25 |\n\n```js\nawait db.updateRowsByCriteria('users', \n{ \n    key: 'NAME', \n    value: 'ditha' \n},{ \n    update_key: 'AGE', \n    update_value: 32\n})\n```\n\nresult :\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  2 | rosyid |  20 |\n|  3 |   ditha  |  32 |\n|  4 |  keja  |  25 |\n\n\n#### 🛠️ update sheet or doc properties\n\nthis is doc title/name :\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-11.png)\n\nthis is sheet title/name :\n\n![image tutorial](https://raw.githubusercontent.com/zaadevofc/zaadevofc/main/zaadevofc-spreadsheet-db-tutor-3.png)\n\nyou can use the code below :\n\n```js\ndb.changeDocTitle(/* new doc title/name */);\ndb.changeSheetTitleByTitle(/* sheet title/name */, /* new sheet title/name */);\ndb.changeSheetTitleById(/* sheet id */, /* new sheet title/name */);\ndb.changeSheetTitleByIndex(/* sheet index */, /* new sheet title/name */);\n```\n\n#### 🛠️ get all data\n\nfetching all data from your doc :\n\n```js\ndb.getData()\n```\n\n//=\u003e result :\n\n```js\n{\n  title: '',\n  locale: '',\n  autoRecalc: '',\n  timeZone: '',\n  sheetCount: 0,\n  spreadsheetId: '',\n  spreadsheetUrl: '',\n  googleDriveUrl: '',\n  rawSheets: [],\n}\n```\n\n//=\u003e rawSheets :\n```js\n{\n    sheetId: 0,\n    title: '',\n    index: 0,\n    sheetType: '',\n    spreadsheetUrl: '',\n    rowCount: 0,\n    columnCount: 0,\n    headerRowIndex: 0,\n    contentCounts: 0,\n    contents: [],\n}\n```\n\n//=\u003e contents :\n\u003e the `contents` of the content property depend on the contents of your sheet, I give an example using a table like this:\n\n| ID |  NAME  | AGE |\n|:--:|:------:|:---:|\n|  1 |  jamal |  23 |\n|  2 | rosyid |  20 |\n|  3 |   ditha  |  32 |\n|  4 |  keja  |  25 |\n\nresult of property `contents` :\n\n```js\n{\n    { index: 0, id: '1', name: 'jamal', age: '23' },\n    { index: 1, id: '2', name: 'rosyid', age: '20' },\n    { index: 2, id: '3', name: 'ditha', age: '32' },\n    { index: 3, id: '4', name: 'kejaa', age: '25' }\n}\n```\n\n#### 🛠️ get data sheet\n\nthis will return a **data sheet** based on existing properties:\n\n```js\ndb.getAllSheets();\ndb.getSheetByIndex(/* your sheet index */);\ndb.getSheetById(/* your sheet id */);\ndb.getSheetByTitle(/* your sheet title */);\n```\n\n#### 🛠️ get data contents\n\nthis will return a **sheet contents** based on existing properties:\n\n```js\ndb.getAllContents();\ndb.getContentByIndex(/* your sheet index */);\ndb.getContentById(/* your sheet id */);\ndb.getContentByTitle(/* your sheet title */);\n```\n\n## Support \u0026 Contributions\n\nThis module was written and is actively maintained by [zaadevofc](https://github.com/zaadevofc). If you want to develop this module, you can do that because this module is free and open source\n\n\u003e **Want to help support it? Buy me inspiration**\n[Saweria](https://saweria.co/zaadevofc)\n\n## License\nThis is free and unencumbered public domain software. For more info, see https://unlicense.org.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaadevofc%2Fspreadsheet-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaadevofc%2Fspreadsheet-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaadevofc%2Fspreadsheet-db/lists"}