{"id":17948,"library":"sheetsql","title":"sheetsql","description":"sheetsql is a JavaScript/TypeScript library (currently at version 0.1.7) that enables developers to interact with Google Spreadsheets as if they were a simple database. It provides a programmatic API for performing CRUD (Create, Read, Update, Delete) operations on spreadsheet data, effectively turning a Google Sheet into a 'single source of truth' for non-technical users. This approach is particularly useful for scenarios where a full-fledged Content Management System (CMS) is overkill, but programmatic access to frequently updated spreadsheet data is required. The library is currently in an early development stage, indicated by its low version number, suggesting that future releases might introduce breaking changes. It differentiates itself by offering a direct, code-driven interface to Google Sheets data without requiring intermediate database synchronization, simplifying workflows for data managed primarily by business users.","status":"active","version":"0.1.7","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install sheetsql","lang":"bash","label":"npm"},{"cmd":"yarn add sheetsql","lang":"bash","label":"yarn"},{"cmd":"pnpm add sheetsql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Underpins all interactions with Google APIs, including Google Sheets.","package":"googleapis","optional":false}],"imports":[{"note":"sheetsql ships with TypeScript types and is best used in an ESM context. While CommonJS require might work via transpilation, ESM import is the idiomatic usage.","wrong":"const Database = require('sheetsql')","symbol":"Database","correct":"import { Database } from 'sheetsql'"}],"quickstart":{"code":"import { Database } from 'sheetsql';\nimport * as path from 'path';\n\n// Ensure your service account key file exists at this path.\n// For production, consider loading the key from environment variables or a secure secret management system.\nconst keyFilePath = path.resolve('./google-serviceaccount.json');\n\nconst runExample = async () => {\n  const db = new Database({\n    db: '1ya2Tl2ev9M80xYwspv7FJaoWq0oVOMBk3VF0f0MXv2s', // Replace with your actual Google Spreadsheet ID\n    table: 'Sheet1', // optional, default = Sheet1\n    keyFile: keyFilePath,\n    cacheTimeoutMs: 5000 // optional, default = 5000\n  });\n\n  // Load schema and data from google spreadsheet\n  await db.load();\n  console.log('Database loaded.');\n\n  // Insert multiple documents\n  let docs = await db.insert([\n    {\n      name: 'joway',\n      age: 18\n    },\n    {\n      name: 'alice',\n      age: 25\n    }\n  ]);\n  console.log('Inserted documents:', docs);\n\n  // Find documents and update them\n  docs = await db.update(\n    {\n      name: 'joway'\n    },\n    {\n      age: 100\n    }\n  );\n  console.log('Updated documents:', docs);\n\n  // Find documents\n  docs = await db.find({\n    name: 'joway'\n  });\n  console.log('Found documents:', docs);\n\n  // Find all documents\n  docs = await db.find({});\n  console.log('All documents:', docs);\n\n  // Find documents and remove them\n  docs = await db.remove({\n    name: 'alice'\n  });\n  console.log('Removed documents:', docs);\n};\n\nrunExample().catch(console.error);","lang":"typescript","description":"Demonstrates how to initialize a `Database` instance with a Google Service Account key, load data from a spreadsheet, and perform basic CRUD operations (insert, find, update, remove)."},"warnings":[{"fix":"Implement explicit type conversion logic in your application code (e.g., `parseInt(doc.age)`, `String(myNumber)`).","message":"Data retrieved from and written to Google Spreadsheets via sheetsql are always handled as strings. Users are responsible for explicitly converting data types (e.g., to numbers, booleans, dates) in their application code when reading, and ensuring data is correctly stringified when writing.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refer to the Google Cloud documentation for creating a Service Account and ensure the service account email has 'Editor' access to your Google Spreadsheet.","message":"Proper authentication with Google Sheets requires a correctly configured Google Cloud Service Account. This involves creating the service account, downloading its JSON key file, and crucially, sharing the target Google Spreadsheet with the service account's email address (with editor permissions). Misconfiguration in any of these steps will lead to authentication failures.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set environment variables like `HTTP_PROXY=http://your.proxy.com:8080` and, if necessary, `NO_PROXY=*` before running your application.","message":"sheetsql internally uses the `googleapis` library, which relies on standard `HTTP_PROXY`/`HTTPS_PROXY` environment variables for proxying requests. If only Google API requests need to be proxied, and other network requests in the application should bypass the proxy, users must explicitly set `NO_PROXY=*` to prevent unintended global proxying.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}