I'm building out a Shedquarters in my backyard! Check out the ever-evolving post + pictures here →

The Exceeding Cleverness of Laravel's Atomic Database Locks

July 22, 2021

I was having a conversation in a Slack today about MySQL's "advisory locks", which let you acquire a lock that is not table dependent. You just ask MySQL for a lock with a name and it either gives it to you or doesn't:

1-- Try to get a lock, waiting up to 10 seconds for it.
2SELECT GET_LOCK('my-lock-name', 10);
3 
4-- Returns 1 if a lock is acquired, 0 if not.
Code highlighting powered by torchlight.dev.

These are great for getting application-level locks. Say you've got five "worker" processes that need to "reserve" items for processing. Obviously you only want an item to be processed once, and you can't rely on just updating a reserved_at column, because two processes might grab a record at the exact same time, leading to duplicate processing.

In this case, you'd have each worker get a lock as the "leader", reserve their job, and then release the lock.

Let's say for example that you have five import processors, all running as pseudo-daemons, sitting around waiting for new user imports to work on.

In the process method of your daemon, you would want to acquire a lock while you look for imports that are ready to process:

1class Process extends Command
2{
3 use IsPseudoDaemon;
4 
5 protected $signature = 'imports:process';
6 
7 public function handle()
8 {
9 $this->runAsPseudoDaemon();
10 }
11 
12 /**
13 * This is the main method that will be kept alive.
14 */
15 public function process()
16 {
18 // Acquire a lock while we look for imports.
19 $import = Cache::lock('reserve-import')->get(function () {
20 if ($import = Import::readyToProcess()->first()) {
21 // Reserve the import while we hold the lock,
22 // so no one else can.
23 return tap($import)->reserve();
24 }
25 });
26 
27 // Process the import if we secured one.
28 optional($import)->process();
29 }
30}

That's a bit about why you would want a lock, let's talk about how Laravel does this.

Laravel Locks

Laravel supports atomic locks using a number of different drivers. The most common is probably going to be Redis driver, which many people use as their cache. It's something Redis is good at, and most people have Redis in their stack.

But if you don't have Redis in your stack, Laravel provides several other drivers.

  • memcached
  • dynamodb
  • database
  • file
  • array

The array driver is just for testing, since it's in memory only, and the file driver would only work for single-server setups, not across multiple.

Memcached, Redis, and DynamoDB all support locking natively, but I was surprised to just see database in there, without mention of which database driver you're using.

We already know MySQL has the GET_LOCK style advisory locks, but did the Laravel team implement different locking mechanisms for every single driver?

Turns out, they did something twice as clever and half as difficult.

Database Locks For All

If you go take a look at the DatabaseLock source code, you'll see exactly how they do it:

1 try {
2 $this->connection->table($this->table)->insert([
3 'key' => $this->name,
4 'owner' => $this->owner,
5 'expiration' => $this->expiresAt(),
6 ]);
7 
8 $acquired = true;
9} catch (QueryException $e) {
10 // Stuff.
11}

They... insert a record? That's it?

This is so unbelievably coy, because this is not a locking mechanism at all. Laravel is relying on the database to enforce uniqueness, which every single database engine is fully capable of doing.

The docs give you a schema for your cache_locks table that mandates that key is a primary key, and therefore unique:

1Schema::create('cache_locks', function ($table) {
2 $table->string('key')->primary();
3 $table->string('owner');
4 $table->integer('expiration');
5});

Because two records can never share a key, you have atomicity guaranteed out of the box, for every single database driver.

You also get all the nice expiration, ownership, etc because they just insert that data as columns out to the side of the lock's name. Everything you'd expect from a proper locking implementation!

When I figured out how Laravel does this, I was taken by the simplicity and the cleverness. Leveraging one of the database's inherit strengths (a primary key may exist once) to work in the context of locks is just genius.

No futzing about with the different syntaxes and behaviors of advisory locks across engines, no ongoing maintenance when they change, no edge cases.

Insert a row.

Thanks for reading! My name is Aaron and I'm currently working at small property tax firm in Texas, where I serve in dual roles as COO & CTO.

I work on a lot of projects. I'm building a shedquarters. I currently do a podcast, and I used to do a different podcast.

If you ever have any questions or want to chat, I'm always on Twitter
Copyright 2013 - 2021, Aaron Francis.