Stars: 451
Forks: 128
Pull Requests: 93
Issues: 177
Watchers: 21
Last Updated: 2023-07-10 05:39:58
Eloquent syntax for DynamoDB
License: MIT License
Languages: PHP, JavaScript, Shell
Supports all key types - primary hash key and composite keys.
For advanced users only. If you're not familiar with Laravel, Laravel Eloquent and DynamoDB, then I suggest that you get familiar with those first.
Breaking changes in v2: config no longer lives in config/services.php
Composer install
composer require baopham/dynamodb
Install service provider (< Laravel 5.5):
// config/app.php
'providers' => [
...
BaoPham\DynamoDb\DynamoDbServiceProvider::class,
...
];
Run
php artisan vendor:publish --provider 'BaoPham\DynamoDb\DynamoDbServiceProvider'
Update DynamoDb config in config/dynamodb.php
For Lumen
Try this to install the vendor:publish
command
Load configuration file and enable Eloquent support in bootstrap/app.php
:
$app = new Laravel\Lumen\Application(
realpath(__DIR__.'/../')
);
// Load dynamodb config file
$app->configure('dynamodb');
// Enable Facade support
$app->withFacades();
// Enable Eloquent support
$app->withEloquent();
BaoPham\DynamoDb\DynamoDbModel
, then you can use Eloquent methods that are supported. The idea here is that you can switch back to Eloquent without changing your queries.BaoPham\DynamoDb\ModelTrait
, it will call a PutItem
after the model is saved.$model->find($id, array $columns = []);
$model->findMany($ids, array $columns = []);
$model->delete();
$model->deleteAsync()->wait();
// Using getIterator()
// If 'key' is the primary key or a global/local index and it is a supported Query condition,
// will use 'Query', otherwise 'Scan'.
$model->where('key', 'key value')->get();
$model->where(['key' => 'key value']);
// Chainable for 'AND'.
$model->where('foo', 'bar')
->where('foo2', '!=', 'bar2')
->get();
// Chainable for 'OR'.
$model->where('foo', 'bar')
->orWhere('foo2', '!=', 'bar2')
->get();
// Other types of conditions
$model->where('count', '>', 0)->get();
$model->where('count', '>=', 0)->get();
$model->where('count', '<', 0)->get();
$model->where('count', '<=', 0)->get();
$model->whereIn('count', [0, 100])->get();
$model->whereNotIn('count', [0, 100])->get();
$model->where('count', 'between', [0, 100])->get();
$model->where('description', 'begins_with', 'foo')->get();
$model->where('description', 'contains', 'foo')->get();
$model->where('description', 'not_contains', 'foo')->get();
// Nested conditions
$model->where('name', 'foo')
->where(function ($query) {
$query->where('count', 10)->orWhere('count', 20);
})
->get();
// Nested attributes
$model->where('nestedMap.foo', 'bar')->where('list[0]', 'baz')->get();
NULL and NOT_NULL only check for the attribute presence not its value being null
See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Condition.html
$model->whereNull('name');
$model->whereNotNull('name');
// Using scan operator, not too reliable since DynamoDb will only give 1MB total of data.
$model->all();
// Basically a scan but with limit of 1 item.
$model->first();
Unfortunately, offset of how many records to skip does not make sense for DynamoDb. Instead, provide the last result of the previous query as the starting point for the next query.
Examples:
For query such as:
$query = $model->where('count', 10)->limit(2);
$items = $query->all();
$last = $items->last();
Take the last item of this query result as the next "offset":
$nextPage = $query->after($last)->limit(2)->all();
// or
$nextPage = $query->afterKey($items->lastKey())->limit(2)->all();
// or (for query without index condition only)
$nextPage = $query->afterKey($last->getKeys())->limit(2)->all();
// update
$model->update($attributes);
// update asynchronously and wait on the promise for completion.
$model->updateAsync($attributes)->wait();
$model = new Model();
// Define fillable attributes in your Model class.
$model->fillableAttr1 = 'foo';
$model->fillableAttr2 = 'foo';
// DynamoDb doesn't support incremented Id, so you need to use UUID for the primary key.
$model->id = 'de305d54-75b4-431b-adb2-eb6b9e546014';
$model->save();
Saving single model asynchronously and waiting on the promise for completion.
$model = new Model();
// Define fillable attributes in your Model class.
$model->fillableAttr1 = 'foo';
$model->fillableAttr2 = 'bar';
// DynamoDb doesn't support incremented Id, so you need to use UUID for the primary key.
$model->id = 'de305d54-75b4-431b-adb2-eb6b9e546014';
$model->saveAsync()->wait();
Saving multiple models asynchronously and waiting on all of them simultaneously.
for($i = 0; $i < 10; $i++){
$model = new Model();
// Define fillable attributes in your Model class.
$model->fillableAttr1 = 'foo';
$model->fillableAttr2 = 'bar';
// DynamoDb doesn't support incremented Id, so you need to use UUID for the primary key.
$model->id = uniqid();
// Returns a promise which you can wait on later.
$promises[] = $model->saveAsync();
}
\GuzzleHttp\Promise\all($promises)->wait();
$model->delete();
$model->deleteAsync()->wait();
$model->chunk(10, function ($records) {
foreach ($records as $record) {
}
});
// Use this with caution unless your limit is small.
// DynamoDB has a limit of 1MB so if your limit is very big, the results will not be expected.
$model->where('name', 'foo')->take(3)->get();
$model->where('name', 'foo')->firstOrFail();
// for composite key
$model->where('id', 'foo')->where('id2', 'bar')->firstOrFail();
$model->findOrFail('foo');
// for composite key
$model->findOrFail(['id' => 'foo', 'id2' => 'bar']);
$model = Model::first();
$model->refresh();
class Foo extends DynamoDbModel
{
protected static function boot()
{
parent::boot();
static::addGlobalScope('count', function (DynamoDbQueryBuilder $builder) {
$builder->where('count', '>', 6);
});
}
public function scopeCountUnderFour($builder)
{
return $builder->where('count', '<', 4);
}
public function scopeCountUnder($builder, $count)
{
return $builder->where('count', '<', $count);
}
}
$foo = new Foo();
// Global scope will be applied
$foo->all();
// Local scope
$foo->withoutGlobalScopes()->countUnderFour()->get();
// Dynamic local scope
$foo->withoutGlobalScopes()->countUnder(6)->get();
$model = new Model();
$model->where('id', 'foo')->removeAttribute('name', 'description', 'nested.foo', 'nestedArray[0]');
// Or
Model::find('foo')->removeAttribute('name', 'description', 'nested.foo', 'nestedArray[0]');
For debugging purposes, you can choose to convert to the actual DynamoDb query
$raw = $model->where('count', '>', 10)->toDynamoDbQuery();
// $op is either "Scan" or "Query"
$op = $raw->op;
// The query body being sent to AWS
$query = $raw->query;
where $raw
is an instance of RawDynamoDbQuery
Use decorate
when you want to enhance the query. For example:
To set the order of the sort key:
$items = $model
->where('hash', 'hash-value')
->where('range', '>', 10)
->decorate(function (RawDynamoDbQuery $raw) {
// desc order
$raw->query['ScanIndexForward'] = false;
})
->get();
To force to use "Query" instead of "Scan" if the library fails to detect the correct operation:
$items = $model
->where('hash', 'hash-value')
->decorate(function (RawDynamoDbQuery $raw) {
$raw->op = 'Query';
})
->get();
If your table has indexes, make sure to declare them in your model class like so
/**
* Indexes.
* [
* '<simple_index_name>' => [
* 'hash' => '<index_key>'
* ],
* '<composite_index_name>' => [
* 'hash' => '<index_hash_key>',
* 'range' => '<index_range_key>'
* ],
* ]
*
* @var array
*/
protected $dynamoDbIndexKeys = [
'count_index' => [
'hash' => 'count'
],
];
Note that order of index matters when a key exists in multiple indexes.
For example, we have this
$model->where('user_id', 123)->where('count', '>', 10)->get();
with
protected $dynamoDbIndexKeys = [
'count_index' => [
'hash' => 'user_id',
'range' => 'count'
],
'user_index' => [
'hash' => 'user_id',
],
];
will use count_index
.
protected $dynamoDbIndexKeys = [
'user_index' => [
'hash' => 'user_id',
],
'count_index' => [
'hash' => 'user_id',
'range' => 'count'
]
];
will use user_index
.
Most of the time, you should not have to do anything but if you need to use a specific index, you can specify it like so
$model->where('user_id', 123)->where('count', '>', 10)->withIndex('count_index')->get();
To use composite keys with your model:
$compositeKey
to an array of the attributes names comprising the key, e.g.protected $primaryKey = 'customer_id';
protected $compositeKey = ['customer_id', 'agent_id'];
$model->find(['customer_id' => 'value1', 'agent_id' => 'value2']);
Use DynamoDb
facade to build raw queries
use BaoPham\DynamoDb\Facades\DynamoDb;
DynamoDb::table('articles')
// call set<key_name> to build the query body to be sent to AWS
->setFilterExpression('#name = :name')
->setExpressionAttributeNames(['#name' => 'author_name'])
->setExpressionAttributeValues([':name' => DynamoDb::marshalValue('Bao')])
->prepare()
// the query body will be sent upon calling this.
->scan(); // supports any DynamoDbClient methods (e.g. batchWriteItem, batchGetItem, etc.)
DynamoDb::table('articles')
->setIndexName('author_name')
->setKeyConditionExpression('#name = :name')
->setProjectionExpression('id, author_name')
// Can set the attribute mapping one by one instead
->setExpressionAttributeName('#name', 'author_name')
->setExpressionAttributeValue(':name', DynamoDb::marshalValue('Bao'))
->prepare()
->query();
DynamoDb::table('articles')
->setKey(DynamoDb::marshalItem(['id' => 'ae025ed8']))
->setUpdateExpression('REMOVE #c, #t')
->setExpressionAttributeName('#c', 'comments')
->setExpressionAttributeName('#t', 'tags')
->prepare()
->updateItem();
DynamoDb::table('articles')
->setKey(DynamoDb::marshalItem(['id' => 'ae025ed8']))
->prepare()
->deleteItem();
DynamoDb::table('articles')
->setItem(DynamoDb::marshalItem(['id' => 'ae025ed8', 'author_name' => 'New Name']))
->prepare()
->putItem();
// Or, instead of ::table()
DynamoDb::newQuery()
->setTableName('articles')
// Or access the DynamoDbClient instance directly
DynamoDb::client();
// pass in the connection name to get a different client instance other than the default.
DynamoDb::client('test');
The query builder methods are in the form of set<key_name>
, where <key_name>
is the key name of the query body to be sent.
For example, to build an UpdateTable
query:
[
'AttributeDefinitions' => ...,
'GlobalSecondaryIndexUpdates' => ...,
'TableName' => ...
]
Do:
$query = DynamoDb::table('articles')
->setAttributeDefinitions(...)
->setGlobalSecondaryIndexUpdates(...);
And when ready:
$query->prepare()->updateTable();
Laravel ^5.1
Follow these steps:
composer.json
to use v2composer update
php artisan vendor:publish
config/services.php
to the new config file config/dynamodb.php
as one of the connections
key
, secret
, token
inside credentials
local_endpoint
to endpoint
local
fieldQ: Cannot assign id
property if its not in the fillable array
A: Try this?
Q: How to create migration?
A: Please see this issue
Q: How to use with factory?
A: Please see this issue
Q: How do I use with Job? Getting a SerializesModels error
A: You can either write your own restoreModel or remove the SerializesModels
trait from your Job.