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, spread some kind words about our work or sponsor our work via Patreon.
You will sometimes get exclusive content on tips about Laravel, AWS or Kubernetes on Patreon and some early-access to projects or packages.
🚀
Installation
You can install the package via composer:
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.
// 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.
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.
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():
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.
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():
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 when it comes to schema capabilities and counter-patterns that may affect your implementation and see further caveats that are CockroachDB-only.
🐛
Testing
vendor/bin/phpunit
🤝
Contributing
Please see CONTRIBUTING for details.
🔒
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
5 Nov 11, 2022
2 Sep 28, 2022
4 Feb 22, 2022
424 Dec 12, 2022
161 Oct 17, 2022
359 Jan 3, 2023
547 Dec 27, 2022
258 Dec 31, 2022
3 Apr 26, 2022
745 Jan 7, 2023
12 Dec 11, 2022
636 Dec 30, 2022
751 Jan 6, 2023
8 Sep 19, 2019
3 Aug 15, 2021
341 Dec 30, 2022
1 Dec 15, 2021
2.5k Dec 27, 2022
441 Dec 11, 2022