{"id":21340991,"url":"https://github.com/yavin-dev/gsheet-jdbc","last_synced_at":"2025-07-12T14:33:40.437Z","repository":{"id":43332763,"uuid":"437932041","full_name":"yavin-dev/gsheet-jdbc","owner":"yavin-dev","description":null,"archived":false,"fork":false,"pushed_at":"2022-03-07T19:57:03.000Z","size":88,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2023-07-03T13:07:38.333Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yavin-dev.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"Code-Of-Conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-13T15:48:27.000Z","updated_at":"2023-05-10T01:52:28.000Z","dependencies_parsed_at":"2022-09-21T00:52:11.039Z","dependency_job_id":null,"html_url":"https://github.com/yavin-dev/gsheet-jdbc","commit_stats":null,"previous_names":[],"tags_count":8,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yavin-dev%2Fgsheet-jdbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yavin-dev%2Fgsheet-jdbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yavin-dev%2Fgsheet-jdbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yavin-dev%2Fgsheet-jdbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yavin-dev","download_url":"https://codeload.github.com/yavin-dev/gsheet-jdbc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225824809,"owners_count":17529906,"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":[],"created_at":"2024-11-22T00:54:20.536Z","updated_at":"2024-11-22T00:54:22.905Z","avatar_url":"https://github.com/yavin-dev.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gsheet-jdbc\n\n\u003e Connect to any Google Spreadsheet with JDBC\n\n[![Coverage Status](https://coveralls.io/repos/github/yavin-dev/gsheet-jdbc/badge.svg?branch=main)](https://coveralls.io/github/yavin-dev/gsheet-jdbc?branch=main)\n\n## Table of Contents\n\n- [Background](#background)\n- [Overview](#how-it-works)\n- [Usage](#usage)\n- [JDBC URL Format](#jdbc-url-format)\n- [Authentication](#authentication)\n- [Table Schemas](#database-table-schemas)\n- [SQL Queries](#sql-queries)\n- [Contribute](#contribute)\n- [License](#license)\n\n## Background\n\ngsheet-jdbc is a Java JDBC driver that turns any Google Spreadsheet into a read-only database.\n\n## How It Works\n\nWhen a client program creates an intitial JDBC connection, gsheet-jdbc will download one or more sheets contained within a Google spreadsheet document, [infer the database schema](#database-table-schemas) (column names and types), and copy the data into an [H2 inmemory database](https://www.h2database.com/html/main.html).  H2 provides the heavy lifting for handling subsequent SQL queries.\n\nSubsequent connections will continue to leverage the existing database unless the contents become stale (detected by querying the last modification datestamp of the spreadsheet document). \n\nBy copying the data into an in-memory database, the driver reduces the risk of running into any rate limits on the Google Sheet or Drive APIs.  Most connections will incur minimal delay as the data is already cached locally.   THe primary downside is the cost of refreshing the data on the first connection or whenever the data becomes stale.  This process maintains an exclusive lock on the Driver to ensure consistency (at the cost of extra latency when these events occur).\n\n## Usage\n\nInstall the following package:\n\nTBD.\n\n## JDBC URL Format\n\nThe JDBC URL encoding allows developers to specify one or multiple sheets and corresponding properties including:\n1. The Google document ID\n2. The sheet name and range of cells to load\n\nIn addition, the URL can specify the database schema to place the tables under.\n\nThe format is:\n\n```\njdbc:gsheet://doc=(id={{GOOGLE_DOCUMENT_ID1}},range={{SHEET_NAME_AND_RANGE}}),doc=(id={{GOOGLE_DOCUMENT_ID2,range={{SHEET_NAME_AND_RANGE}})/{{DATABASE_SCHEMA}}\n```\n\nBoth the document ID and range formats are provided by Google.  A valid range consists of:\n1. A sheet name \n2. Followed by a `!` separator character \n3. Followed by the column and number of the upper left cell\n4. Followed by a `:` separator character\n5. Followed by the column and number of the lower right cell\n\nFor example, the following URL loads two sheets:\n\n```\njdbc:gsheet://doc=(id=abcdefg,range=Sheet1!A1:G11),doc=(id=xyz123,range=Sheet2!A1:G11)/MySchema\n```\nThe first sheet has\n1. A document ID `abcdefg`,\n2. A sheet name `Sheet1`\n3. A cell range from `A1` to `G11`\n\nBoth sheets are loaded as `Sheet1` \u0026 `Sheet2` tables into the database schema `MySchema`.\n\n## Authentication\n\nThe driver looks for an environment variable, `GSHEET_JDBC_CREDENTIALS`, containing the contents of a Google service account credentials JSON file.\n\nThe service account must be setup with `VIEW ACCESS` in a project with both the google sheet and google drive APIs enabled.  The Google drive API is required to fetch document timestamps to determine data freshness.\n\nEach document must be shared with the IAM email address of the service account so the driver can read the file contents.\n\n## Database Table Schemas\n\nThe first row of the range provided in the JDBC URL must contain the column headers or names for each column.  These names will be mapped to physical columns names in the H2 database.  Column names are restricted\nto 256 alphanumeric (ASCII) characters, space, hyphen, and underscore.  \n\nColumn types are derived from the format (explicit or implied) of cells in the first data row.  Supported column types include:\n- **Text** - The default format if none is applied.  It maps to `VARCHAR` in the database.\n- **Number** - For numeric, non-date columns.  It maps to `DOUBLE` in the database.\n- **Date** - For calendar days.  It maps to `DATE` in the database.\n- **Datetime** - For calendar days plus time to milliseconds.  It maps to `TIMESTAMP` in the database.\n- **Boolean** - For true/false columns.  It maps to `BOOLEAN` in the database.\n\nNo foreign keys, primary keys, or indices are created.\n\n## SQL Queries\n\nMake sure you double quote (`\"`) the schema, table, and column names in your queries.  The table must be prefixed by the schema name in SQL queries:\n\n```sql\nSelect * from \\\"MySchema\\\".\\\"Class Data\\\" WHERE \\\"Student Name\\\"='Alexandra' LIMIT 1;\n```\n\nQueries leverage the [H2 database](https://github.com/h2database/h2database) dialect.\n\n## Contribute\nPlease refer to [the contributing.md file](CONTRIBUTING.md) for information about how to get involved. We welcome issues, questions, and pull requests.\n\nCommunity chat is now on [discord](https://discord.gg/ApvtW5YU)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyavin-dev%2Fgsheet-jdbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyavin-dev%2Fgsheet-jdbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyavin-dev%2Fgsheet-jdbc/lists"}