https://github.com/renoki-co/laravel-thermite
Laravel Thermite is an extended PostgreSQL Laravel database driver to connect to a CockroachDB cluster.
https://github.com/renoki-co/laravel-thermite
active cockroach cockroachdb database laravel pgsql postgres postgresql psql replica
Last synced: 8 months ago
JSON representation
Laravel Thermite is an extended PostgreSQL Laravel database driver to connect to a CockroachDB cluster.
- Host: GitHub
- URL: https://github.com/renoki-co/laravel-thermite
- Owner: renoki-co
- License: apache-2.0
- Created: 2021-07-16T14:54:04.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-10-23T07:03:15.000Z (over 2 years ago)
- Last Synced: 2024-09-28T18:05:04.036Z (over 1 year ago)
- Topics: active, cockroach, cockroachdb, database, laravel, pgsql, postgres, postgresql, psql, replica
- Language: PHP
- Homepage:
- Size: 59.6 KB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
Laravel Thermite
================
[](https://codecov.io/gh/renoki-co/laravel-thermite/branch/master)
[](https://github.styleci.io/repos/386672830)
[](https://packagist.org/packages/renoki-co/laravel-thermite)
[](https://packagist.org/packages/renoki-co/laravel-thermite)
[](https://packagist.org/packages/renoki-co/laravel-thermite)
[](https://packagist.org/packages/renoki-co/laravel-thermite)
Laravel Thermite is an extended PostgreSQL Laravel database driver to connect to a CockroachDB cluster.
## 🤝 Supporting
**If you are using one or more Renoki Co. open-source packages in your production apps, in presentation demos, hobby projects, school projects or so, sponsor our work with [Github Sponsors](https://github.com/sponsors/rennokki). 📦**
[
](https://github-content.renoki.org/github-repo/27)
## 🚀 Installation
You can install the package via composer:
```bash
composer require renoki-co/laravel-thermite
```
## 🙌 Usage
The driver is based on Postgres, most of the features from Laravel's first-party Postgres driver are available in CockroachDB.
```php
// config/database.php
return [
// ...
'connections' => [
// ...
'cockroachdb' => [
'driver' => 'cockroachdb',
'url' => env('DATABASE_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '26257'),
'database' => env('DB_DATABASE', 'defaultdb'),
'username' => env('DB_USERNAME', 'root'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
'prefix' => '',
'prefix_indexes' => true,
'schema' => 'public',
'sslmode' => 'prefer',
],
],
];
```
## ✨ Caveats
### Primary Keys are not incremental
Postgres supports incrementing keys, but since CockroachDB is based on a global multi-master architecture, having increments may lead to [transaction contention](https://www.cockroachlabs.com/docs/v21.1/sql-faqs#how-do-i-auto-generate-unique-row-ids-in-cockroachdb).
This way, this extended driver leverages you with two functions that you may call in your migrations to generate performant, unique IDs. The differences between the methods [can be found here](https://www.cockroachlabs.com/docs/v21.1/sql-faqs#what-are-the-differences-between-uuid-sequences-and-unique_rowid).
The `->id()` method got replaced to generate a random UUID as primary key with `gen_random_uuid()` instead of an incremental primary key. The downside is that is not orderable, opposed to `uniqueRowId()`:
```php
use RenokiCo\LaravelThermite\Database\Blueprint;
Schema::create('users', function (Blueprint $table) {
$table->id();
$table->string('name');
});
class User extends Model
{
// Make sure to set key type as string.
protected $keyType = 'string';
}
```
With `uniqueRowId()`, it uses `unique_rowid()`-generated primary key. This is highly-orderable, being sequentially generated. The only minor downsides are the throttling upon insert, which are limited by one node.
```php
use RenokiCo\LaravelThermite\Database\Blueprint;
Schema::create('users', function (Blueprint $table) {
$table->uniqueRowId();
$table->string('name');
});
class User extends Model
{
// Do not set the $keyType to string, as it is an integer.
}
```
### Foreign keys associated with Primary Keys
To represent the primary key constraints in other tables, like passing relational fields, consider using `->uuid()`:
```php
Schema::create('users', function (Blueprint $table) {
$table->id();
$table->string('name');
});
Schema::create('books', function (Blueprint $table) {
$table->id();
$table->uuid('user_id')->index();
$table->string('name');
});
$book = $user->books()->create(['name' => 'The Great Gatsby']);
```
## Other caveats
Being based on Postgres, CockroachDB borrowed functionalities from its code. Consider [reading about CockroachDB-Postgres compatibilities](https://www.cockroachlabs.com/docs/v21.1/sql-feature-support.html) when it comes to schema capabilities and counter-patterns that may affect your implementation and [see further caveats that are CockroachDB-only](https://www.cockroachlabs.com/docs/v21.1/postgresql-compatibility.html).
## 🐛 Testing
``` bash
vendor/bin/phpunit
```
## 🤝 Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## 🔒 Security
If you discover any security related issues, please email alex@renoki.org instead of using the issue tracker.
## 🎉 Credits
- [Alex Renoki](https://github.com/rennokki)
- [All Contributors](../../contributors)