spreadsheet-db

1.3 verified Sat May 09 auth: no python

A lightweight Python library that uses Google Sheets as a database. Currently at version 1.3, with no regular release cadence.

pip install spreadsheet-db

Common errors

error gspread.exceptions.APIError: {'code': 403, 'message': 'Google Sheets API has not been used in project ...'} ↓

cause The Google Sheets API is not enabled for the Google Cloud project.

fix

Enable the Google Sheets API via the Google Cloud Console under APIs & Services.

error AttributeError: 'SpreadsheetDB' object has no attribute 'insert' ↓

cause The version of spreadsheet-db may be outdated or installed incorrectly.

fix

Run 'pip install --upgrade spreadsheet-db' to get the latest version.

error oauth2client.client.HttpAccessTokenRefreshError: invalid_grant ↓

cause The service account key file is missing, expired, or not properly configured.

fix

Ensure the credentials file path is correct and the service account has access to the sheet.

Warnings

gotcha The library expects a Google Sheets document with the first row as headers. Inserting a row without a header column will raise an error. ↓

fix Ensure your sheet has headers in the first row matching the dictionary keys you intend to insert.

gotcha The select() method returns all matching rows as lists, not dictionaries, and ordering is not guaranteed. ↓

fix Use the returned rows with column index from headers. For dictionary format, iterate over headers manually.

deprecated The library uses gspread's ServiceAccountCredentials, which is deprecated in favor of google-auth directly. ↓

fix Use google.oauth2.service_account.Credentials instead of gspread's ServiceAccountCredentials.

Imports

SpreadsheetDB

from spreadsheet_db import SpreadsheetDB

Main class to use.

Quickstart

Initialize with credentials and use insert/select like a database.

from google.oauth2.service_account import Credentials
from spreadsheet_db import SpreadsheetDB
import os

creds = Credentials.from_service_account_file(
    os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', 'credentials.json')
)
db = SpreadsheetDB('MySheet', credentials=creds)
db.insert({'name': 'Alice', 'age': 30})
result = db.select({'name': 'Alice'})
print(result)