{"id":41992,"library":"spreadsheet-orm","title":"spreadsheet-orm","description":"spreadsheet-orm v1.0.4 is an ORM for Google Spreadsheets that provides a query builder and schema management layer, turning spreadsheets into database-like tables. It offers schema validation, relationship handling (hasOne/hasMany), and a fluent query builder. Actively maintained, it simplifies working with Google Sheets API by abstracting raw API calls. Differentiators include schema definitions, type-safe querying, and built-in data validation, unlike raw google-spreadsheet packages.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/codingbotPark/spreadsheet-orm","tags":["javascript","google-spreadsheet","spreadsheet-orm","spreadsheet-database","google-sheets-api","orm","database","query-builder","typescript"],"install":[{"cmd":"npm install spreadsheet-orm","lang":"bash","label":"npm"},{"cmd":"yarn add spreadsheet-orm","lang":"bash","label":"yarn"},{"cmd":"pnpm add spreadsheet-orm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for interacting with Google Sheets API","package":"google-spreadsheet","optional":false},{"reason":"Used for date handling and formatting","package":"moment","optional":true}],"imports":[{"note":"ESM-only since v1, no default export","wrong":"const SpreadsheetORM = require('spreadsheet-orm')","symbol":"SpreadsheetORM","correct":"import { SpreadsheetORM } from 'spreadsheet-orm'"},{"note":"Named export, not default","wrong":"import Schema from 'spreadsheet-orm'","symbol":"Schema","correct":"import { Schema } from 'spreadsheet-orm'"},{"note":"Main export, not a subpath","wrong":"import { QueryBuilder } from 'spreadsheet-orm/query'","symbol":"QueryBuilder","correct":"import { QueryBuilder } from 'spreadsheet-orm'"}],"quickstart":{"code":"import { SpreadsheetORM, Schema } from 'spreadsheet-orm';\n\nconst orm = new SpreadsheetORM({\n  credentials: JSON.parse(process.env.GOOGLE_CREDENTIALS ?? '{}'),\n  spreadsheetId: process.env.SPREADSHEET_ID ?? ''\n});\n\nconst userSchema = new Schema('users', {\n  id: { type: 'string', required: true },\n  name: { type: 'string', required: true },\n  email: { type: 'string' },\n  created_at: { type: 'date' }\n});\n\nconst userModel = orm.model(userSchema);\nconst users = await userModel.query().where('email', '!=', '').orderBy('created_at', 'desc').limit(10).get();\nconsole.log(users);","lang":"typescript","description":"Initialize ORM with Google credentials, define a schema, and run a query with filters and ordering."},"warnings":[{"fix":"Use 'credentials' object instead of 'auth'","message":"v1.0.0 changed the constructor signature: 'auth' option replaced by 'credentials'","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Replace rawQuery with query().raw()","message":"Method 'rawQuery' is deprecated in v1.0.3, use 'query().raw()' instead","severity":"deprecated","affected_versions":">=1.0.3"},{"fix":"Always use moment objects when setting dates, or format as ISO strings","message":"Date fields are stored as ISO strings, but moment objects are used internally. Ensure consistent date formatting","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Register all schemas before defining relationships","message":"Relationships (hasOne, hasMany) require the related schema to be registered before use","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid spaces in sheet names","message":"Worksheet names with spaces are not supported; internal naming uses underscores","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use named import { SpreadsheetORM }","message":"Before v1.0.0, the default export was a class. Now it's a named export","severity":"breaking","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'abstract':52 'activ':42 'api':50,54,89 'builder':18,41,94 'built':66 'built-in':65 'call':55 'data':68 'databas':27,85,91 'database-lik':26 'definit':59 'differenti':56 'fluent':39 'googl':12,48,73,78,87 'google-sheets-api':86 'google-spreadsheet':72,77 'handl':35 'hasone/hasmany':36 'includ':57 'javascript':76 'layer':22 'like':28 'maintain':43 'manag':21 'offer':31 'orm':3,6,10,82,90 'packag':75 'provid':15 'queri':17,40,63,93 'query-build':92 'raw':53,71 'relationship':34 'safe':62 'schema':20,32,58 'sheet':49,88 'simplifi':45 'spreadsheet':2,5,13,24,74,79,81,84 'spreadsheet-databas':83 'spreadsheet-orm':1,4,80 'tabl':29 'turn':23 'type':61 'type-saf':60 'typescript':95 'unlik':70 'v1.0.4':7 'valid':33,69 'work':46","created_at":"2026-06-04T18:55:06.155114+00:00","updated_at":"2026-06-04T18:55:06.155114+00:00","problems":[{"fix":"Set GOOGLE_CREDENTIALS environment variable with JSON object containing type, project_id, private_key, client_email","cause":"No Google service account credentials provided","error":"Error: Missing credentials. Provide credentials option."},{"fix":"Use import { Schema } from 'spreadsheet-orm'","cause":"Using default import instead of named import for Schema","error":"TypeError: schema_1.Schema is not a constructor"},{"fix":"Use import { SpreadsheetORM } from 'spreadsheet-orm' or enable ESM in your project","cause":"Using CommonJS require with ESM-only package","error":"SpreadsheetORM is not defined"},{"fix":"Ensure spreadsheet has a sheet named exactly as the schema name","cause":"Sheet title mismatch: schema name must match sheet title exactly","error":"Error: Worksheet \"users\" not found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/codingbotPark/spreadsheet-orm","github":"https://github.com/codingbotPark/spreadsheet-orm","docs":null,"changelog":null,"pypi":null,"npm":"spreadsheet-orm","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}