PHPackages                             amazingbv/laravel-google-sheets-database-driver - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. amazingbv/laravel-google-sheets-database-driver

ActiveLibrary[Database & ORM](/categories/database)

amazingbv/laravel-google-sheets-database-driver
===============================================

Laravel database driver that treats a Google Sheets spreadsheet as a database.

1.0.0(1mo ago)61↑2900%MITPHPPHP ^8.2CI passing

Since Apr 7Pushed 1mo agoCompare

[ Source](https://github.com/AmazingBV/laravel-google-sheets-database-driver)[ Packagist](https://packagist.org/packages/amazingbv/laravel-google-sheets-database-driver)[ RSS](/packages/amazingbv-laravel-google-sheets-database-driver/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (6)Versions (2)Used By (0)

[![Laravel Google Sheets Database Driver header](assets/header.png)](assets/header.png)

Laravel Google Sheets Database Driver
=====================================

[](#laravel-google-sheets-database-driver)

[![Latest Version on Packagist](https://camo.githubusercontent.com/c7045bac62e6c68cef218869aa5388ebbb047b3fa3d7c68ecfc753f26a91ebb5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d617a696e6762762f6c61726176656c2d676f6f676c652d7368656574732d64617461626173652d6472697665722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/amazingbv/laravel-google-sheets-database-driver)[![Tests](https://camo.githubusercontent.com/76d48ed47340184f09aabe1e31437783d9242f0fb3733fb37c4b6af5f97223fe/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616d617a696e6762762f6c61726176656c2d676f6f676c652d7368656574732d64617461626173652d6472697665722f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d5465737473267374796c653d666c61742d737175617265)](https://github.com/amazingbv/laravel-google-sheets-database-driver/actions/workflows/tests.yml)[![Downloads](https://camo.githubusercontent.com/9537abff9cb35bec41a881260092453662f0ac5c3eb5635e059d2a9573559af7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d617a696e6762762f6c61726176656c2d676f6f676c652d7368656574732d64617461626173652d6472697665722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/amazingbv/laravel-google-sheets-database-driver)[![License: MIT](https://camo.githubusercontent.com/1b01ef0024ba0866c115986b895301f657c1b21fc29f05c4844b7f2e8d89204d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e7376673f7374796c653d666c61742d737175617265)](LICENSE)

A Laravel database driver that uses a Google Sheets spreadsheet as its backing store.

This package lets you treat:

- one spreadsheet as a database
- each tab as a table
- the first row as the column definition

It is designed for lightweight back-office data, prototypes, operational tools, and integrations where a spreadsheet is more practical than a traditional database.

Features
--------

[](#features)

- Custom Laravel connection: `google-sheets`
- Works with `DB`, Eloquent, `Schema`, and migrations
- Keeps a visible `Database Index` tab as the first tab in the spreadsheet
- Ignores schema indexes and constraints during migrations instead of hard-failing
- Uses a hidden schema sheet and hidden migration sheet internally
- Handles Google Sheets API quotas with throttling, retries, and in-process caching
- Auto-heals common metadata drift when tabs are removed manually

Requirements
------------

[](#requirements)

- PHP `^8.2`
- Laravel `12` or `13`
- A Google Cloud project with the Google Sheets API enabled
- A Google service account with a downloaded JSON key
- A spreadsheet shared with that service account

Installation
------------

[](#installation)

```
composer require amazingbv/laravel-google-sheets-database-driver
```

Laravel package discovery is enabled automatically.

Quick Start
-----------

[](#quick-start)

Add the following to your `.env`:

```
DB_CONNECTION=google-sheets
DB_DATABASE=your-google-spreadsheet-id
GOOGLE_SHEETS_CREDENTIALS_PATH=/absolute/path/to/service-account.json

GOOGLE_SHEETS_CACHE_STORE=file
GOOGLE_SHEETS_CACHE_TTL=60

GOOGLE_SHEETS_QUOTA_RETRY_ATTEMPTS=5
GOOGLE_SHEETS_QUOTA_RETRY_BASE_DELAY_MS=1000
GOOGLE_SHEETS_QUOTA_RETRY_MAX_DELAY_MS=10000
GOOGLE_SHEETS_READ_REQUESTS_PER_MINUTE=50
GOOGLE_SHEETS_WRITE_REQUESTS_PER_MINUTE=45
```

Then run:

```
php artisan sheets:install
php artisan migrate --database=google-sheets
```

How It Maps To Google Sheets
----------------------------

[](#how-it-maps-to-google-sheets)

- Spreadsheet = database
- Tab = table
- Row 1 = column names
- Rows 2+ = records

The package also manages:

- `Database Index` as a visible first tab with links to the table tabs
- `__sheetsdbal_schema` as a hidden internal schema tab
- `__sheetsdbal_migrations` as a hidden internal migration-log tab

Service Account Setup
---------------------

[](#service-account-setup)

This package uses a Google service account for server-to-server access.

The JSON file referenced by `GOOGLE_SHEETS_CREDENTIALS_PATH` is the service account key file downloaded from Google Cloud. The package uses that file to authenticate against the Google Sheets API.

In practice:

1. Create or choose a Google Cloud project.
2. Enable the Google Sheets API for that project.
3. Create a service account.
4. Create and download a JSON key for that service account.
5. Share your spreadsheet with the `client_email` from that JSON file, usually as `Editor`.
6. Store the JSON file outside your repository and point `GOOGLE_SHEETS_CREDENTIALS_PATH` to it.

Useful official Google documentation:

- [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create)
- [Best practices for managing service account keys](https://docs.cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys)
- [Google Sheets API quickstart](https://developers.google.com/workspace/sheets/api/quickstart/go)

Notes:

- The `client_email` inside the JSON is the identity you share the spreadsheet with.
- Do not commit the JSON key file to Git.
- Rotate keys if a file is exposed or replaced.

Usage
-----

[](#usage)

### Query Builder

[](#query-builder)

```
use Illuminate\Support\Facades\DB;

$users = DB::connection('google-sheets')
    ->table('users')
    ->where('active', true)
    ->orderBy('name')
    ->get();
```

### Eloquent

[](#eloquent)

```
class Contact extends Model
{
    protected $connection = 'google-sheets';
    protected $table = 'contacts';
    protected $guarded = [];
}
```

### Schema

[](#schema)

```
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::connection('google-sheets')->create('products', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->integer('price');
    $table->timestamps();
});
```

Supported Query Subset
----------------------

[](#supported-query-subset)

The driver intentionally supports a practical subset instead of full SQL compatibility.

Supported:

- `select`
- `where`, `orWhere`
- `whereIn`, `whereNotIn`
- `whereNull`, `whereNotNull`
- `whereLike`
- `orderBy`
- `limit`, `offset`
- `first`, `find`, `get`, `pluck`
- `count`, `min`, `max`, `avg`, `sum`
- `insert`, `insertGetId`, `update`, `delete`
- simple in-memory `inner join`

Unsupported:

- raw SQL
- unions
- grouped queries / `groupBy` / `having`
- database-native transaction guarantees

Migrations And Schema Behavior
------------------------------

[](#migrations-and-schema-behavior)

This package tries to be migration-friendly for standard Laravel apps.

What it does:

- runs normal table creation migrations against Google Sheets
- ignores indexes and relational constraints instead of failing migrations
- keeps internal schema metadata in sync
- removes stale metadata and stale create-table migration entries when tabs were deleted manually

What it does not do:

- enforce unique constraints
- enforce foreign keys
- provide true relational integrity

So if your migration contains:

- `->unique()`
- `->index()`
- `->primary()`
- `->foreignId()->constrained()`

the migration can still run, but Google Sheets will not enforce those guarantees.

Transactions
------------

[](#transactions)

Laravel transaction calls are treated as no-op control flow.

That means:

- queue workers and framework internals will not crash when they call `transaction()`
- nested transaction bookkeeping still behaves sanely for Laravel
- there is no atomic commit/rollback guarantee

Quota Handling
--------------

[](#quota-handling)

Google Sheets has strict API quotas. This driver includes a few protections:

- reuses sheet-directory and sheet-value reads within one connection
- throttles read and write requests per minute in the current PHP process
- retries quota-style failures with exponential backoff
- uses a configurable Laravel cache store for additional reduction in API traffic

If you still hit quotas:

- lower `GOOGLE_SHEETS_READ_REQUESTS_PER_MINUTE`
- lower `GOOGLE_SHEETS_WRITE_REQUESTS_PER_MINUTE`
- use `GOOGLE_SHEETS_CACHE_STORE=file` or `redis`
- avoid very large migration batches and write-heavy loops

Database Index Tab
------------------

[](#database-index-tab)

The package maintains a visible first tab named `Database Index`.

It contains:

- a formatted title in cell `A1`
- one row per table tab underneath
- clickable links to the actual tabs

This makes the spreadsheet easier to use as a navigable “database”.

Operational Notes
-----------------

[](#operational-notes)

- Manually editing data is supported, but changing headers or deleting tabs can invalidate metadata
- If you remove tabs manually, rerun `php artisan sheets:install` or `php artisan migrate`
- Hidden package-managed tabs should generally be left alone
- This package is best suited for small datasets and low write concurrency

Local Development With A Path Repository
----------------------------------------

[](#local-development-with-a-path-repository)

If you want to test this package from a local checkout in another Laravel app:

```
{
  "repositories": [
    {
      "type": "path",
      "url": "/absolute/path/to/this/package",
      "options": {
        "symlink": true
      }
    }
  ],
  "require": {
    "amazingbv/laravel-google-sheets-database-driver": "^1.0"
  }
}
```

Then run:

```
composer update amazingbv/laravel-google-sheets-database-driver
php artisan optimize:clear
```

Limits
------

[](#limits)

This is not a replacement for MySQL or PostgreSQL.

Use it when:

- the spreadsheet itself is part of the workflow
- non-technical users need direct visibility
- the dataset is relatively small
- strong relational guarantees are not required

Do not use it when:

- you need high write throughput
- you need strict transactions
- you need database-level constraints
- you need efficient large-scale querying

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance94

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c1ae3b30deb77936e065a4a37de1be603814e578d29902afac339ce514099dd3?d=identicon)[AmazingBV](/maintainers/AmazingBV)

---

Top Contributors

[![marcopetersamazing](https://avatars.githubusercontent.com/u/26324203?v=4)](https://github.com/marcopetersamazing "marcopetersamazing (12 commits)")

---

Tags

databasedbalgoogle-sheetslaravellaraveldatabasedbalgoogle-sheets

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/amazingbv-laravel-google-sheets-database-driver/health.svg)

```
[![Health](https://phpackages.com/badges/amazingbv-laravel-google-sheets-database-driver/health.svg)](https://phpackages.com/packages/amazingbv-laravel-google-sheets-database-driver)
```

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k7.2M71](/packages/mongodb-laravel-mongodb)[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[spiritix/lada-cache

A Redis based, automated and scalable database caching layer for Laravel

591444.8k2](/packages/spiritix-lada-cache)[clickbar/laravel-magellan

This package provides functionality for working with the postgis extension in Laravel.

423715.4k1](/packages/clickbar-laravel-magellan)[pdphilip/elasticsearch

An Elasticsearch implementation of Laravel's Eloquent ORM

145360.2k4](/packages/pdphilip-elasticsearch)[cybercog/laravel-clickhouse

ClickHouse migrations for Laravel

163166.8k](/packages/cybercog-laravel-clickhouse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)