PHPackages                             tixby/databricks-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. tixby/databricks-driver

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

tixby/databricks-driver
=======================

Laravel Eloquent database driver for Databricks SQL warehouses via the Statement Execution API

v0.1.3(1mo ago)13MITPHPPHP ^8.2

Since Jul 14Pushed 1mo agoCompare

[ Source](https://github.com/TiX-By/databricks-driver)[ Packagist](https://packagist.org/packages/tixby/databricks-driver)[ RSS](/packages/tixby-databricks-driver/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (12)Versions (5)Used By (0)

Laravel Databricks Driver
=========================

[](#laravel-databricks-driver)

A Laravel database driver for **Databricks SQL warehouses**. It plugs Databricks into Eloquent and the Query Builder as a first-class connection — no PDO, no ODBC, no native extensions. All communication happens over the [Databricks SQL Statement Execution REST API](https://docs.databricks.com/api/workspace/statementexecution) using Laravel's `Http` client, so it deploys anywhere plain PHP over HTTPS works (containers, serverless, shared hosting, Vapor).

```
$events = DB::connection('databricks')
    ->table('vivenu.silver_mvp.dim_event')
    ->where('status', 'active')
    ->orderByDesc('start_date')
    ->limit(20)
    ->get();
```

Features
--------

[](#features)

- **Zero native dependencies** — pure PHP over HTTPS. No Simba/ODBC driver installs, no `ext-odbc`, no PDO.
- **Full read support** — raw SQL, Query Builder, and Eloquent models against Unity Catalog tables, including 3-part `catalog.schema.table` names.
- **Parameterized queries** — Laravel's `?` bindings are converted to the API's typed named parameters (no string interpolation, safe against SQL injection).
- **Typed results** — rows are hydrated into `stdClass` objects with proper PHP types based on the warehouse's column manifest (`INT` → `int`, `DOUBLE` → `float`, `BOOLEAN` → `bool`).
- **Precision-safe money** — `DECIMAL` values are deliberately kept as strings so financial data never loses cents to float rounding.
- **Large result sets** — multi-chunk results are fetched transparently; `cursor()` streams chunks lazily so memory stays flat. Results over the 25 MiB inline cap can use `EXTERNAL_LINKS` disposition instead.
- **Read-only by default** — write statements are rejected *before any HTTP request leaves your machine* unless you explicitly opt in.
- **Resilient polling** — long-running statements are polled with backoff; 429/5xx responses are tolerated; statements that exceed your deadline are canceled server-side.
- **Honest failure modes** — unsupported operations (transactions, upserts, locks, schema builder) throw loud exceptions instead of silently doing the wrong thing.

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

[](#requirements)

RequirementVersionPHP^8.2Laravel (illuminate/database)^11.0 || ^12.0DatabricksAny workspace with a [SQL warehouse](https://docs.databricks.com/en/compute/sql-warehouse/index.html)Installation
------------

[](#installation)

### Step 1 — Require the package

[](#step-1--require-the-package)

If the package is available on Packagist:

```
composer require tixby/databricks-driver
```

Or install straight from GitHub by adding the repository to your application's `composer.json` first:

```
{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/TiX-By/databricks-driver" }
    ]
}
```

```
composer require tixby/databricks-driver:^0.1
```

The service provider is registered automatically via Laravel package discovery — there is nothing to add to `config/app.php`.

### Step 2 — Gather your Databricks credentials

[](#step-2--gather-your-databricks-credentials)

You need three values from your Databricks workspace:

1. **Workspace host** — the base URL of your workspace, e.g. `https://dbc-a1b2c3d4-e5f6.cloud.databricks.com`. Copy it from your browser's address bar (no trailing slash needed; it is normalized either way).
2. **Personal access token (PAT)** — in Databricks go to **Settings → Developer → Access tokens → Generate new token**. Copy the token (it starts with `dapi...`). *(OAuth machine-to-machine auth is not yet supported.)*
3. **SQL warehouse ID** — go to **SQL Warehouses**, open your warehouse, and copy the **ID** from the **Connection details** tab (it also appears in the URL: `/sql/warehouses/`).

### Step 3 — Add the environment variables

[](#step-3--add-the-environment-variables)

In your application's `.env`:

```
DATABRICKS_HOST=https://dbc-a1b2c3d4-e5f6.cloud.databricks.com
DATABRICKS_TOKEN=dapiXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DATABRICKS_WAREHOUSE_ID=1234567890abcdef
DATABRICKS_CATALOG=main
DATABRICKS_SCHEMA=default
```

### Step 4 — Register the connection

[](#step-4--register-the-connection)

Add a `databricks` connection to the `connections` array in `config/database.php`:

```
'connections' => [

    // ... your existing connections ...

    'databricks' => [
        'driver' => 'databricks',
        'host' => env('DATABRICKS_HOST'),
        'token' => env('DATABRICKS_TOKEN'),
        'warehouse_id' => env('DATABRICKS_WAREHOUSE_ID'),

        // Optional: default namespace applied to unqualified table names in raw SQL.
        'catalog' => env('DATABRICKS_CATALOG'),
        'schema' => env('DATABRICKS_SCHEMA'),

        // Optional tuning — the values below are the defaults.
        'wait_timeout' => 50,             // seconds the API holds the initial request open (0, or 5–50)
        'max_execution_seconds' => 300,   // total deadline before the statement is canceled
        'row_limit' => 100000,            // server-side cap on returned rows (0/null = no cap)
        'strict_truncation' => true,      // throw (true) or log a warning (false) when results are truncated
        'read_only' => true,              // reject INSERT/UPDATE/DELETE/DDL before any HTTP call
        'disposition' => env('DATABRICKS_DISPOSITION', 'INLINE'), // or 'EXTERNAL_LINKS' for results >25 MiB
    ],
],
```

`host`, `token`, and `warehouse_id` are required — the connection throws immediately if any is missing.

### Step 5 — Verify the connection

[](#step-5--verify-the-connection)

```
php artisan tinker
```

```
DB::connection('databricks')->selectOne('SELECT current_catalog() AS catalog, current_timestamp() AS now');
// => {#... +"catalog": "main", +"now": "2026-07-14 12:34:56.789"}
```

If this returns a row, you are connected. Common failures at this step:

- `The databricks connection requires a 'host' config value.` — an env var is missing or the config cache is stale (`php artisan config:clear`).
- `Could not reach the Databricks workspace` — the host URL is wrong or unreachable from your network.
- A 403 message from the API — the token is invalid, expired, or lacks access to the warehouse.

Usage
-----

[](#usage)

### Raw queries

[](#raw-queries)

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

// Multiple rows
$rows = DB::connection('databricks')->select(
    'SELECT event_id, name, start_date FROM main.analytics.dim_event WHERE start_date >= ?',
    [now()->startOfYear()]
);

// Single row
$row = DB::connection('databricks')->selectOne(
    'SELECT count(*) AS total FROM main.analytics.fact_sales'
);
echo $row->total; // int

// Scalar
$total = DB::connection('databricks')->scalar(
    'SELECT sum(amount) FROM main.analytics.fact_sales WHERE sale_date = ?',
    ['2026-07-14']
);
```

### Query Builder

[](#query-builder)

Everything read-oriented in the Query Builder works: wheres, joins, aggregates, grouping, ordering, limits, unions, subqueries.

```
$db = DB::connection('databricks');

$topEvents = $db->table('main.analytics.fact_sales as s')
    ->join('main.analytics.dim_event as e', 'e.event_id', '=', 's.event_id')
    ->select('e.name', $db->raw('sum(s.amount) as revenue'), $db->raw('count(*) as tickets'))
    ->whereBetween('s.sale_date', ['2026-01-01', '2026-06-30'])
    ->groupBy('e.name')
    ->orderByDesc('revenue')
    ->limit(10)
    ->get();

$count = $db->table('main.analytics.dim_event')->where('status', 'active')->count();
```

Three-part Unity Catalog names are wrapped correctly with backticks: `main.analytics.dim_event` compiles to ``main`.`analytics`.`dim_event``.

### Eloquent models

[](#eloquent-models)

Point a model at the connection and give it a fully qualified table name. Analytics tables typically have no auto-incrementing key and no Laravel timestamps, so disable both:

```