# goshdb
GOogle SHeets DataBase - Python client to key-value database based on Google Sheets
Sheet works as a table and has the following look & structure:
<img src="https://github.com/artoby/goshdb/assets/6637041/cf3ba5d4-e1df-42ff-8487-3f18a27190fd" width="300">
# Use cases
- Store configuration with ability to change it on the fly
- Store data that should be shared between multiple users / machines
- Write status of a long-running process and observe it in real-time in Google Sheets
- Review data modification history in Google Sheets UI (File -> Version history -> See version history)
Features
- Simple key-value interface (get/set string/object)
Advantages
- Free storage (Google Sheets API has free quota)
- Concurrent read (Supports parallel read from multiple clients)
- No need to create a server
- User-friendly Google Sheets UI for data review & modification
- No need to install any software on the client side (only Python)
- Simple get/set methods instead of SQL queries
- No need to create a database schema (just create a new sheet)
- Data backup, synchronization, availability, and security are managed by Google Sheets
Limitations
- Not suitable for high-frequency read/write operations (Google Sheets API has read/write quota:
300/minute per project, 60/minute per user per project)
- Not suitable for concurrent write (Google Sheets API has no locking mechanism)
- Not suitable for very large data (Google Sheets has a limit of 10 million cells per spreadsheet,
i.e. 5 million key-value pairs
- Not suitable for high-speed data access (Google Sheets API has a delay, takes ~0.3-1 second per
get/set operation)
- Not suitable for complex queries, types, data structures, relations, validation and indexing
(only key-value interface)
- Not suitable for sensitive & high-security data (Google Sheets API has access to all
spreadsheets in the account)
# Installation
```bash
pip install goshdb
```
# Configuration
#### Step 1. Select a Google account that will be used to access the spreadsheet
<details>
<summary>Details</summary>
* Though `Table` uses only provided spreadsheet, credentials technically
allow to read/write all the spreadsheets in the account.
* So it's recommended to use `Table` with a special service (non-personal)
account that doesn't have critical/secret spreadsheets that might be compromised.
</details>
#### Step 2. Create a spreadsheet in your Google Sheets account.
<details>
<summary>Details</summary>
* You should share the spreadsheet and provide write access to the account that will be used to
access it (see Step 1).
</details>
#### Step 3. Obtain credentials.json file with this the [instruction](https://developers.google.com/sheets/api/quickstart/python)
<details>
<summary>Details</summary>
* If you do this for the first time - take `credentials.json` and put it in `secret_dir`.
* On a first attempt to create `Table` it'll open a browser window, ask you to sign in
the target test account.
* Then the `token.json` file will be generated automatically and put in `secret_dir`.
* The `token.json` file will be used automatically for further access to the
target spreadsheet.
* You can use `token.json` to access the spreadsheet from another machine without completing the
steps above
</details>
# Usage
```python
from goshdb import Table
from pathlib import Path
# Take spreadsheet ID from your spreadsheet URL:
# https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit#gid=0
SPREADSHEET_ID = '...'
# Provide a sheet name. It should be either new sheet or existing one that follows the required structure.
SHEET_NAME = '...'
# Create a Table object. If you do this for the first time - it'll open a browser window (see Step 3 details)
table = Table(
secret_dir=Path('path/to/secret_dir'),
spreadsheet_id=SPREADSHEET_ID,
sheet_name=SHEET_NAME
)
# Write a key-value pair
table.set_string('city', 'London')
print(table.get_string('city')) # London
table.set_object('person_1', {'name': 'John', 'age': 30})
print(table.get_object('person_1')) # {'name': 'John', 'age': 30}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/artoby/goshdb",
"name": "goshdb",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.11,>=3.10",
"maintainer_email": null,
"keywords": "google, sheets, spreadsheet, database, key-value, free, nosql",
"author": "Artyom Vorobyov",
"author_email": "artyom.vorobyov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/ac/3157baacd3bafb8d830665e585db481cbce0d8dc24a2e73f20e7f5a4e894/goshdb-0.2.1.tar.gz",
"platform": null,
"description": "# goshdb\nGOogle SHeets DataBase - Python client to key-value database based on Google Sheets\n\nSheet works as a table and has the following look & structure:\n\n<img src=\"https://github.com/artoby/goshdb/assets/6637041/cf3ba5d4-e1df-42ff-8487-3f18a27190fd\" width=\"300\">\n\n\n# Use cases\n- Store configuration with ability to change it on the fly\n- Store data that should be shared between multiple users / machines\n- Write status of a long-running process and observe it in real-time in Google Sheets\n- Review data modification history in Google Sheets UI (File -> Version history -> See version history)\n\nFeatures\n- Simple key-value interface (get/set string/object)\n\nAdvantages\n- Free storage (Google Sheets API has free quota)\n- Concurrent read (Supports parallel read from multiple clients)\n- No need to create a server\n- User-friendly Google Sheets UI for data review & modification\n- No need to install any software on the client side (only Python)\n- Simple get/set methods instead of SQL queries\n- No need to create a database schema (just create a new sheet)\n- Data backup, synchronization, availability, and security are managed by Google Sheets\n\nLimitations\n- Not suitable for high-frequency read/write operations (Google Sheets API has read/write quota: \n300/minute per project, 60/minute per user per project)\n- Not suitable for concurrent write (Google Sheets API has no locking mechanism)\n- Not suitable for very large data (Google Sheets has a limit of 10 million cells per spreadsheet, \ni.e. 5 million key-value pairs\n- Not suitable for high-speed data access (Google Sheets API has a delay, takes ~0.3-1 second per \nget/set operation)\n- Not suitable for complex queries, types, data structures, relations, validation and indexing \n(only key-value interface)\n- Not suitable for sensitive & high-security data (Google Sheets API has access to all \nspreadsheets in the account)\n\n# Installation\n```bash\npip install goshdb\n```\n\n# Configuration\n\n#### Step 1. Select a Google account that will be used to access the spreadsheet\n\n<details>\n<summary>Details</summary>\n\n* Though `Table` uses only provided spreadsheet, credentials technically \nallow to read/write all the spreadsheets in the account.\n* So it's recommended to use `Table` with a special service (non-personal)\naccount that doesn't have critical/secret spreadsheets that might be compromised.\n\n</details>\n\n#### Step 2. Create a spreadsheet in your Google Sheets account.\n\n<details>\n<summary>Details</summary>\n\n* You should share the spreadsheet and provide write access to the account that will be used to \naccess it (see Step 1).\n\n</details>\n\n#### Step 3. Obtain credentials.json file with this the [instruction](https://developers.google.com/sheets/api/quickstart/python)\n\n<details>\n<summary>Details</summary>\n\n* If you do this for the first time - take `credentials.json` and put it in `secret_dir`.\n* On a first attempt to create `Table` it'll open a browser window, ask you to sign in \nthe target test account.\n* Then the `token.json` file will be generated automatically and put in `secret_dir`.\n* The `token.json` file will be used automatically for further access to the\ntarget spreadsheet.\n* You can use `token.json` to access the spreadsheet from another machine without completing the \nsteps above\n\n</details>\n\n\n# Usage\n```python\nfrom goshdb import Table\nfrom pathlib import Path\n\n# Take spreadsheet ID from your spreadsheet URL:\n# https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit#gid=0\nSPREADSHEET_ID = '...'\n# Provide a sheet name. It should be either new sheet or existing one that follows the required structure.\nSHEET_NAME = '...' \n\n\n# Create a Table object. If you do this for the first time - it'll open a browser window (see Step 3 details)\ntable = Table(\n secret_dir=Path('path/to/secret_dir'),\n spreadsheet_id=SPREADSHEET_ID,\n sheet_name=SHEET_NAME\n)\n\n# Write a key-value pair\ntable.set_string('city', 'London')\nprint(table.get_string('city')) # London\ntable.set_object('person_1', {'name': 'John', 'age': 30})\nprint(table.get_object('person_1')) # {'name': 'John', 'age': 30}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "GOogle SHeets DataBase - Python client to key-value database based on Google Sheets",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/artoby/goshdb",
"Repository": "https://github.com/artoby/goshdb"
},
"split_keywords": [
"google",
" sheets",
" spreadsheet",
" database",
" key-value",
" free",
" nosql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "750abd5eac15842eedd96682471abfd775f36c8fd736164c77b578b63f9d0d41",
"md5": "9f53184cc4b5eff5b33ba559f0501fd3",
"sha256": "e3240960dcc282183c353300dfe5e808bc78af59dd34dd9dd23be5bbe50b1364"
},
"downloads": -1,
"filename": "goshdb-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f53184cc4b5eff5b33ba559f0501fd3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.11,>=3.10",
"size": 8340,
"upload_time": "2024-05-10T10:53:03",
"upload_time_iso_8601": "2024-05-10T10:53:03.158041Z",
"url": "https://files.pythonhosted.org/packages/75/0a/bd5eac15842eedd96682471abfd775f36c8fd736164c77b578b63f9d0d41/goshdb-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "40ac3157baacd3bafb8d830665e585db481cbce0d8dc24a2e73f20e7f5a4e894",
"md5": "1b399ac9fc42159e7d9643bfd37d99c8",
"sha256": "0dd7376c0c9d68c53bbe4585b7d6c3080d36d061367f8fa63e5713acc13098cd"
},
"downloads": -1,
"filename": "goshdb-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "1b399ac9fc42159e7d9643bfd37d99c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.11,>=3.10",
"size": 7156,
"upload_time": "2024-05-10T10:53:04",
"upload_time_iso_8601": "2024-05-10T10:53:04.958836Z",
"url": "https://files.pythonhosted.org/packages/40/ac/3157baacd3bafb8d830665e585db481cbce0d8dc24a2e73f20e7f5a4e894/goshdb-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-10 10:53:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "artoby",
"github_project": "goshdb",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "goshdb"
}
JSON
