This will be a quick walkthrough of standing up basic Django with some fancy development tools like IntelliJ, mypy, and black. In addition to Django we will use DRF to implement a REST API and Gunicorn to expand on the basic Django runserver.

This guide acts as a precursor, setting the stage for future posts where this Django service will be utilized as a dependency of the SQS consumer we created in this guide https://honstain.com/asyncio-sqs-and-httpx/.

Why would you be interested in this write-up?

• You're looking for some practical examples of setting Django with IntelliJ.
• You're interested in Gunicorn configurations for Django services.
  • This will give us some basic tooling to consider performance in future blog posts.

What this post is not:

• A replacement for the excellent Django tutorial https://docs.djangoproject.com/en/5.0/intro/. We assume you have gone through the tutorial or can wing it.
• Security or CI/CD - we are primarily focused on getting a service setup for experimenting with development tools and eventually scaling/performance issue (subsequent posts).

Overview of Key Dependencies

The dependencies most relevant to this blog:

Setup The Django Service

The idea here is to take the source code and get it running locally.

Get the Source Code

I have a public github repo you can pull or copy to get started.

GitHub - AnthonyHonstain/django-user-service: An example Django 5.0 service with DRF, postgres, gunicorn.

An example Django 5.0 service with DRF, postgres, gunicorn. - AnthonyHonstain/django-user-service

GitHubAnthonyHonstain

Get Mamba or Decide on an Alternative

Similar to the previous SQS consumer post we are going to assume you are using mamba.

Micromamba User Guide — documentation

document.write(`<img src="../_static/logo.png" class="logo__image only-dark" alt="documentation - Home"/>`);QuantStack & mamba contributors

# CD into the project directory
mamba create -n django-user-service -c conda-forge  python=3.12
mamba activate django-user-service

pyproject.toml and Poetry

We will be using poetry to manage the python dependencies for this service.

Poetry - Python dependency management and packaging made easy

Python dependency management and packaging made easy

Python dependency management and packaging made easy

This is the pyproject.toml for the repo https://github.com/AnthonyHonstain/django-user-service/blob/main/pyproject.toml

In the mamba environment you already have active:

pip install poetry
poetry install --no-root

Django and mypy

I set this Django service up using mypy, there was one thing I missed that you might also want to be aware of. Its not enough to just add mypy and django-stubs.

The mypy configuration file: https://github.com/AnthonyHonstain/django-user-service/blob/main/mypy.ini

Without the mypy configuration I ran into a number of mypy errors.

EXAMPLE ERRORS

❯ mypy .
usercore/models.py:5: error: Need type annotation for "name"  [var-annotated]
usercore/models.py:6: error: Need type annotation for "age"  [var-annotated]
user_service/settings.py:30: error: Need type annotation for "ALLOWED_HOSTS" (hint: "ALLOWED_HOSTS: List[<type>] = ...")  [var-annotated]
Found 3 errors in 2 files (checked 15 source files)

We have the django-stubs dependency set, but we need to help mypy along with that mypy.ini file.

References:

The mypy configuration file - mypy 1.9.0 documentation

mypy 1.9.0 documentation

GitHub - typeddjango/django-stubs: PEP-484 stubs for Django

PEP-484 stubs for Django. Contribute to typeddjango/django-stubs development by creating an account on GitHub.

GitHubtypeddjango

IntelliJ and Django

I will provide some examples of configuring IntelliJ to work with Django, I didn't find it super intuitive and hope this could help others.

IntelliJ IDEA – the Leading Java and Kotlin IDE

IntelliJ IDEA is undoubtedly the top-choice IDE for software developers. It makes Java and Kotlin development a more productive and enjoyable experience.

JetBrainsJetBrains

You can skip this if you use an alternative editor.

Django and Python Black

I also found python Black to play nice with Django and have included an example screenshot of enabling the Black formatted automatically in IntelliJ. This automated the majority of the formatting activities.

Getting Django Running

Standing up the database

The core of this service is going to be a postgres database, which we will standup using docker compose.

docker-compose.yml

version: '3.8'

services:
  db:
    image: postgres:16.2
    volumes:
      - postgres_data_product:/var/lib/postgresql/data/
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - '5432:5432'
    # Logging for every query - can comment out the entire line to disable
    #     Reference: https://stackoverflow.com/a/58806511
    command: ["postgres", "-c", "log_statement=all"]

volumes:
  postgres_data_product:

Success looks like:

db-1 | 2024-02-27 15:02:00.353 UTC [1] LOG: database system is ready to accept connections

Connect IntelliJ to the Database

It should only require you to set the user and password from the docker-compose file.

You won't have much to look at until you run the migrations.

Run the Django Migrations

You can start running the manage.py commands to initialize your Django service.

python manage.py migrate

You can refresh the postgres schema in IntelliJ to view the results of the migration. Success looks like you now have a table called usercore_user.

This is also a reasonable time to create a superuser for local development.

python manage.py createsuperuser

Overview of the API

This service uses DRF https://www.django-rest-framework.org/#installation to serve as a basic REST API.

The model here is just a laughably basic user with three fields.

from django.db import models


class User(models.Model):
    name = models.CharField(max_length=200)
    age = models.IntegerField()

And we will make a basic DRF ModelViewSet for it.

import structlog

from rest_framework import serializers, viewsets

from .models import User

logger = structlog.get_logger(__name__)


# Serializers define the API representation.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ["id", "name", "age"]


# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    def list(self, request, *args, **kwargs):
        logger.info("UserViewSet list called", size=str(len(self.queryset)))
        return super(UserViewSet, self).list(request, *args, **kwargs)

    def create(self, request, *args, **kwargs):
        logger.info("Creating a new user", body=request.data)
        return super(UserViewSet, self).create(request, *args, **kwargs)

Running the service python manage.py runserver if you haven't already will let us exercise the endpoint using the DRF UI.

http://localhost:8000/usercore/users/

You also have the basic Django Admin UI http://localhost:8000/admin/

IntelliJ HTTP Client

I found the IntelliJ HTTP client to be a handy way to exercise simple endpoints, postman would also work here.

HTTP Client | IntelliJ IDEA

Explore the features of the HTTP Client plugin: compose and execute HTTP requests, view responses, configure proxy settings, certificates, and more.

IntelliJ IDEA Help

### GET request list
GET http://localhost:8000/usercore/users/
Accept: application/json

### GET request single record
GET http://localhost:8000/usercore/users/40000/
Accept: application/json

### POST request create single record
POST http://localhost:8000/usercore/users/
Accept: application/json
Content-Type: application/json

{"name":"Anthony", "age":2}

Starting Gunicorn

The Django runserver is useful for local development, but we want to get a more capable web server more detailed investigation.

Since we should have already installed gunciorn with our python dependencies, we can start it using:

gunicorn --log-level debug --bind 0.0.0.0:8000 user_service.wsgi -w 1

This uses the wsgi module Django already created for us, and sets one default worker.

Shooting a few calls into the server should look something like this:

This service is also setup with structlog and emits JSON formatted logs to the logs folder in the project directory.

tail -f json.log | jq


{
  "request": "GET /usercore/users/",
  "user_agent": "Apache-HttpClient/4.5.14 (Java/17.0.10)",
  "event": "request_started",
  "ip": "127.0.0.1",
  "request_id": "f4449541-2eea-4337-ad63-fb24de0c0d35",
  "timestamp": "2024-03-15T15:06:48.697754Z",
  "logger": "django_structlog.middlewares.request",
  "level": "info"
}
{
  "size": "3",
  "event": "UserViewSet list called",
  "ip": "127.0.0.1",
  "request_id": "f4449541-2eea-4337-ad63-fb24de0c0d35",
  "timestamp": "2024-03-15T15:06:48.767477Z",
  "logger": "usercore.views",
  "level": "info"
}
{
  "code": 200,
  "request": "GET /usercore/users/",
  "event": "request_finished",
  "ip": "127.0.0.1",
  "user_id": null,
  "request_id": "f4449541-2eea-4337-ad63-fb24de0c0d35",
  "timestamp": "2024-03-15T15:06:48.770240Z",
  "logger": "django_structlog.middlewares.request",
  "level": "info"
}

Summary

At this stage you should now have a Django service with DRF that can serve a basic API via Gunicorn (and has logging, tests, and a real PostgreSQL database).

GitHub - AnthonyHonstain/django-user-service: An example Django 5.0 service with DRF, postgres, gunicorn.

An example Django 5.0 service with DRF, postgres, gunicorn. - AnthonyHonstain/django-user-service

GitHubAnthonyHonstain

In subsequent posts, we will explore more of having our SQS consumer, call this service.

In this post we are going to stand up a basic Python SQS consumer that leverages asyncio and experiments with some different types of workloads.

Why would you be interested in this post?

• You're working in Python and want to create a service to consume from SQS.
• You're interested in an application of asyncio (in a Python 3.12 context).
• You're interested in seeing HTTPX used for an IO-bound workload (take an SQS message and process several HTTP calls).

This service was created with the idea that you would ultimately run it in something like Kubernetes. In this post, we will stop significantly short of containerizing and running in a cluster.

Overview of Key Dependencies

I will provide an overview of the interesting dependencies I selected for this service. I tried to articulate the reasoning/idea behind why I used what, but all of this in the context of trying to construct a basic service that would run in a container, that could process SQS messages and make HTTP calls.

The really notable stuff in this service

• aiobotocore 2.8.0 https://github.com/aio-libs/aiobotocore and https://aiobotocore.readthedocs.io/en/latest/
  • The dependency I struggled the most with. I was looking for an asynchronous way to get SQS messages.
    • None of this should be a criticism of this project, I think it is fairly unclear if you're new to Python+SQS what the best options for a client are. At least when I compare it to other clients, like picking an HTTP client where you find clear leaders to pick from.
    • Discussions on this are probably pretty similar to other discussions in the Python community about how to deal with libraries that don't support asyncio async/await patterns. Resulting in these replicas of the original non-async project.
    • This project looks to be reasonably maintained, and it seemed very unlikely the boto was going to get asyncio support.
• httpx 0.24.2 https://www.python-httpx.org/
  • I haven't tried other client's asyncio support, on cursory review I was pleased with the documentation and never hit any roadblocks. It just worked and the code was clean wrt async/await.
• pydantic 2.5.2 https://docs.pydantic.dev/latest/
  • I used this to model the JSON coming out of SQS and the request/response from the HTTPX calls. If I had to do it over again I might go with dataclasses, but I was partially using this as an opportunity to explore pydantic.
• python 3.12 https://www.python.org/downloads/release/python-3120/
  • It would be fair criticism that I don't effectively leverage new language features (when applicable).

Less critical things:

• python-json-logger 2.0.7 https://github.com/madzak/python-json-logger
  • This helped me structure the logs in JSON.

• black 23.11.0 https://black.readthedocs.io/en/stable/
  • I have been getting a ton of value here, ymmv. I love that it consistently and with no effort on my part produces very readable and organized formatting.
• mypy 1.7.1 https://mypy.readthedocs.io/en/stable/
  • static type checker - I still bump into odd things, but have found the juice worth the squeeze as more developers come into a project.
• respx 0.20.2 https://lundberg.github.io/respx/
  • Used for mocking out HTTPX. I found it pretty helpful, but saw some peers get bound up by not understanding the scope of it.

Service Setup - Python and Poetry

There are many ways to manage dependencies and Python environments, I won't argue this is the best. But it has worked well for me developing on Ubuntu where I do most of the actual coding in IntelliJ and have multiple projects with different Python versions (some having more complicated dependencies).

Requirements (you should have this already)

• Mamba installed (in my case I went for micromamba) https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html

Setup the mamba environment

mamba create -n sqs-async-consumer -c conda-forge  python=3.12

Optional Tip After Mamba Environment Creation

If you use ZSH, you can modify your .zshrc file to automatically set the environment when you navigate to the directory for the project.

function mamba_auto_activate() {
    if [ "$(pwd)" = "/home/dev/Desktop/python/sqs-async-consumer" ]; then
        mamba activate sqs-async-consumer
    fi
}
chpwd_functions+=("mamba_auto_activate")

Install Poetry

I think there are a number of ways to install poetry https://python-poetry.org/

I am really happy with poetry (relative to pip) for tracking my python services dependencies, versioning, and locking dependencies.

I have had much less success trying to use poetry for virtualization (hence me still leaning on mamba). This could just be my own failing or lack of sufficient knowledge + research into poetry and how best to use it. When I have tried to run pure poetry, I get tangled up with IntelliJ not being able to correctly interact with the environment (important for me since I prefer to use Intellij to run/test/debug the service during my more normal development cycle).

Install Poetry Dependencies

This will install aiobotocore and all the other stuff we need for the service to run.

poetry install

The pyproject.toml is a critical file to review https://github.com/AnthonyHonstain/sqs-async-python-consumer/blob/main/pyproject.toml

[tool.poetry]
name = "sqs-consumer-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
aiobotocore = "^2.8.0"
pydantic = "^2.5.2"
black = "^23.11.0"
httpx = "^0.25.2"
mypy = "^1.7.1"
python-json-logger = "^2.0.7"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"
pytest-asyncio = "^0.23.2"
respx = "^0.20.2"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

# Black configuration
[tool.black]
line-length = 120

I also found it helpful to check the config

poetry config --list

Docker Compose wiremock and localstack

We will use docker compose to stand up wiremock and localstack for development and testing.

• localstack is used for getting a local version of AWS's SQS product.
  • Note that this docker-compose.yml also contains a basic init of localstack to automatically create the queue you want for local development.
• wiremock is used for proving a mock HTTP service
  • Note - it is created with some starter mappings

Source for the docker-compose https://github.com/AnthonyHonstain/sqs-async-python-consumer/blob/main/docker-compose.yml

This is the docker-compose.yml file for the service

version: '3.8'

services:
  localstack:
    image: localstack/localstack:3.1.0
    ports:
      - "4566:4566" # LocalStack's default edge port
      - "4571:4571" # Deprecated port, but can be included for backward compatibility
    environment:
      - SERVICES=sqs
      #- DEBUG=1
      - DATA_DIR=/tmp/localstack/data
    volumes:
      # https://docs.localstack.cloud/getting-started/installation/#docker-compose
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"

  wiremock:
    image: wiremock/wiremock:3.3.1-2
    ports:
      - "8080:8080" # Default Wiremock port
    volumes:
      - ./wiremock:/home/wiremock
    command: --verbose

  localstack-init:
    image: amazon/aws-cli:2.15.15
    depends_on:
      - localstack
    environment:
      AWS_ACCESS_KEY_ID: 'test'
      AWS_SECRET_ACCESS_KEY: 'test'
      AWS_DEFAULT_REGION: 'us-east-1'
    volumes:
      - ./init-localstack.sh:/init-localstack.sh  # Corrected volume mount
    entrypoint: /bin/sh
    command: -c "/init-localstack.sh"

Setting up IntelliJ

I use the Ultimate version, but PyCharm should be fine. https://www.jetbrains.com/

Open module settings

Configure an SDK

Example IntelliJ configuration for running locally:

Example IntelliJ configuration for running all tests:

Run Tests

This can be done with poetry run pytest

Start the required dependencies

Run The Service Locally

You can use IntelliJ with the setting provided previously in this guide, or you can use the command line: poetry run python sqs_consumer_project/sqs_consumer.py

You can use jq to format the results: poetry run python sqs_consumer_project/sqs_consumer.py 2>&1 | jq

❯ poetry run python sqs_consumer_project/sqs_consumer.py          

{"asctime": "2024-02-18 07:46:12,742", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-3"}
{"asctime": "2024-02-18 07:46:12,744", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-2"}
{"asctime": "2024-02-18 07:46:12,748", "name": "root", "levelname": "INFO", "message": "receive_messages got messages", "taskName": "Task-3", "message_count": 1}
{"asctime": "2024-02-18 07:46:12,748", "name": "root", "levelname": "INFO", "message": "Starting MessageId processing", "taskName": "Task-3", "message_id": "a4f2d436-36f3-408d-a747-f14687e103a1"}
{"asctime": "2024-02-18 07:46:12,748", "name": "root", "levelname": "INFO", "message": "pydantic model", "taskName": "Task-3", "sqs_message": "name='Anthony' age=2"}
{"asctime": "2024-02-18 07:46:12,748", "name": "root", "levelname": "INFO", "message": "Started work", "taskName": "Task-3", "message_name": "Anthony", "message_age": 2}
{"asctime": "2024-02-18 07:46:14,750", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-2"}
{"asctime": "2024-02-18 07:46:16,761", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-2"}
{"asctime": "2024-02-18 07:46:16,945", "name": "httpx", "levelname": "INFO", "message": "HTTP Request: POST http://localhost:8080/record_user \"HTTP/1.1 200 OK\"", "taskName": "Task-3"}
{"asctime": "2024-02-18 07:46:16,946", "name": "root", "levelname": "INFO", "message": "Received response", "taskName": "Task-3", "user_id": "xxxxxx"}
{"asctime": "2024-02-18 07:46:16,946", "name": "root", "levelname": "INFO", "message": "Completed work", "taskName": "Task-3", "message_name": "Anthony", "message_age": 3, "user_id": "xxxxxx"}
{"asctime": "2024-02-18 07:46:16,958", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-3"}
{"asctime": "2024-02-18 07:46:18,766", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-2"}
{"asctime": "2024-02-18 07:46:18,963", "name": "root", "levelname": "INFO", "message": "Polling for messages", "taskName": "Task-3"}
{"asctime": "2024-02-18 07:46:18,988", "name": "root", "levelname": "ERROR", "message": "Cancel Error", "taskName": "Task-2"}
{"asctime": "2024-02-18 07:46:18,988", "name": "root", "levelname": "INFO", "message": "Finished", "taskName": "Task-2"}
{"asctime": "2024-02-18 07:46:18,988", "name": "root", "levelname": "ERROR", "message": "Cancel Error", "taskName": "Task-3"}
{"asctime": "2024-02-18 07:46:18,988", "name": "root", "levelname": "INFO", "message": "Finished", "taskName": "Task-3"}
{"asctime": "2024-02-18 07:46:19,000", "name": "root", "levelname": "INFO", "message": "Script interrupted by user", "taskName": null}

The important sequence of work that one of the tasks will go through consuming SQS messages:

• "message": "receive_messages got messages" We have a message to work from SQS.
• "message": "Started work" We are going to make the HTTP call (we expect a delay).
• You will see other work happening in the service during this time
• "message": "Received response" We got an HTTP response
• "message": "Completed work" We successfully completed our work on the message and will signal it can be deleted.

Summary

We provided the outline of a service that could consume SQS messages and make HTTP calls and got basic functionality working. We also got some rudimentary logging and testing established.

You can get the whole repo on github if you want to pull it down to modify or review. This service is missing some things you would want before using it in a production context (configuration and more robust testing being notable). We may take this service and experiment with HTTPX/concurrency in subsequent posts.

GitHub - AnthonyHonstain/sqs-async-python-consumer: An example service written in Python using asyncio that can consume SQS messages and execute HTTP calls based on those messages.

An example service written in Python using asyncio that can consume SQS messages and execute HTTP calls based on those messages. - GitHub - AnthonyHonstain/sqs-async-python-consumer: An example ser…

GitHubAnthonyHonstain

In this post, we will explore an alternative database schema design for tracking physical inventory. Our previous posts focused on using a single database record to model a distinct location and SKU (location and SKU being represented as basic strings in this example). But what would it look like if we designed our schema around the idea of double-entry accounting? That would mean the quantity of a given location and SKU would be defined by the sum of multiple database records (we couldn't just look at a single record anymore to find its current quantity).

A good primer for double-entry accounting is Martin Fowler's blog post on the subject https://www.martinfowler.com/eaaDev/AccountingNarrative.html.

Previous Blog Posts In This Series

This post will significantly reference several of my previous blog posts. We now seek to draw a comparison on this double-entry schema to a design that uses a single record (for each location and SKU relationship). I would venture to guess that most developers would not start with a double-entry model.

• Part 1 - Creating a Scalatra Inventory Management Service
• Part 2 - Implementing Create/Update in Slick
• Part 3 - Inventory Management Transfer
• Part 4 - Inventory Management Transfer with Row Level Locking

Source Code

• A basic skeleton of a Scalatra service you could use to build as you go while reading: https://bitbucket.org/honstain/scalatra-single-record-transfer-service/ You would need to create a new DAO and wire up the REST endpoints and tests.
• The completed solution: https://bitbucket.org/honstain/scalatra-double-record-transfer-service/src/master/

Designing the Schema for Double-Entry

Each transfer (physical movement of goods from one location to another) will be modeled with two new records, one decrementing the qty from the source location and one incrementing the qty for the destination.

Starting with a single location LOC-01 that contains 2 units of SKU-01

If we wanted to move 1 unit of SKU-01 to the location LOC-02, instead of updating record id:1 we would create two new records.

This means that to calculate the current quantity of LOC-01 and SKU-01 we would need to sum the quantity across records id:1 and id:2.

Using this design, we are never updating old database records, we are only creating new ones.

All our operations (creating, moving, and decrementing inventory) would be handled by a DB insert. Because we treat existing records as immutable, there are fewer instances where the DB needs to manage the overhead of locking specific rows. We saw in our previous post how we ended up doing some fine-grained row-level locking in order to provide consistency. We ended up locking everything in the transaction, the source and the destination, which can have an impact on all the other database queries that might be running against that table.

Just like in our original example, let's start with a DAO and way to retrieve all the database records for testing.

package org.bitbucket.honstain.inventory.dao

import org.slf4j.{Logger, LoggerFactory}
import slick.jdbc.{PostgresProfile, TransactionIsolation}
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

object TRANSACTION {
  val ADJUST = "adjust"
  val TRANSFER = "transfer"
}

case class InventoryDoubleRecord(
                                  id: Option[Int],
                                  sku: String,
                                  qty: Int,
                                  txnType: String,
                                  location: String
                                )

class InventoryDoubleRecords(tag: Tag) extends Table[InventoryDoubleRecord](tag, "inventory_double") {
  def id = column[Int]("id", O.PrimaryKey, O.AutoInc)
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def txnType = column[String]("type")
  def location = column[String]("location")
  def * =
    (id.?, sku, qty, txnType, location) <> (InventoryDoubleRecord.tupled, InventoryDoubleRecord.unapply)
}

object InventoryDoubleRecordDao extends TableQuery(new InventoryDoubleRecords(_)) {

  val logger: Logger = LoggerFactory.getLogger(getClass)

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[InventoryDoubleRecord]] = {
    db.run(this.result)
  }

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[(String, String, Option[Int])]] = {
    val groupByQuery = this.groupBy(x => (x.sku, x.location))
      .map{ case ((sku, location), group) => (sku, location, group.map(_.qty).sum) }
      .result
    db.run(groupByQuery)
  }
}

We will also make a basic test to start us off.

package org.bitbucket.honstain.inventory.dao

import org.bitbucket.honstain.PostgresSpec

import org.scalatest.BeforeAndAfter
import org.scalatra.test.scalatest._
import slick.dbio.DBIO
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Await
import scala.concurrent.duration.Duration


class InventoryDoubleRecordDaoTests extends ScalatraFunSuite with BeforeAndAfter with PostgresSpec {

  def createInventoryTable: DBIO[Int] =
    sqlu"""
          CREATE TABLE inventory_double
          (
            id bigserial NOT NULL,
            sku text,
            qty integer,
            type text,
            location text,
            CONSTRAINT pk_double PRIMARY KEY (id)
          );
      """
  def dropInventoryTable: DBIO[Int] =
    sqlu"""
          DROP TABLE IF EXISTS inventory_double;
      """

  before {
    Await.result(database.run(createInventoryTable), Duration.Inf)
  }

  after {
    Await.result(database.run(dropInventoryTable), Duration.Inf)
  }

  val TEST_SKU = "NewSku"
  val BIN_01 = "Bin-01"
  val BIN_02 = "Bin-02"

  test("findAll when empty") {
    val futureFind = InventoryDoubleRecordDao.findAll(database)
    val findResult: Seq[InventoryDoubleRecord] = Await.result(futureFind, Duration.Inf)

    findResult should equal(List())
  }
  
    test("findAll with single location and SKU but multiple records") {
    val inventoryTable = TableQuery[InventoryDoubleRecords] ++= Seq(
      InventoryDoubleRecord(None, TEST_SKU, 1, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(None, TEST_SKU, 3, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(None, TEST_SKU, -1, TRANSACTION.ADJUST, BIN_01)
    )
    Await.result(database.run(inventoryTable), Duration.Inf)

    val futureFind = InventoryDoubleRecordDao.findAll(database)
    val findResult: Seq[(String, String, Option[Int])] = Await.result(futureFind, Duration.Inf)

    findResult should equal(List((TEST_SKU, BIN_01, Some(3))))
  }

  test("findAll with multiple location+SKU and multiple records") {
    val inventoryTable = TableQuery[InventoryDoubleRecords] ++= Seq(
      InventoryDoubleRecord(None, TEST_SKU, 1, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(None, TEST_SKU, 3, TRANSACTION.ADJUST, BIN_02),
      InventoryDoubleRecord(None, TEST_SKU, -1, TRANSACTION.ADJUST, BIN_01)
    )
    Await.result(database.run(inventoryTable), Duration.Inf)

    val futureFind = InventoryDoubleRecordDao.findAll(database)
    val findResult: Seq[(String, String, Option[Int])] = Await.result(futureFind, Duration.Inf)

    findResult should contain only ((TEST_SKU, BIN_02, Some(3)), (TEST_SKU, BIN_01, Some(0)))
  }
}

This should look very similar to our original example (that modeled each location and SKU relationship with a single DB record), except for the fact that we now do a SQL aggregation on the results to find all the current inventory information.

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[(String, String, Option[Int])]] = {
    val groupByQuery = this.groupBy(x => (x.sku, x.location))
      .map{ case ((sku, location), group) => (sku, location, group.map(_.qty).sum) }
      .result
    db.run(groupByQuery)
  }

This Slick query is roughly equivalent to the following SQL:

SELECT sku, location, SUM(qty)
FROM inventory_double
GROUP BY sku, location

Why the SQL aggregation and tuple return type? How we model the record in the database with the class InventoryDoubleRecord is now somewhat abstracted from how our business logic might want to handle the date. The InventoryDoubleRecord class has id and txnType columns which are not necessarily applicable when a client is asking the service how many items are in a location or how many units of a SKU are available. Hence we are returning a tuple from our findAll function, the reader could map this to a new class if they preferred.

Create/Insert/Update Logic

Now we want the ability to create new inventory, and update the qty of an existing location + SKU. You might refer to this sort of logic as an adjustment (which I track via the TRANSACTION enum). Where previously we could take a lock on a single record and do an atomic create or update:

INSERT INTO inventory_single (sku, qty, location)
VALUES ('SKU-01', 3, 'LOC-01')
ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
DO UPDATE SET qty = EXCLUDED.qty;

Now we have to consider multiple rows in order to find out the current quantity of a location and SKU. Our initial function definition could look like:

  def create(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             location: String
            ): Future[InventoryDoubleRecord] = {
    val insert = for {
      // Find the current count for this Location and SKU
      initGroupBy <- // TODO - query to find existing qty

      // Insert a new record that will result in the desired qty
      _ <- // TODO - insert a new record

      // Return the updated value
      newRecordBySku <- // TODO return the current qty for the SKU and Location
    } yield newRecordBySku

    db.run(insert.transactionally)
  }

The structure we just outlined uses a Slick transaction and for comprehension to group a set of queries (lookup, insert, and lookup). We start first by doing the lookup component.

• Lookup existing qty - find the qty for the Location/SKU pair if it exists
  • A basic Slick aggregartion with sum, will give us a result of something like Future[Seq[(String, String, Option[Int])]]. We should be dealing with just a single record here given our schema design so we can use headOption to grab the head of the Sequence.

this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku)
        .map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption

• Insert - create a new database record.
  • Case 1 - We found no existing records for the SKU and Location pair.
  • Case 2 - We have an existing record and the QTY is needed to determine what the new qty to insert will be.

      _ <- {
        initGroupBy match {
          case None =>
            this += InventoryDoubleRecord(Some(0), sku, qty, TRANSACTION.ADJUST, location)
          case Some((_, Some(existingQty))) =>
            logger.debug(s"FOUND record $qty - $existingQty")
            this += InventoryDoubleRecord(Some(0), sku, qty - existingQty, TRANSACTION.ADJUST, location)
          case _ => DBIO.failed(new Exception("Insert for create failed"))
        }
      }

• Lookup current quantity - get the current qty for the Location/SKU pair after our insert.
  • I made an effort to use the return type InventoryDoubleRecord class so we could more easily draw a parallel with our single record schema design. It also illustrates an example of mapping the results (even I am not personally a fan of this code).

      newRecordGroupBy <- this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku).map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption
      newRecordBySku <- {
        newRecordGroupBy match {
          case Some((_, Some(newQty))) =>
            DBIO.successful (InventoryDoubleRecord (None, sku, newQty, TRANSACTION.ADJUST, location) )
          case _ =>
            DBIO.failed(new Exception("Insert for create failed"))
        }
      }

We want some tests to cover this logic as well. These are not beautiful or fully comprehensive tests, but hopefully they are illustrative of the of logic we are testing in the DAO. They are a bit on the verbose side.

  test("create when empty") {
    val futureCreate = InventoryDoubleRecordDao.create(database, TEST_SKU, 2, BIN_01)
    val createResult = Await.result(futureCreate, Duration.Inf)
    createResult should equal(InventoryDoubleRecord(None, TEST_SKU, 2, TRANSACTION.ADJUST, BIN_01))

    val futureFind = InventoryDoubleRecordDao.findAllRaw(database)
    val findResult: Seq[InventoryDoubleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should equal(List(InventoryDoubleRecord(Option(1), TEST_SKU, 2, TRANSACTION.ADJUST, BIN_01)))
  }

  test("create with existing record") {
    Await.result(InventoryDoubleRecordDao.create(database, TEST_SKU, 2, BIN_01), Duration.Inf)

    val futureUpdate = InventoryDoubleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    val updateResult= Await.result(futureUpdate, Duration.Inf)
    updateResult should equal(InventoryDoubleRecord(None, TEST_SKU, 1, TRANSACTION.ADJUST, BIN_01))

    val futureFindAllRaw = InventoryDoubleRecordDao.findAllRaw(database)
    val findResult: Seq[InventoryDoubleRecord] = Await.result(futureFindAllRaw, Duration.Inf)
    findResult should equal(List(
      InventoryDoubleRecord(Option(1), TEST_SKU, 2, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(Option(2), TEST_SKU, -1, TRANSACTION.ADJUST, BIN_01),
    ))
  }

Final Create/Insert/Update Code

This gives us the following create function:

  def create(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             location: String
            ): Future[InventoryDoubleRecord] = {
    val insert = for {
      // Find the current count for this location and SKU
      initGroupBy <- this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku).map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption

      // Insert a new record that will result in the desired qty
      _ <- {
        initGroupBy match {
          case None =>
            this += InventoryDoubleRecord(None, sku, qty, TRANSACTION.ADJUST, location)
          case Some((_, Some(existingQty))) =>
            logger.debug(s"FOUND record $qty - $existingQty")
            this += InventoryDoubleRecord(None, sku, qty - existingQty, TRANSACTION.ADJUST, location)
          case _ => DBIO.failed(new Exception("Insert for create failed"))
        }
      }

      // Return the updated value
      newRecordGroupBy <- this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku).map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption
      newRecordBySku <- {
        newRecordGroupBy match {
          case Some((_, Some(newQty))) =>
            DBIO.successful (InventoryDoubleRecord (None, sku, newQty, TRANSACTION.ADJUST, location) )
          case _ =>
            DBIO.failed(new Exception("Insert for create failed"))
        }
      }
    } yield newRecordBySku

    db.run(insert.transactionally)
  }

The reader may notice that this query is susceptible to problems with consistency when we have concurrent calls. We have not set an isolation level for our transaction, but just like our problems with inventory transfer http://honstain.com/inventory-transfer-row-locking/ we can get undesirable behavior if multiple requests to create for a given location/SKU overlap.

Demonstrate the Consistency Problem

If you use siege to pound on the service with a few users you can pretty quickly observe some undesirable behavior.

siege -v -c2 -r10 --content-type "application/json" -f siege_urls.txt

#### siege_urls.text ####
127.0.0.1:8080/double
127.0.0.1:8080/double POST {"sku": "SKU-01","qty": 1,"location": "LOC-01"}
127.0.0.1:8080/double POST {"sku": "SKU-01","qty": 17,"location": "LOC-01"}

We would hope to only ever see a quantity of 1 or 17 (with corresponding adjustment records in the DB).

#### Example Logging from Sacalatra Service ####
10:41:52.365 [scala-execution-context-global-35] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 2 for sku: SKU-01 location: LOC-01
10:41:52.372 [scala-execution-context-global-35] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 2 for sku: SKU-01 location: LOC-01
10:41:52.387 [qtp1637506559-12] DEBUG o.b.h.inventory.app.ToyInventory - GET: location: SKU-01 sku: LOC-01 qty: Some(17)
10:41:56.813 [qtp1637506559-17] DEBUG o.b.h.inventory.app.ToyInventory - GET: location: SKU-01 sku: LOC-01 qty: Some(32)
10:41:56.818 [scala-execution-context-global-39] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 1 existing: 32 for sku: SKU-01 location: LOC-01
10:41:56.827 [scala-execution-context-global-39] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 1 existing: 1 for sku: SKU-01 location: LOC-01
10:41:56.839 [scala-execution-context-global-38] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 1 for sku: SKU-01 location: LOC-01
10:41:56.862 [scala-execution-context-global-38] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 17 for sku: SKU-01 location: LOC-01

I would encourage you to play with several different isolation levels and observe how PostgreSQL handles this sort of query (read following by an insert).

db.run(insert.transactionally.withTransactionIsolation(TransactionIsolation.Serializable))

Summary of the Initial Create/Insert/Update Logic

We have created a basic design for tracking inventory using a DB schema based on double-entry accounting. It still has some gaps with consistency (just like our initial attempt that relied on a single DB record for each location and SKU pair), but hopefully this gives you some ideas.

Source code for this blog post: https://bitbucket.org/honstain/scalatra-double-record-transfer-service/src/master/

Increasing Consistency of the Create/Insert/Update Logic

One idea we can explore is taking a pessimistic lock on the location and SKU. What would that imply in our current schema?

• Using a SELECT FOR UPDATE would mean that we lock all the records needed to compute the current value, this would be worse (in terms of DB overhead to support locking) than our schema that used a single record to track the quantity.

We will instead create a new table just to support this locking behavior.

CREATE TABLE inventory_lock
(
  location text,
  sku text,
  revision integer,
  CONSTRAINT pk_lock PRIMARY KEY (location, sku)
);

class InventoryDoubleRecordLocks(tag: Tag) extends Table[(String, String, Int)](tag, "inventory_lock") {
  def location = column[String]("location")
  def sku = column[String]("sku")
  def revision = column[Int]("revision")
  def * = (location, sku, revision)
}

Given this additional table, here is one way we might include it in our create functions database transaction:

      createLock <- {
        TableQuery[InventoryDoubleRecordLocks].filter(x => x.location === location && x.sku === sku).forUpdate.result
      }

      _ <- {
        createLock match {
          case Seq((`location`, `sku`, _)) =>
            val updateLock = TableQuery[InventoryDoubleRecordLocks]
            val q = for { x <- updateLock if x.location === location && x.sku === sku } yield x.revision
            q.update(createLock.head._3 + 1)
          case _ =>
            // Create if no record lock existed
            TableQuery[InventoryDoubleRecordLocks] += (location, sku, 0)
        }
      }

This has two main pieces, attempt to read the record FOR UPDATE Then we support creating a new record if this is the first time the Location/SKU pair has been seen.

• A helpful reference here would be to review: https://www.postgresql.org/docs/11/explicit-locking.html

I make no claim that this is the best solution to the problem, but it illustrates one way to maintain consistency. This solution does not make use of foreign key constraints or joins.

Summary

We have taken a tour Scalatra and Slick while implementing a very rudimentary service for tracking physical inventory (tracking quantities of a SKU by location). There are many ways that you could solve this problem, and I have tried to outline some of the options and what the trade-offs are.

The primary goal of this set of blogs on this toy inventory system, was to learn and share (I was exploring as I went). I am still inexperienced with Scala and the ecosystem (while being reasonably comfortable with PostgreSQL).

I found Scalatra and Slick reasonably difficult to adapt to, probably because I am still trying to write Java and JDBI. I humbly admit my weakness here.

I had originally set out to compare the transfer logic between the single record design (one DB record to track the qty of a location/SKU pair) with the double-entry model covered in this post. I have implemented a transfer function (which you can find here https://bitbucket.org/honstain/scalatra-double-record-inventory) but I will not create a special blog post to cover it. I think the create example here is sufficient to illustrate the logic and I would like to move on from Scalatra and experiment with the Play framework https://www.playframework.com/.

Want to Know More About Double-Entry Accounting?

Some initial references that are worth considering if you would like to further familiarize yourself with double record/entry accounting:

• Martin Folwer has some excellent posts that I referenced
  • Start here for a nice primer on double-entry accounting along with some historical background on the practice https://www.martinfowler.com/eaaDev/AccountingNarrative.html
  • https://www.martinfowler.com/eaaDev/AccountingTransaction.html
  • https://www.martinfowler.com/eaaDev/Account.html
• StackOverflow has some interesting debates on the matter
  • https://stackoverflow.com/questions/287097/inventory-database-design
  • https://stackoverflow.com/questions/4373968/database-design-calculating-the-account-balance
• Michael Wigley authored an interesting article on double entry accounting
  • https://stackoverflow.com/questions/4373968/database-design-calculating-the-account-balance

In this post, we will explore an alternative database schema design for tracking physical inventory. Our previous posts focused on using a single database record to model a distinct location and SKU (location and SKU being represented as basic strings in this example). But what would it look like if we designed our schema around the idea of double-entry accounting? That would mean the quantity of a given location and SKU would be defined by the sum of multiple database records (we couldn't just look at a single record anymore to find its current quantity).

A good primer for double-entry accounting is Martin Fowler's blog post on the subject https://www.martinfowler.com/eaaDev/AccountingNarrative.html.

Previous Blog Posts In This Series

This post will significantly reference several of my previous blog posts. We now seek to draw a comparison on this double-entry schema to a design that uses a single record (for each location and SKU relationship). I would venture to guess that most developers would not start with a double-entry model.

• Part 1 - Creating a Scalatra Inventory Management Service
• Part 2 - Implementing Create/Update in Slick
• Part 3 - Inventory Management Transfer
• Part 4 - Inventory Management Transfer with Row Level Locking

Source Code

• A basic skeleton of a Scalatra service you could use to build as you go while reading: https://bitbucket.org/honstain/scalatra-single-record-transfer-service/ You would need to create a new DAO and wire up the REST endpoints and tests.
• The completed solution: https://bitbucket.org/honstain/scalatra-double-record-transfer-service/src/master/

Designing the Schema for Double-Entry

Each transfer (physical movement of goods from one location to another) will be modeled with two new records, one decrementing the qty from the source location and one incrementing the qty for the destination.

Starting with a single location LOC-01 that contains 2 units of SKU-01

If we wanted to move 1 unit of SKU-01 to the location LOC-02, instead of updating record id:1 we would create two new records.

This means that to calculate the current quantity of LOC-01 and SKU-01 we would need to sum the quantity across records id:1 and id:2.

Using this design, we are never updating old database records, we are only creating new ones.

All our operations (creating, moving, and decrementing inventory) would be handled by a DB insert. Because we treat existing records as immutable, there are fewer instances where the DB needs to manage the overhead of locking specific rows. We saw in our previous post how we ended up doing some fine-grained row-level locking in order to provide consistency. We ended up locking everything in the transaction, the source and the destination, which can have an impact on all the other database queries that might be running against that table.

Just like in our original example, let's start with a DAO and way to retrieve all the database records for testing.

package org.bitbucket.honstain.inventory.dao

import org.slf4j.{Logger, LoggerFactory}
import slick.jdbc.{PostgresProfile, TransactionIsolation}
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

object TRANSACTION {
  val ADJUST = "adjust"
  val TRANSFER = "transfer"
}

case class InventoryDoubleRecord(
                                  id: Option[Int],
                                  sku: String,
                                  qty: Int,
                                  txnType: String,
                                  location: String
                                )

class InventoryDoubleRecords(tag: Tag) extends Table[InventoryDoubleRecord](tag, "inventory_double") {
  def id = column[Int]("id", O.PrimaryKey, O.AutoInc)
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def txnType = column[String]("type")
  def location = column[String]("location")
  def * =
    (id.?, sku, qty, txnType, location) <> (InventoryDoubleRecord.tupled, InventoryDoubleRecord.unapply)
}

object InventoryDoubleRecordDao extends TableQuery(new InventoryDoubleRecords(_)) {

  val logger: Logger = LoggerFactory.getLogger(getClass)

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[InventoryDoubleRecord]] = {
    db.run(this.result)
  }

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[(String, String, Option[Int])]] = {
    val groupByQuery = this.groupBy(x => (x.sku, x.location))
      .map{ case ((sku, location), group) => (sku, location, group.map(_.qty).sum) }
      .result
    db.run(groupByQuery)
  }
}

We will also make a basic test to start us off.

package org.bitbucket.honstain.inventory.dao

import org.bitbucket.honstain.PostgresSpec

import org.scalatest.BeforeAndAfter
import org.scalatra.test.scalatest._
import slick.dbio.DBIO
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Await
import scala.concurrent.duration.Duration


class InventoryDoubleRecordDaoTests extends ScalatraFunSuite with BeforeAndAfter with PostgresSpec {

  def createInventoryTable: DBIO[Int] =
    sqlu"""
          CREATE TABLE inventory_double
          (
            id bigserial NOT NULL,
            sku text,
            qty integer,
            type text,
            location text,
            CONSTRAINT pk_double PRIMARY KEY (id)
          );
      """
  def dropInventoryTable: DBIO[Int] =
    sqlu"""
          DROP TABLE IF EXISTS inventory_double;
      """

  before {
    Await.result(database.run(createInventoryTable), Duration.Inf)
  }

  after {
    Await.result(database.run(dropInventoryTable), Duration.Inf)
  }

  val TEST_SKU = "NewSku"
  val BIN_01 = "Bin-01"
  val BIN_02 = "Bin-02"

  test("findAll when empty") {
    val futureFind = InventoryDoubleRecordDao.findAll(database)
    val findResult: Seq[InventoryDoubleRecord] = Await.result(futureFind, Duration.Inf)

    findResult should equal(List())
  }
  
    test("findAll with single location and SKU but multiple records") {
    val inventoryTable = TableQuery[InventoryDoubleRecords] ++= Seq(
      InventoryDoubleRecord(None, TEST_SKU, 1, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(None, TEST_SKU, 3, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(None, TEST_SKU, -1, TRANSACTION.ADJUST, BIN_01)
    )
    Await.result(database.run(inventoryTable), Duration.Inf)

    val futureFind = InventoryDoubleRecordDao.findAll(database)
    val findResult: Seq[(String, String, Option[Int])] = Await.result(futureFind, Duration.Inf)

    findResult should equal(List((TEST_SKU, BIN_01, Some(3))))
  }

  test("findAll with multiple location+SKU and multiple records") {
    val inventoryTable = TableQuery[InventoryDoubleRecords] ++= Seq(
      InventoryDoubleRecord(None, TEST_SKU, 1, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(None, TEST_SKU, 3, TRANSACTION.ADJUST, BIN_02),
      InventoryDoubleRecord(None, TEST_SKU, -1, TRANSACTION.ADJUST, BIN_01)
    )
    Await.result(database.run(inventoryTable), Duration.Inf)

    val futureFind = InventoryDoubleRecordDao.findAll(database)
    val findResult: Seq[(String, String, Option[Int])] = Await.result(futureFind, Duration.Inf)

    findResult should contain only ((TEST_SKU, BIN_02, Some(3)), (TEST_SKU, BIN_01, Some(0)))
  }
}

This should look very similar to our original example (that modeled each location and SKU relationship with a single DB record), except for the fact that we now do a SQL aggregation on the results to find all the current inventory information.

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[(String, String, Option[Int])]] = {
    val groupByQuery = this.groupBy(x => (x.sku, x.location))
      .map{ case ((sku, location), group) => (sku, location, group.map(_.qty).sum) }
      .result
    db.run(groupByQuery)
  }

This Slick query is roughly equivalent to the following SQL:

SELECT sku, location, SUM(qty)
FROM inventory_double
GROUP BY sku, location

Why the SQL aggregation and tuple return type? How we model the record in the database with the class InventoryDoubleRecord is now somewhat abstracted from how our business logic might want to handle the date. The InventoryDoubleRecord class has id and txnType columns which are not necessarily applicable when a client is asking the service how many items are in a location or how many units of a SKU are available. Hence we are returning a tuple from our findAll function, the reader could map this to a new class if they preferred.

Create/Insert/Update Logic

Now we want the ability to create new inventory, and update the qty of an existing location + SKU. You might refer to this sort of logic as an adjustment (which I track via the TRANSACTION enum). Where previously we could take a lock on a single record and do an atomic create or update:

INSERT INTO inventory_single (sku, qty, location)
VALUES ('SKU-01', 3, 'LOC-01')
ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
DO UPDATE SET qty = EXCLUDED.qty;

Now we have to consider multiple rows in order to find out the current quantity of a location and SKU. Our initial function definition could look like:

  def create(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             location: String
            ): Future[InventoryDoubleRecord] = {
    val insert = for {
      // Find the current count for this Location and SKU
      initGroupBy <- // TODO - query to find existing qty

      // Insert a new record that will result in the desired qty
      _ <- // TODO - insert a new record

      // Return the updated value
      newRecordBySku <- // TODO return the current qty for the SKU and Location
    } yield newRecordBySku

    db.run(insert.transactionally)
  }

The structure we just outlined uses a Slick transaction and for comprehension to group a set of queries (lookup, insert, and lookup). We start first by doing the lookup component.

• Lookup existing qty - find the qty for the Location/SKU pair if it exists
  • A basic Slick aggregartion with sum, will give us a result of something like Future[Seq[(String, String, Option[Int])]]. We should be dealing with just a single record here given our schema design so we can use headOption to grab the head of the Sequence.

this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku)
        .map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption

• Insert - create a new database record.
  • Case 1 - We found no existing records for the SKU and Location pair.
  • Case 2 - We have an existing record and the QTY is needed to determine what the new qty to insert will be.

      _ <- {
        initGroupBy match {
          case None =>
            this += InventoryDoubleRecord(Some(0), sku, qty, TRANSACTION.ADJUST, location)
          case Some((_, Some(existingQty))) =>
            logger.debug(s"FOUND record $qty - $existingQty")
            this += InventoryDoubleRecord(Some(0), sku, qty - existingQty, TRANSACTION.ADJUST, location)
          case _ => DBIO.failed(new Exception("Insert for create failed"))
        }
      }

• Lookup current quantity - get the current qty for the Location/SKU pair after our insert.
  • I made an effort to use the return type InventoryDoubleRecord class so we could more easily draw a parallel with our single record schema design. It also illustrates an example of mapping the results (even I am not personally a fan of this code).

      newRecordGroupBy <- this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku).map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption
      newRecordBySku <- {
        newRecordGroupBy match {
          case Some((_, Some(newQty))) =>
            DBIO.successful (InventoryDoubleRecord (None, sku, newQty, TRANSACTION.ADJUST, location) )
          case _ =>
            DBIO.failed(new Exception("Insert for create failed"))
        }
      }

We want some tests to cover this logic as well. These are not beautiful or fully comprehensive tests, but hopefully they are illustrative of the of logic we are testing in the DAO. They are a bit on the verbose side.

  test("create when empty") {
    val futureCreate = InventoryDoubleRecordDao.create(database, TEST_SKU, 2, BIN_01)
    val createResult = Await.result(futureCreate, Duration.Inf)
    createResult should equal(InventoryDoubleRecord(None, TEST_SKU, 2, TRANSACTION.ADJUST, BIN_01))

    val futureFind = InventoryDoubleRecordDao.findAllRaw(database)
    val findResult: Seq[InventoryDoubleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should equal(List(InventoryDoubleRecord(Option(1), TEST_SKU, 2, TRANSACTION.ADJUST, BIN_01)))
  }

  test("create with existing record") {
    Await.result(InventoryDoubleRecordDao.create(database, TEST_SKU, 2, BIN_01), Duration.Inf)

    val futureUpdate = InventoryDoubleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    val updateResult= Await.result(futureUpdate, Duration.Inf)
    updateResult should equal(InventoryDoubleRecord(None, TEST_SKU, 1, TRANSACTION.ADJUST, BIN_01))

    val futureFindAllRaw = InventoryDoubleRecordDao.findAllRaw(database)
    val findResult: Seq[InventoryDoubleRecord] = Await.result(futureFindAllRaw, Duration.Inf)
    findResult should equal(List(
      InventoryDoubleRecord(Option(1), TEST_SKU, 2, TRANSACTION.ADJUST, BIN_01),
      InventoryDoubleRecord(Option(2), TEST_SKU, -1, TRANSACTION.ADJUST, BIN_01),
    ))
  }

Final Create/Insert/Update Code

This gives us the following create function:

  def create(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             location: String
            ): Future[InventoryDoubleRecord] = {
    val insert = for {
      // Find the current count for this location and SKU
      initGroupBy <- this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku).map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption

      // Insert a new record that will result in the desired qty
      _ <- {
        initGroupBy match {
          case None =>
            this += InventoryDoubleRecord(None, sku, qty, TRANSACTION.ADJUST, location)
          case Some((_, Some(existingQty))) =>
            logger.debug(s"FOUND record $qty - $existingQty")
            this += InventoryDoubleRecord(None, sku, qty - existingQty, TRANSACTION.ADJUST, location)
          case _ => DBIO.failed(new Exception("Insert for create failed"))
        }
      }

      // Return the updated value
      newRecordGroupBy <- this.filter(_.sku === sku).filter(_.location === location)
        .groupBy(x => x.sku).map{ case (_, group) => (sku, group.map(_.qty).sum) }
        .result.headOption
      newRecordBySku <- {
        newRecordGroupBy match {
          case Some((_, Some(newQty))) =>
            DBIO.successful (InventoryDoubleRecord (None, sku, newQty, TRANSACTION.ADJUST, location) )
          case _ =>
            DBIO.failed(new Exception("Insert for create failed"))
        }
      }
    } yield newRecordBySku

    db.run(insert.transactionally)
  }

The reader may notice that this query is susceptible to problems with consistency when we have concurrent calls. We have not set an isolation level for our transaction, but just like our problems with inventory transfer http://honstain.com/inventory-transfer-row-locking/ we can get undesirable behavior if multiple requests to create for a given location/SKU overlap.

Demonstrate the Consistency Problem

If you use siege to pound on the service with a few users you can pretty quickly observe some undesirable behavior.

siege -v -c2 -r10 --content-type "application/json" -f siege_urls.txt

#### siege_urls.text ####
127.0.0.1:8080/double
127.0.0.1:8080/double POST {"sku": "SKU-01","qty": 1,"location": "LOC-01"}
127.0.0.1:8080/double POST {"sku": "SKU-01","qty": 17,"location": "LOC-01"}

We would hope to only ever see a quantity of 1 or 17 (with corresponding adjustment records in the DB).

#### Example Logging from Sacalatra Service ####
10:41:52.365 [scala-execution-context-global-35] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 2 for sku: SKU-01 location: LOC-01
10:41:52.372 [scala-execution-context-global-35] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 2 for sku: SKU-01 location: LOC-01
10:41:52.387 [qtp1637506559-12] DEBUG o.b.h.inventory.app.ToyInventory - GET: location: SKU-01 sku: LOC-01 qty: Some(17)
10:41:56.813 [qtp1637506559-17] DEBUG o.b.h.inventory.app.ToyInventory - GET: location: SKU-01 sku: LOC-01 qty: Some(32)
10:41:56.818 [scala-execution-context-global-39] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 1 existing: 32 for sku: SKU-01 location: LOC-01
10:41:56.827 [scala-execution-context-global-39] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 1 existing: 1 for sku: SKU-01 location: LOC-01
10:41:56.839 [scala-execution-context-global-38] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 1 for sku: SKU-01 location: LOC-01
10:41:56.862 [scala-execution-context-global-38] DEBUG o.b.h.i.d.InventoryDoubleRecordDao$ - INSERT need qty: 17 existing: 17 for sku: SKU-01 location: LOC-01

I would encourage you to play with several different isolation levels and observe how PostgreSQL handles this sort of query (read following by an insert).

db.run(insert.transactionally.withTransactionIsolation(TransactionIsolation.Serializable))

Summary of the Initial Create/Insert/Update Logic

We have created a basic design for tracking inventory using a DB schema based on double-entry accounting. It still has some gaps with consistency (just like our initial attempt that relied on a single DB record for each location and SKU pair), but hopefully this gives you some ideas.

Source code for this blog post: https://bitbucket.org/honstain/scalatra-double-record-transfer-service/src/master/

Increasing Consistency of the Create/Insert/Update Logic

One idea we can explore is taking a pessimistic lock on the location and SKU. What would that imply in our current schema?

• Using a SELECT FOR UPDATE would mean that we lock all the records needed to compute the current value, this would be worse (in terms of DB overhead to support locking) than our schema that used a single record to track the quantity.

We will instead create a new table just to support this locking behavior.

CREATE TABLE inventory_lock
(
  location text,
  sku text,
  revision integer,
  CONSTRAINT pk_lock PRIMARY KEY (location, sku)
);

class InventoryDoubleRecordLocks(tag: Tag) extends Table[(String, String, Int)](tag, "inventory_lock") {
  def location = column[String]("location")
  def sku = column[String]("sku")
  def revision = column[Int]("revision")
  def * = (location, sku, revision)
}

Given this additional table, here is one way we might include it in our create functions database transaction:

      createLock <- {
        TableQuery[InventoryDoubleRecordLocks].filter(x => x.location === location && x.sku === sku).forUpdate.result
      }

      _ <- {
        createLock match {
          case Seq((`location`, `sku`, _)) =>
            val updateLock = TableQuery[InventoryDoubleRecordLocks]
            val q = for { x <- updateLock if x.location === location && x.sku === sku } yield x.revision
            q.update(createLock.head._3 + 1)
          case _ =>
            // Create if no record lock existed
            TableQuery[InventoryDoubleRecordLocks] += (location, sku, 0)
        }
      }

This has two main pieces, attempt to read the record FOR UPDATE Then we support creating a new record if this is the first time the Location/SKU pair has been seen.

• A helpful reference here would be to review: https://www.postgresql.org/docs/11/explicit-locking.html

I make no claim that this is the best solution to the problem, but it illustrates one way to maintain consistency. This solution does not make use of foreign key constraints or joins.

Summary

We have taken a tour Scalatra and Slick while implementing a very rudimentary service for tracking physical inventory (tracking quantities of a SKU by location). There are many ways that you could solve this problem, and I have tried to outline some of the options and what the trade-offs are.

The primary goal of this set of blogs on this toy inventory system, was to learn and share (I was exploring as I went). I am still inexperienced with Scala and the ecosystem (while being reasonably comfortable with PostgreSQL).

I found Scalatra and Slick reasonably difficult to adapt to, probably because I am still trying to write Java and JDBI. I humbly admit my weakness here.

I had originally set out to compare the transfer logic between the single record design (one DB record to track the qty of a location/SKU pair) with the double-entry model covered in this post. I have implemented a transfer function (which you can find here https://bitbucket.org/honstain/scalatra-double-record-inventory) but I will not create a special blog post to cover it. I think the create example here is sufficient to illustrate the logic and I would like to move on from Scalatra and experiment with the Play framework https://www.playframework.com/.

Want to Know More About Double-Entry Accounting?

Some initial references that are worth considering if you would like to further familiarize yourself with double record/entry accounting:

• Martin Folwer has some excellent posts that I referenced
  • Start here for a nice primer on double-entry accounting along with some historical background on the practice https://www.martinfowler.com/eaaDev/AccountingNarrative.html
  • https://www.martinfowler.com/eaaDev/AccountingTransaction.html
  • https://www.martinfowler.com/eaaDev/Account.html
• StackOverflow has some interesting debates on the matter
  • https://stackoverflow.com/questions/287097/inventory-database-design
  • https://stackoverflow.com/questions/4373968/database-design-calculating-the-account-balance
• Michael Wigley authored an interesting article on double entry accounting
  • https://stackoverflow.com/questions/4373968/database-design-calculating-the-account-balance

In our previous post, we designed a basic system to track the physical transfer of goods between two physical locations.

Previous posts for our inventory service:

• Part 1 - Creating a Scalatra Inventory Management Service
• Part 2 - Implementing Create/Update in Slick
• Part 3 - Inventory Management Transfer

WARNING - This may be difficult to follow if you haven't been working through the previous posts. Reviewing this repository that implements this material covered so far may help you https://bitbucket.org/honstain/scalatra-single-record-transfer-service/src/master/

I created a basic diagram to help better visualize the sort of relationship and model we are dealing with in this walk-through.

Enforcing Consistency in the Database

When we left off in our previous post we had a solution that worked for the simple happy path, but would quickly manifest undesirable behavior under mild concurrency.

Our initial attempts focused on using a more restricted database isolation level. But as we saw from our testing, it exposed a lot of errors to the client (while using Serializable the database would detect and abort our transactions). We could attempt to retry, but we would need to think through any approach with retry holistically to make sure retry was still valid given the new state of the database.

Possible options consider going forward:

• Retry our database serialization failures (if using the Serializable isolation level).
  • Remember that there are non-trivial performance implications to serializing, but like with anything it would be to your benefit to experiment and make an informed decision for your use case and read patterns.
• Pessimistic row level locking - we use the database to block access specific rows while we execute our logic and do the update. https://www.postgresql.org/docs/9.0/sql-select.html#SQL-FOR-UPDATE-SHARE
• Optimistic offline lock - by assuming the risk of conflict is low (especially if multiple services are involved) we rely on a revision id and some additional logic in the client/callers identify potential issues.
  • Martin Flower has a great reference https://martinfowler.com/eaaCatalog/optimisticOfflineLock.html

These are just a few directions you could go, you could even attempt to circumvent this problem entirely with some alternative technology solutions. Because this series of blog posts are centered around Scala, relational databases, and microservices, I will focus our exploration ways to work the problem using traditional database techniques.

Row Level Locking

Our next attempt will be to use row level locking to help us prevent multiple concurrent users from conflicting with one another.

A excellent reference to review before continuing would be to review the PostgreSQL documentation on select for update SQL. https://www.postgresql.org/docs/9.0/sql-select.html#SQL-FOR-UPDATE-SHARE

Slick provides us access to PostgreSQL row-level locking with the forUpdate method on the Query class.

• Before we add row level locking - this is our original transfer function:

  def transfer(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               fromLocation: String,
               toLocation: String
              ): Future[Int] = {

    val insert = for {
      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
      }
      createUpdateDestination <- {
        toRecord match {
          case Some(InventorySingleRecord(_, `sku`, destQty, `toLocation`)) =>
            // Update
            val q = for { x <- this if x.location === toLocation && x.sku === sku } yield x.qty
            q.update(destQty + qty)
          case _ =>
            // Create - this is likely susceptible to write skew
            this += InventorySingleRecord(Option.empty, sku, qty, toLocation)
        }
      }
      updateSource <- {
        fromRecord match {
          case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>

            val destinationQty: Int = if (toRecord.isDefined) toRecord.get.qty else 0
            logger.debug(s"Transfer $qty from:$fromLocation (had qty:$srcQty) to $toLocation (had qty:$destinationQty)")

            val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
            q.update(srcQty - qty)
          case _ =>
            DBIO.failed(new Exception("Failed to find source location"))
        }
      }
    } yield updateSource
    db.run(insert.transactionally)
  }

• After we just need to add forUpdate to the initial select queries.

      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).forUpdate.result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).forUpdate.result.headOption
      }

Let's test this change by trying to run more than one transfer in parallel. We will use the same approach from our previous post (creating the initial transfer functionality), where we used the Linux command line tool siege.

siege -v -c2 -r10 --content-type "application/json" -f siege_urls.txt

Please make sure your database data looks like the following:

The results of our concurrent requests looked like this (we had a few failures).

Looking to the logs from Scalatra, you can see PostgreSQL encountered a deadlock, looking at the response times also shows how painful the deadlock was to identify for the database.

At some point the requests overlapped in such a way that our fictitious user 929 had taken a lock on LOC-01 and then wanted to lock LOC-02 only to find that user 629 already had a lock on LOC-02 and wanted LOC-01. It would be a good idea to review the PostgreSQL documentation on deadlocks https://www.postgresql.org/docs/9.5/explicit-locking.html. I found it helpful to turn on query logging in PostgreSQL https://stackoverflow.com/questions/722221/how-to-log-postgresql-queries if you want even more information about what is happening.

2019-04-18 07:22:23.790 PDT [8195] toyinventory@toyinventory ERROR:  deadlock detected
2019-04-18 07:22:23.790 PDT [8195] toyinventory@toyinventory DETAIL:  Process 8195 waits for ShareLock on transaction 14078; blocked by process 8193.
	Process 8193 waits for ShareLock on transaction 14079; blocked by process 8195.
	Process 8195: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-02') and ("sku" = 'SKU-01') for update 
	Process 8193: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-01') and ("sku" = 'SKU-01') for update 

How Do We Fix This?

As described in the documentation for PostgreSQL https://www.postgresql.org/docs/9.5/explicit-locking.html#LOCKING-DEADLOCKS

The best defense against deadlocks is generally to avoid them by being certain that all applications using a database acquire locks on multiple objects in a consistent order.

How would we go about acquiring our locks in a consistent order? In our code, the first lock we take is the destination location (note the ordering of our current operations in our transfer DAO method is fairly arbitrary).

  def transfer(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               fromLocation: String,
               toLocation: String,
               userId: String
              ): Future[Int] = {

    val insert = for {
      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).forUpdate.result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).forUpdate.result.headOption
      }

What if we added a new step at the very beginning that was only responsible for taking out database locks in a consistent order?

We can start by always taking our first lock on the smallest (by ordering of the location string) location and our second lock on the largest.

val locations = List(fromLocation, toLocation)
val firstLocationToLock = locations.min
val secondLocationToLock = locations.max

Then add two more queries to our Slick for-comprehension. In this case, we can ignore the response, I leave it as an exercise to the reader if they want to reorganize this Slick query into only 4 database queries (I have chosen to be wasteful in an effort to be simple to understand for the purpose of illustration).

    val locations = Seq(fromLocation, toLocation)
    val firstLocationToLock = locations.min
    val secondLocationToLock = locations.max

    val insert = for {
      _ <- {
        this.filter(x => x.location === firstLocationToLock && x.sku === sku).forUpdate.result.headOption
      }
      _ <- {
        this.filter(x => x.location === secondLocationToLock && x.sku === sku).forUpdate.result.headOption
      }
      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
      }

With our changes, lets make sure the automated tests still pass and then attempt to do concurrent transfers.

These results look much more promising than our previous attempts. You should review the Scalatra service logs to confirm the result. We can review the PostgreSQL query logs to see if the queries are matching our expectations.

2019-04-18 08:08:13.925 PDT [11853] toyinventory@toyinventory LOG:  execute S_2: BEGIN
2019-04-18 08:08:13.925 PDT [11853] toyinventory@toyinventory LOG:  execute S_3: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-01') and ("sku" = 'SKU-01') for update 
2019-04-18 08:08:13.930 PDT [11853] toyinventory@toyinventory LOG:  execute S_4: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-02') and ("sku" = 'SKU-01') for update 
2019-04-18 08:08:13.933 PDT [11853] toyinventory@toyinventory LOG:  execute S_6: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-01') and ("sku" = 'SKU-01')
2019-04-18 08:08:13.956 PDT [11853] toyinventory@toyinventory LOG:  execute S_5: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-02') and ("sku" = 'SKU-01')
2019-04-18 08:08:13.959 PDT [11853] toyinventory@toyinventory LOG:  execute S_8: update "inventory_single" set "qty" = $1 where ("inventory_single"."location" = 'LOC-01') and ("inventory_single"."sku" = 'SKU-01')
2019-04-18 08:08:13.959 PDT [11853] toyinventory@toyinventory DETAIL:  parameters: $1 = '2'
2019-04-18 08:08:13.963 PDT [11853] toyinventory@toyinventory LOG:  execute S_7: update "inventory_single" set "qty" = $1 where ("inventory_single"."location" = 'LOC-02') and ("inventory_single"."sku" = 'SKU-01')
2019-04-18 08:08:13.963 PDT [11853] toyinventory@toyinventory DETAIL:  parameters: $1 = '0'
2019-04-18 08:08:13.964 PDT [11853] toyinventory@toyinventory LOG:  execute S_1: COMMIT

This is pretty significant progress if you compare these results to our initial implementation. At the cost of row level locking, we can leverage our database to provide a pretty consistent experience for the caller.

Summary

In this and the previous post we have worked our way from a very basic solution to one that makes some trade-offs with locking but is able to provide some useful consistency. There are a number of ways to approach this problem, and we have made an effort to explore several (including some less successful attempts like utilizing a more aggressive isolation level).

Hopefully, you found this useful if you were looking for examples designing systems with relational databases or applications of Scala and Slick.

In our previous post, we designed a basic system to track the physical transfer of goods between two physical locations.

Previous posts for our inventory service:

• Part 1 - Creating a Scalatra Inventory Management Service
• Part 2 - Implementing Create/Update in Slick
• Part 3 - Inventory Management Transfer

WARNING - This may be difficult to follow if you haven't been working through the previous posts. Reviewing this repository that implements this material covered so far may help you https://bitbucket.org/honstain/scalatra-single-record-transfer-service/src/master/

I created a basic diagram to help better visualize the sort of relationship and model we are dealing with in this walk-through.

Enforcing Consistency in the Database

When we left off in our previous post we had a solution that worked for the simple happy path, but would quickly manifest undesirable behavior under mild concurrency.

Our initial attempts focused on using a more restricted database isolation level. But as we saw from our testing, it exposed a lot of errors to the client (while using Serializable the database would detect and abort our transactions). We could attempt to retry, but we would need to think through any approach with retry holistically to make sure retry was still valid given the new state of the database.

Possible options consider going forward:

• Retry our database serialization failures (if using the Serializable isolation level).
  • Remember that there are non-trivial performance implications to serializing, but like with anything it would be to your benefit to experiment and make an informed decision for your use case and read patterns.
• Pessimistic row level locking - we use the database to block access specific rows while we execute our logic and do the update. https://www.postgresql.org/docs/9.0/sql-select.html#SQL-FOR-UPDATE-SHARE
• Optimistic offline lock - by assuming the risk of conflict is low (especially if multiple services are involved) we rely on a revision id and some additional logic in the client/callers identify potential issues.
  • Martin Flower has a great reference https://martinfowler.com/eaaCatalog/optimisticOfflineLock.html

These are just a few directions you could go, you could even attempt to circumvent this problem entirely with some alternative technology solutions. Because this series of blog posts are centered around Scala, relational databases, and microservices, I will focus our exploration ways to work the problem using traditional database techniques.

Row Level Locking

Our next attempt will be to use row level locking to help us prevent multiple concurrent users from conflicting with one another.

A excellent reference to review before continuing would be to review the PostgreSQL documentation on select for update SQL. https://www.postgresql.org/docs/9.0/sql-select.html#SQL-FOR-UPDATE-SHARE

Slick provides us access to PostgreSQL row-level locking with the forUpdate method on the Query class.

• Before we add row level locking - this is our original transfer function:

  def transfer(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               fromLocation: String,
               toLocation: String
              ): Future[Int] = {

    val insert = for {
      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
      }
      createUpdateDestination <- {
        toRecord match {
          case Some(InventorySingleRecord(_, `sku`, destQty, `toLocation`)) =>
            // Update
            val q = for { x <- this if x.location === toLocation && x.sku === sku } yield x.qty
            q.update(destQty + qty)
          case _ =>
            // Create - this is likely susceptible to write skew
            this += InventorySingleRecord(Option.empty, sku, qty, toLocation)
        }
      }
      updateSource <- {
        fromRecord match {
          case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>

            val destinationQty: Int = if (toRecord.isDefined) toRecord.get.qty else 0
            logger.debug(s"Transfer $qty from:$fromLocation (had qty:$srcQty) to $toLocation (had qty:$destinationQty)")

            val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
            q.update(srcQty - qty)
          case _ =>
            DBIO.failed(new Exception("Failed to find source location"))
        }
      }
    } yield updateSource
    db.run(insert.transactionally)
  }

• After we just need to add forUpdate to the initial select queries.

      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).forUpdate.result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).forUpdate.result.headOption
      }

Let's test this change by trying to run more than one transfer in parallel. We will use the same approach from our previous post (creating the initial transfer functionality), where we used the Linux command line tool siege.

siege -v -c2 -r10 --content-type "application/json" -f siege_urls.txt

Please make sure your database data looks like the following:

The results of our concurrent requests looked like this (we had a few failures).

Looking to the logs from Scalatra, you can see PostgreSQL encountered a deadlock, looking at the response times also shows how painful the deadlock was to identify for the database.

At some point the requests overlapped in such a way that our fictitious user 929 had taken a lock on LOC-01 and then wanted to lock LOC-02 only to find that user 629 already had a lock on LOC-02 and wanted LOC-01. It would be a good idea to review the PostgreSQL documentation on deadlocks https://www.postgresql.org/docs/9.5/explicit-locking.html. I found it helpful to turn on query logging in PostgreSQL https://stackoverflow.com/questions/722221/how-to-log-postgresql-queries if you want even more information about what is happening.

2019-04-18 07:22:23.790 PDT [8195] toyinventory@toyinventory ERROR:  deadlock detected
2019-04-18 07:22:23.790 PDT [8195] toyinventory@toyinventory DETAIL:  Process 8195 waits for ShareLock on transaction 14078; blocked by process 8193.
	Process 8193 waits for ShareLock on transaction 14079; blocked by process 8195.
	Process 8195: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-02') and ("sku" = 'SKU-01') for update 
	Process 8193: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-01') and ("sku" = 'SKU-01') for update 

How Do We Fix This?

As described in the documentation for PostgreSQL https://www.postgresql.org/docs/9.5/explicit-locking.html#LOCKING-DEADLOCKS

The best defense against deadlocks is generally to avoid them by being certain that all applications using a database acquire locks on multiple objects in a consistent order.

How would we go about acquiring our locks in a consistent order? In our code, the first lock we take is the destination location (note the ordering of our current operations in our transfer DAO method is fairly arbitrary).

  def transfer(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               fromLocation: String,
               toLocation: String,
               userId: String
              ): Future[Int] = {

    val insert = for {
      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).forUpdate.result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).forUpdate.result.headOption
      }

What if we added a new step at the very beginning that was only responsible for taking out database locks in a consistent order?

We can start by always taking our first lock on the smallest (by ordering of the location string) location and our second lock on the largest.

val locations = List(fromLocation, toLocation)
val firstLocationToLock = locations.min
val secondLocationToLock = locations.max

Then add two more queries to our Slick for-comprehension. In this case, we can ignore the response, I leave it as an exercise to the reader if they want to reorganize this Slick query into only 4 database queries (I have chosen to be wasteful in an effort to be simple to understand for the purpose of illustration).

    val locations = Seq(fromLocation, toLocation)
    val firstLocationToLock = locations.min
    val secondLocationToLock = locations.max

    val insert = for {
      _ <- {
        this.filter(x => x.location === firstLocationToLock && x.sku === sku).forUpdate.result.headOption
      }
      _ <- {
        this.filter(x => x.location === secondLocationToLock && x.sku === sku).forUpdate.result.headOption
      }
      toRecord <- {
        this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
      }
      fromRecord <- {
        this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
      }

With our changes, lets make sure the automated tests still pass and then attempt to do concurrent transfers.

These results look much more promising than our previous attempts. You should review the Scalatra service logs to confirm the result. We can review the PostgreSQL query logs to see if the queries are matching our expectations.

2019-04-18 08:08:13.925 PDT [11853] toyinventory@toyinventory LOG:  execute S_2: BEGIN
2019-04-18 08:08:13.925 PDT [11853] toyinventory@toyinventory LOG:  execute S_3: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-01') and ("sku" = 'SKU-01') for update 
2019-04-18 08:08:13.930 PDT [11853] toyinventory@toyinventory LOG:  execute S_4: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-02') and ("sku" = 'SKU-01') for update 
2019-04-18 08:08:13.933 PDT [11853] toyinventory@toyinventory LOG:  execute S_6: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-01') and ("sku" = 'SKU-01')
2019-04-18 08:08:13.956 PDT [11853] toyinventory@toyinventory LOG:  execute S_5: select "id", "sku", "qty", "location" from "inventory_single" where ("location" = 'LOC-02') and ("sku" = 'SKU-01')
2019-04-18 08:08:13.959 PDT [11853] toyinventory@toyinventory LOG:  execute S_8: update "inventory_single" set "qty" = $1 where ("inventory_single"."location" = 'LOC-01') and ("inventory_single"."sku" = 'SKU-01')
2019-04-18 08:08:13.959 PDT [11853] toyinventory@toyinventory DETAIL:  parameters: $1 = '2'
2019-04-18 08:08:13.963 PDT [11853] toyinventory@toyinventory LOG:  execute S_7: update "inventory_single" set "qty" = $1 where ("inventory_single"."location" = 'LOC-02') and ("inventory_single"."sku" = 'SKU-01')
2019-04-18 08:08:13.963 PDT [11853] toyinventory@toyinventory DETAIL:  parameters: $1 = '0'
2019-04-18 08:08:13.964 PDT [11853] toyinventory@toyinventory LOG:  execute S_1: COMMIT

This is pretty significant progress if you compare these results to our initial implementation. At the cost of row level locking, we can leverage our database to provide a pretty consistent experience for the caller.

Summary

In this and the previous post we have worked our way from a very basic solution to one that makes some trade-offs with locking but is able to provide some useful consistency. There are a number of ways to approach this problem, and we have made an effort to explore several (including some less successful attempts like utilizing a more aggressive isolation level).

Hopefully, you found this useful if you were looking for examples designing systems with relational databases or applications of Scala and Slick.

Continuing in our series of posts about creating a basic Scalatra service for managing inventory, we would now like to implement the persistence logic to transfer inventory from one location to another.

Previous posts for our inventory service:

• Creating a Scalatra Inventory Management Service
• Implementing Create/Update in Slick

WARNING - This may be difficult to follow if you haven't been working through the previous posts. Reviewing this repository that implements this material covered so far may help you https://bitbucket.org/honstain/scalatra-single-record-transfer-service/src/master/

Transfer Inventory Between Locations

NOTE - I am going to intentionally start with naive implementation and demonstrate testing it (exposing issues). We will iterate on the design together.

Let's establish some basic requirements or expectations for this logic. We may initially relax some of these requirements to illustrative purposes (but this is where we are going).

• The source location must exist when attempting to transfer a SKU+qty from a source location to a destination location.
• The source location has enough inventory to supply the requested qty being transferred. Said another way, we will not support going negative.

To illustrate, if we wanted to transfer 1 unit of 'SKU-01' from location 'LOC-01' to 'LOC-02'.

We will want to remove one from 'LOC-01' and then increase the quantity of 'LOC-02'. An initial test to help us validate this behavior for our DAO might look like:

def createInventoryHelper(sku: String, qty: Int, location: String): InventorySingleRecord = {
  val create = InventorySingleRecordDao.create(database, sku, qty, location)
  Await.result(create, Duration.Inf).get
}
  
test("transfer") {
  createInventoryHelper(TEST_SKU, 1, BIN_01)
  createInventoryHelper(TEST_SKU, 0, BIN_02)

  val futureTrans = InventorySingleRecordDao.transfer(database, TEST_SKU, 1, BIN_01, BIN_02)
  Await.result(futureTrans, Duration.Inf)

  val futureFind = InventorySingleRecordDao.findAll(database)
  val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)

  findResult should contain only (
    InventorySingleRecord(Some(1), "NewSku", 0, BIN_01),
    InventorySingleRecord(Some(2), "NewSku", 1, BIN_02),
  )
}

Now to implement the InventorySingleRecordDao.transfer logic we can reference the upsert logic from our previous post that uses the Scala for comprehension and a database transaction. We can start by just modifying the source location and ignore the destination location (the test won't pass, but we will be able to validate our transfer logic incrementally).

This gives us a basic overview of the transfer function in our DAO. We have a for comprehension with the query to retrieve the database record for the source (fromLocation) and then attempt to modify it (there is basic handling to address the possibility that we don't find the source record.

def transfer(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             fromLocation: String,
             toLocation: String
            ): Future[Int] = {

  val insert = for {
    fromRecord <- {
      this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
    }
    updateSource <- {
      fromRecord match {
        case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>
          val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
          q.update(srcQty - qty)
        case _ =>
          DBIO.failed(new Exception("Failed to find source location"))
      }
    }
  } yield updateSource
  db.run(insert.transactionally)
}

Running the test that just created, we will get a failure, but hopefully, be able to see that the source 'Bin-01' is decremented.

Vector(
	InventorySingleRecord(Some(2),NewSku,0,Bin-02),
	InventorySingleRecord(Some(1),NewSku,0,Bin-01))
did not contain only (
	InventorySingleRecord(Some(1),NewSku,0,Bin-01), 
	InventorySingleRecord(Some(2),NewSku,1,Bin-02))

Now we need to update the destination record.

Just like when we updated the source location, we will want to query for it, but it is more likely that this record does not already exist (at least in this example where we assume physical inventory already exists in a source location, but its much more likely that the sku+location combination of the destination is unknown to the database - remember that those two columns are integral to our design).

toRecord <- {
  this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
}

Now that we possibly have a record for the destination, we can try to update or create. This should be very familiar if you worked through the upsert logic in my previous post.

createUpdateDestination <- {
  toRecord match {
    case Some(InventorySingleRecord(_, `sku`, destQty, `toLocation`)) =>
      // Update
      logger.debug(s"Transfer from:$fromLocation to $toLocation found $destQty in destination")
      val q = for { x <- this if x.location === toLocation && x.sku === sku } yield x.qty
      q.update(destQty + qty)
    case _ =>
      // Create - this is likely susceptible to write skew
      this += InventorySingleRecord(Option.empty, sku, qty, toLocation)
  }
}

Hopefully, with these pieces all put together you get a passing test.

Current Code for a Very Basic Transfer of Inventory

def transfer(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             fromLocation: String,
             toLocation: String
            ): Future[Int] = {

  val insert = for {
    toRecord <- {
      this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
    }
    fromRecord <- {
      this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
    }
    createUpdateDestination <- {
      toRecord match {
        case Some(InventorySingleRecord(_, `sku`, destQty, `toLocation`)) =>
          // Update
          logger.debug(s"Transfer from:$fromLocation to $toLocation found $destQty in destination")
          val q = for { x <- this if x.location === toLocation && x.sku === sku } yield x.qty
          q.update(destQty + qty)
        case _ =>
          this += InventorySingleRecord(Option.empty, sku, qty, toLocation)
      }
    }
    updateSource <- {
      fromRecord match {
        case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>
          val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
          q.update(srcQty - qty)
        case _ =>
          DBIO.failed(new Exception("Failed to find source location"))
      }
    }
  } yield updateSource
  db.run(insert.transactionally)
}

Exposing the Flaws in this Initial Design

At this stage we hopefully have a basic DAO that implements the following.

def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[InventorySingleRecord]]

def create(db: PostgresProfile.backend.DatabaseDef,
           sku: String,
           qty: Int,
           location: String
          ): Future[Option[InventorySingleRecord]]

def transfer(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             fromLocation: String,
             toLocation: String
            ): Future[Int]

I created a repository with a working Scala Scalatra service to snapshot this stage of the development:

• https://bitbucket.org/honstain/scalatra-single-record-transfer-service/src/master/

This repo provides you an example of Scalatra service that exposes our DAO operations via a set of crude HTTP endpoints. The README.md provides some points on starting the service. If this is unfamiliar or you would like a refresher, I suggest reviewing the previous post where I covered just this aspect of Scalatra http://honstain.com/rest-in-a-scalatra-service/.

Before beginning this next step, I suggest you verify that you have a service that runs, with a database, and can respond to HTTP requests.

Using a tool like Postman to transfer inventory between LOC-01 and LOC-02 you may notice that doesn't enforce any constraints yet, it can result in negative quantities and moving negative amounts. What we are really interested in how consistent the database will be with our current DAO queries.

Exposing Consistency Problems

One way to test our system might be to attempt to move inventory in parallel (for the same SKU and location group). Let's start with just two locations and a single SKU, trying to move back and forth between LOC-01 and LOC-02 should be enough to expose an issue.

There are several tools that you could use for load and performance testing. You could even write your own script or test. I have opted to use siege which is a common command line tool you can probably retrieve from your Linux package manager (https://www.joedog.org/siege-home/). By defining a set of URLs we will use siege to execute the following in parallel:

• Get all the inventory
• Transfer 1 qty of SKU SKU-01 from LOC-01 to LOC-02
• Transfer 1 qty of SKU SKU-01 from LOC-02 to LOC-01

# siege_urls.txt - a urls file https://www.joedog.org/siege-manual/#a05

127.0.0.1:8080/

127.0.0.1:8080/transfer POST {"sku": "SKU-01","qty": 1,"fromLocation": "LOC-01","toLocation": "LOC-02"}

127.0.0.1:8080/transfer POST {"sku": "SKU-01","qty": 1,"fromLocation": "LOC-02","toLocation": "LOC-01"}

This command will start siege running with the following arguments:

• -v verbose mode
• -c2 2 concurrent requests
• -r10 run the test 10 times
• --content-type specifying the content type for our API
• -f the URLs file

siege -v -c2 -r10 --content-type "application/json" -f siege_urls.txt

** SIEGE 4.0.4
** Preparing 2 concurrent users for battle.
The server is now under siege...
HTTP/1.1 200     0.01 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.07 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.06 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.00 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.03 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.02 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.07 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      92 bytes ==> GET  /
HTTP/1.1 200     0.06 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.05 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.07 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.05 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      92 bytes ==> GET  /
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer

Transactions:		          20 hits
Availability:		      100.00 %
Elapsed time:		        0.38 secs
Data transferred:	        0.00 MB
Response time:		        0.04 secs
Transaction rate:	       52.63 trans/sec
Throughput:		        0.00 MB/sec
Concurrency:		        1.92
Successful transactions:          20
Failed transactions:	           0
Longest transaction:	        0.07
Shortest transaction:	        0.00

Keeping in mind that we started with qty 2 in LOC-01 and qty 0 in LOC-02, let's see what we have now? NOTE - you will likely have different results, if the results look good please repeat the test since we are trying to demonstrate a concurrency issue.

You can look through the logs of the Scalatra service and try to spot where things first go off the rails. I added the following log line to the update source section.

updateSource <- {
  fromRecord match {
    case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>

      val destinationQty: Int = if (toRecord.isDefined) toRecord.get.qty else 0
      logger.debug(s"Transfer $qty from:$fromLocation (had qty:$srcQty) to $toLocation (had qty:$destinationQty)")

      val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
      q.update(srcQty - qty)
    case _ =>
      DBIO.failed(new Exception("Failed to find source location"))
  }
}

An example of my Scalatra logs that demonstrate our consistency issue:

# Two siege calls happen in close succession, both see qty 2 and move 1
Transfer 1 from:LOC-01 (had qty:2) to LOC-02 (had qty:0)
Transfer 1 from:LOC-01 (had qty:2) to LOC-02 (had qty:0)

# Two siege calls happen again but find that only 1 unit was moved
# We are already in an inconsistent state
Transfer 1 from:LOC-02 (had qty:1) to LOC-01 (had qty:1)
Transfer 1 from:LOC-02 (had qty:1) to LOC-01 (had qty:1)

# The problem just spirals out from here.
Transfer 1 from:LOC-01 (had qty:2) to LOC-02 (had qty:0)
Transfer 1 from:LOC-01 (had qty:1) to LOC-02 (had qty:0)
Transfer 1 from:LOC-02 (had qty:1) to LOC-01 (had qty:1)
Transfer 1 from:LOC-02 (had qty:0) to LOC-01 (had qty:2)

Why is this happening? First let's consider that we are executing multiple queries in a transaction, but our isolation level is the default Read Committed https://www.postgresql.org/docs/9.1/transaction-iso.html. Both transactions overlap and as a result one of the clients does not cause the desired change.

Attempt to Enforce Consistency

Often the first thing people reach for is to ratchet up the isolation level and let the database sort things out. We will try that approach and  jump our query up to Serializable isolation level and see what happens.

db.run(insert.transactionally.withTransactionIsolation(TransactionIsolation.Serializable))

Running siege again you might see something like this:

NOTE ON SIEGE - Siege is a brute force sort of tool, it will blindly attempt to keep cycling through its URLs. Hence a previous failure will not cause it to stop or retry (as currently configured), leading to unusual behavior for larger numbers of iterations as it makes no attempt to model a real user or the physical world.

I have organized the log data to better illustrate the success and failure of each call (assigning a color to each distinct transfer call). Note that I also started passing around a user id (random int assigned at the start of the rest call) to help us trace things, it probably would have been better if I referenced it as a tracing id / provenance id).

Now we have consistent data, but PostgreSQL is achieving that by aborting our transactions whenever it identifies a problem. It is helpful to reference the PostgreSQL docs at this stage https://www.postgresql.org/docs/9.1/transaction-iso.html

If you siege long enough, you may also observe PostgreSQL identify and kill a deadlock.

14:40:20.312 [scala-execution-context-global-39] DEBUG o.b.h.inventory.app.ToyInventory - user: 543 - ERROR: deadlock detected
  Detail: Process 25421 waits for ShareLock on transaction 206692; blocked by process 25419.
Process 25419 waits for ShareLock on transaction 206691; blocked by process 25421.
  Hint: See server log for query details.
  Where: while updating tuple (0,91) in relation "inventory_single"

I will leave it to the reader to try Repeatable Read as an exercise.

Summary

We have made an attempt to implement the functionality for modeling the transfer of physical inventory from one location to another. While tests pass and things work on the happy path, when we introduce concurrency we have problems. In our next post we will explore some additional options to help us maintain consistency.

Continuing in our series of posts about creating a basic Scalatra service for managing inventory, we would now like to implement the persistence logic to transfer inventory from one location to another.

Previous posts for our inventory service:

• Creating a Scalatra Inventory Management Service
• Implementing Create/Update in Slick

WARNING - This may be difficult to follow if you haven't been working through the previous posts. Reviewing this repository that implements this material covered so far may help you https://bitbucket.org/honstain/scalatra-single-record-transfer-service/src/master/

Transfer Inventory Between Locations

NOTE - I am going to intentionally start with naive implementation and demonstrate testing it (exposing issues). We will iterate on the design together.

Let's establish some basic requirements or expectations for this logic. We may initially relax some of these requirements to illustrative purposes (but this is where we are going).

• The source location must exist when attempting to transfer a SKU+qty from a source location to a destination location.
• The source location has enough inventory to supply the requested qty being transferred. Said another way, we will not support going negative.

To illustrate, if we wanted to transfer 1 unit of 'SKU-01' from location 'LOC-01' to 'LOC-02'.

We will want to remove one from 'LOC-01' and then increase the quantity of 'LOC-02'. An initial test to help us validate this behavior for our DAO might look like:

def createInventoryHelper(sku: String, qty: Int, location: String): InventorySingleRecord = {
  val create = InventorySingleRecordDao.create(database, sku, qty, location)
  Await.result(create, Duration.Inf).get
}
  
test("transfer") {
  createInventoryHelper(TEST_SKU, 1, BIN_01)
  createInventoryHelper(TEST_SKU, 0, BIN_02)

  val futureTrans = InventorySingleRecordDao.transfer(database, TEST_SKU, 1, BIN_01, BIN_02)
  Await.result(futureTrans, Duration.Inf)

  val futureFind = InventorySingleRecordDao.findAll(database)
  val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)

  findResult should contain only (
    InventorySingleRecord(Some(1), "NewSku", 0, BIN_01),
    InventorySingleRecord(Some(2), "NewSku", 1, BIN_02),
  )
}

Now to implement the InventorySingleRecordDao.transfer logic we can reference the upsert logic from our previous post that uses the Scala for comprehension and a database transaction. We can start by just modifying the source location and ignore the destination location (the test won't pass, but we will be able to validate our transfer logic incrementally).

This gives us a basic overview of the transfer function in our DAO. We have a for comprehension with the query to retrieve the database record for the source (fromLocation) and then attempt to modify it (there is basic handling to address the possibility that we don't find the source record.

def transfer(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             fromLocation: String,
             toLocation: String
            ): Future[Int] = {

  val insert = for {
    fromRecord <- {
      this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
    }
    updateSource <- {
      fromRecord match {
        case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>
          val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
          q.update(srcQty - qty)
        case _ =>
          DBIO.failed(new Exception("Failed to find source location"))
      }
    }
  } yield updateSource
  db.run(insert.transactionally)
}

Running the test that just created, we will get a failure, but hopefully, be able to see that the source 'Bin-01' is decremented.

Vector(
	InventorySingleRecord(Some(2),NewSku,0,Bin-02),
	InventorySingleRecord(Some(1),NewSku,0,Bin-01))
did not contain only (
	InventorySingleRecord(Some(1),NewSku,0,Bin-01), 
	InventorySingleRecord(Some(2),NewSku,1,Bin-02))

Now we need to update the destination record.

Just like when we updated the source location, we will want to query for it, but it is more likely that this record does not already exist (at least in this example where we assume physical inventory already exists in a source location, but its much more likely that the sku+location combination of the destination is unknown to the database - remember that those two columns are integral to our design).

toRecord <- {
  this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
}

Now that we possibly have a record for the destination, we can try to update or create. This should be very familiar if you worked through the upsert logic in my previous post.

createUpdateDestination <- {
  toRecord match {
    case Some(InventorySingleRecord(_, `sku`, destQty, `toLocation`)) =>
      // Update
      logger.debug(s"Transfer from:$fromLocation to $toLocation found $destQty in destination")
      val q = for { x <- this if x.location === toLocation && x.sku === sku } yield x.qty
      q.update(destQty + qty)
    case _ =>
      // Create - this is likely susceptible to write skew
      this += InventorySingleRecord(Option.empty, sku, qty, toLocation)
  }
}

Hopefully, with these pieces all put together you get a passing test.

Current Code for a Very Basic Transfer of Inventory

def transfer(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             fromLocation: String,
             toLocation: String
            ): Future[Int] = {

  val insert = for {
    toRecord <- {
      this.filter(x => x.location === toLocation && x.sku === sku).result.headOption
    }
    fromRecord <- {
      this.filter(x => x.location === fromLocation && x.sku === sku).result.headOption
    }
    createUpdateDestination <- {
      toRecord match {
        case Some(InventorySingleRecord(_, `sku`, destQty, `toLocation`)) =>
          // Update
          logger.debug(s"Transfer from:$fromLocation to $toLocation found $destQty in destination")
          val q = for { x <- this if x.location === toLocation && x.sku === sku } yield x.qty
          q.update(destQty + qty)
        case _ =>
          this += InventorySingleRecord(Option.empty, sku, qty, toLocation)
      }
    }
    updateSource <- {
      fromRecord match {
        case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>
          val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
          q.update(srcQty - qty)
        case _ =>
          DBIO.failed(new Exception("Failed to find source location"))
      }
    }
  } yield updateSource
  db.run(insert.transactionally)
}

Exposing the Flaws in this Initial Design

At this stage we hopefully have a basic DAO that implements the following.

def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[InventorySingleRecord]]

def create(db: PostgresProfile.backend.DatabaseDef,
           sku: String,
           qty: Int,
           location: String
          ): Future[Option[InventorySingleRecord]]

def transfer(db: PostgresProfile.backend.DatabaseDef,
             sku: String,
             qty: Int,
             fromLocation: String,
             toLocation: String
            ): Future[Int]

I created a repository with a working Scala Scalatra service to snapshot this stage of the development:

• https://bitbucket.org/honstain/scalatra-single-record-transfer-service/src/master/

This repo provides you an example of Scalatra service that exposes our DAO operations via a set of crude HTTP endpoints. The README.md provides some points on starting the service. If this is unfamiliar or you would like a refresher, I suggest reviewing the previous post where I covered just this aspect of Scalatra http://honstain.com/rest-in-a-scalatra-service/.

Before beginning this next step, I suggest you verify that you have a service that runs, with a database, and can respond to HTTP requests.

Using a tool like Postman to transfer inventory between LOC-01 and LOC-02 you may notice that doesn't enforce any constraints yet, it can result in negative quantities and moving negative amounts. What we are really interested in how consistent the database will be with our current DAO queries.

Exposing Consistency Problems

One way to test our system might be to attempt to move inventory in parallel (for the same SKU and location group). Let's start with just two locations and a single SKU, trying to move back and forth between LOC-01 and LOC-02 should be enough to expose an issue.

There are several tools that you could use for load and performance testing. You could even write your own script or test. I have opted to use siege which is a common command line tool you can probably retrieve from your Linux package manager (https://www.joedog.org/siege-home/). By defining a set of URLs we will use siege to execute the following in parallel:

• Get all the inventory
• Transfer 1 qty of SKU SKU-01 from LOC-01 to LOC-02
• Transfer 1 qty of SKU SKU-01 from LOC-02 to LOC-01

# siege_urls.txt - a urls file https://www.joedog.org/siege-manual/#a05

127.0.0.1:8080/

127.0.0.1:8080/transfer POST {"sku": "SKU-01","qty": 1,"fromLocation": "LOC-01","toLocation": "LOC-02"}

127.0.0.1:8080/transfer POST {"sku": "SKU-01","qty": 1,"fromLocation": "LOC-02","toLocation": "LOC-01"}

This command will start siege running with the following arguments:

• -v verbose mode
• -c2 2 concurrent requests
• -r10 run the test 10 times
• --content-type specifying the content type for our API
• -f the URLs file

siege -v -c2 -r10 --content-type "application/json" -f siege_urls.txt

** SIEGE 4.0.4
** Preparing 2 concurrent users for battle.
The server is now under siege...
HTTP/1.1 200     0.01 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.07 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.06 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.00 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.03 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.02 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.07 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      92 bytes ==> GET  /
HTTP/1.1 200     0.06 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.05 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.07 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      91 bytes ==> GET  /
HTTP/1.1 200     0.05 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer
HTTP/1.1 200     0.01 secs:      92 bytes ==> GET  /
HTTP/1.1 200     0.04 secs:       0 bytes ==> POST http://127.0.0.1:8080/transfer

Transactions:		          20 hits
Availability:		      100.00 %
Elapsed time:		        0.38 secs
Data transferred:	        0.00 MB
Response time:		        0.04 secs
Transaction rate:	       52.63 trans/sec
Throughput:		        0.00 MB/sec
Concurrency:		        1.92
Successful transactions:          20
Failed transactions:	           0
Longest transaction:	        0.07
Shortest transaction:	        0.00

Keeping in mind that we started with qty 2 in LOC-01 and qty 0 in LOC-02, let's see what we have now? NOTE - you will likely have different results, if the results look good please repeat the test since we are trying to demonstrate a concurrency issue.

You can look through the logs of the Scalatra service and try to spot where things first go off the rails. I added the following log line to the update source section.

updateSource <- {
  fromRecord match {
    case Some(InventorySingleRecord(_, `sku`, srcQty, `fromLocation`)) =>

      val destinationQty: Int = if (toRecord.isDefined) toRecord.get.qty else 0
      logger.debug(s"Transfer $qty from:$fromLocation (had qty:$srcQty) to $toLocation (had qty:$destinationQty)")

      val q = for { x <- this if x.location === fromLocation && x.sku === sku } yield x.qty
      q.update(srcQty - qty)
    case _ =>
      DBIO.failed(new Exception("Failed to find source location"))
  }
}

An example of my Scalatra logs that demonstrate our consistency issue:

# Two siege calls happen in close succession, both see qty 2 and move 1
Transfer 1 from:LOC-01 (had qty:2) to LOC-02 (had qty:0)
Transfer 1 from:LOC-01 (had qty:2) to LOC-02 (had qty:0)

# Two siege calls happen again but find that only 1 unit was moved
# We are already in an inconsistent state
Transfer 1 from:LOC-02 (had qty:1) to LOC-01 (had qty:1)
Transfer 1 from:LOC-02 (had qty:1) to LOC-01 (had qty:1)

# The problem just spirals out from here.
Transfer 1 from:LOC-01 (had qty:2) to LOC-02 (had qty:0)
Transfer 1 from:LOC-01 (had qty:1) to LOC-02 (had qty:0)
Transfer 1 from:LOC-02 (had qty:1) to LOC-01 (had qty:1)
Transfer 1 from:LOC-02 (had qty:0) to LOC-01 (had qty:2)

Why is this happening? First let's consider that we are executing multiple queries in a transaction, but our isolation level is the default Read Committed https://www.postgresql.org/docs/9.1/transaction-iso.html. Both transactions overlap and as a result one of the clients does not cause the desired change.

Attempt to Enforce Consistency

Often the first thing people reach for is to ratchet up the isolation level and let the database sort things out. We will try that approach and  jump our query up to Serializable isolation level and see what happens.

db.run(insert.transactionally.withTransactionIsolation(TransactionIsolation.Serializable))

Running siege again you might see something like this:

NOTE ON SIEGE - Siege is a brute force sort of tool, it will blindly attempt to keep cycling through its URLs. Hence a previous failure will not cause it to stop or retry (as currently configured), leading to unusual behavior for larger numbers of iterations as it makes no attempt to model a real user or the physical world.

I have organized the log data to better illustrate the success and failure of each call (assigning a color to each distinct transfer call). Note that I also started passing around a user id (random int assigned at the start of the rest call) to help us trace things, it probably would have been better if I referenced it as a tracing id / provenance id).

Now we have consistent data, but PostgreSQL is achieving that by aborting our transactions whenever it identifies a problem. It is helpful to reference the PostgreSQL docs at this stage https://www.postgresql.org/docs/9.1/transaction-iso.html

If you siege long enough, you may also observe PostgreSQL identify and kill a deadlock.

14:40:20.312 [scala-execution-context-global-39] DEBUG o.b.h.inventory.app.ToyInventory - user: 543 - ERROR: deadlock detected
  Detail: Process 25421 waits for ShareLock on transaction 206692; blocked by process 25419.
Process 25419 waits for ShareLock on transaction 206691; blocked by process 25421.
  Hint: See server log for query details.
  Where: while updating tuple (0,91) in relation "inventory_single"

I will leave it to the reader to try Repeatable Read as an exercise.

Summary

We have made an attempt to implement the functionality for modeling the transfer of physical inventory from one location to another. While tests pass and things work on the happy path, when we introduce concurrency we have problems. In our next post we will explore some additional options to help us maintain consistency.

In our previous post, we wanted to create and update a record from our PostgreSQL database in our Scalatra service to manage inventory data.

• Creating a Scalatra Inventory Management Service

We only got as far as using raw SQL to do the query, and this had an added benefit of being an atomic operation. Now we would like to try and implement the same logic using Slick.

Improving the Return Type of our Raw SQL Query

A helpful reference here is http://slick.lightbend.com/doc/3.3.0/sql.html. I would have saved my self some time by sitting down and reading it end to end before I started.

We had the following when we left off last time:

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Seq[(String, Int, String)]] = {
    val query: DBIO[Seq[(String, Int, String)]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING sku, qty, location;
        """.as[(String, Int, String)]
    db.run(query)
  }

This code was handling and returning the tuple (String, Int, String) instead of the InventorySingleRecord case class.

Slick provides us with sql, sqlu, and tsql interpolators.

• sql is used for queries to produce a sequence of tuples, has type DBIO[Seq[<tuples>]] and can use implicit GetResult converters.
• sqlu is used for queries that produce a row count, has type DBIO[Int]
• tsql can enforce compile-time type checking, requires access to a configuration that defines the database schema.

We will continue to use the sql interpolator. Let's define our own converter to the InventorySingleRecord class and update this query (you will need to update your test as well).

  implicit val getInventorySingleRecord : GetResult[InventorySingleRecord] =
    GetResult(r => InventorySingleRecord(r.<<, r.<<, r.<<, r.<<))

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Seq[InventorySingleRecord]] = {

    val query: DBIO[Seq[InventorySingleRecord]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING id, sku, qty, location;
        """.as[InventorySingleRecord]
    db.run(query)
  }

Now we have the desired type instead of a tuple, but we still have a sequence Seq[InventorySingleRecord], which is not ideal given that this is a create for a single record. This can be addressed with headOption (https://www.garysieling.com/blog/scala-headoption-example) to get the first element and update the return type Option[InventorySingleRecord]

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Option[InventorySingleRecord]] = {

    val query: DBIO[Option[InventorySingleRecord]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING id, sku, qty, location;
        """.as[InventorySingleRecord].headOption
    db.run(query)

Our tests then go to validating the option instead of a sequence.

val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
val result: Option[InventorySingleRecord] = Await.result(future, Duration.Inf)
result should equal(Some(InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)))

Implement the raw SQL as a Slick Query

Now let's write the same query using Slick. We will start by using a Scala for comprehension (a nice reference https://medium.com/@scalaisfun/scala-for-comprehension-tricks-9c8b9fe31778).

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Option[InventorySingleRecord]] = {
              
    val upsert = for {
      existing <- {
        this.filter(x => x.location === location && x.sku === sku).forUpdate.result.headOption
      }
    } yield existing
    db.run(upsert.transactionally)
  }

This first step lets us retrieve a record if it already exists, and this is the model we will use to add additional functionality.

We will compose several queries here:

• One to find the existing record (if it exists) this.filter(x => x.location === location && x.sku === sku).forUpdate.result.headOption,
• A Query to create TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
• Finally one to retrieve the value TableQuery[InventorySingleRecords].filter(x => x.location === location && x.sku === sku).result.headOption

I have left the pattern matching unimplemented for the update case just to try and keep things reasonably simple.

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Option[InventorySingleRecord]] = {
    val upsert = for {
      existing <- {
        this.filter(x => x.location === location && x.sku === sku).forUpdate.result.headOption
      }
      _ <- {
        existing match {
          case Some(InventorySingleRecord(_, `sku`, _, `location`)) => 
            // Update
            ???
          case _ => 
            // Create a new record
            TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
        }
      }
      updated <- {
        TableQuery[InventorySingleRecords].filter(x => x.location === location && x.sku === sku).result.headOption
      }
    } yield updated
    db.run(upsert.transactionally)
  }

This should satisfy out tests for a single create, but update is still not implemented.

The logic for doing an update can be implemented as a standard Slick update query.

        existing match {
          case Some(InventorySingleRecord(_, `sku`, _, `location`)) => // Update
            val updateFoo = TableQuery[InventorySingleRecords]
            val q = for {x <- updateFoo if x.location === location && x.sku === sku} yield x.qty
            q.update(qty)

Note that in our update logic we have opted to ignore the existing value for the qty column. You could certainly utilize it if we wanted to log or use it in your update logic, that might look something like this case Some(InventorySingleRecord(_, sku, existingQty, location)) =>

This now should satisfy the tests for both create and update.

Conclusion

We have implemented our create logic in two different ways, one in raw SQL and the other using the Slick functional relational mapper. Hopefully, you found the comparison helpful.

In our previous post, we wanted to create and update a record from our PostgreSQL database in our Scalatra service to manage inventory data.

• Creating a Scalatra Inventory Management Service

We only got as far as using raw SQL to do the query, and this had an added benefit of being an atomic operation. Now we would like to try and implement the same logic using Slick.

Improving the Return Type of our Raw SQL Query

A helpful reference here is http://slick.lightbend.com/doc/3.3.0/sql.html. I would have saved my self some time by sitting down and reading it end to end before I started.

We had the following when we left off last time:

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Seq[(String, Int, String)]] = {
    val query: DBIO[Seq[(String, Int, String)]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING sku, qty, location;
        """.as[(String, Int, String)]
    db.run(query)
  }

This code was handling and returning the tuple (String, Int, String) instead of the InventorySingleRecord case class.

Slick provides us with sql, sqlu, and tsql interpolators.

• sql is used for queries to produce a sequence of tuples, has type DBIO[Seq[<tuples>]] and can use implicit GetResult converters.
• sqlu is used for queries that produce a row count, has type DBIO[Int]
• tsql can enforce compile-time type checking, requires access to a configuration that defines the database schema.

We will continue to use the sql interpolator. Let's define our own converter to the InventorySingleRecord class and update this query (you will need to update your test as well).

  implicit val getInventorySingleRecord : GetResult[InventorySingleRecord] =
    GetResult(r => InventorySingleRecord(r.<<, r.<<, r.<<, r.<<))

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Seq[InventorySingleRecord]] = {

    val query: DBIO[Seq[InventorySingleRecord]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING id, sku, qty, location;
        """.as[InventorySingleRecord]
    db.run(query)
  }

Now we have the desired type instead of a tuple, but we still have a sequence Seq[InventorySingleRecord], which is not ideal given that this is a create for a single record. This can be addressed with headOption (https://www.garysieling.com/blog/scala-headoption-example) to get the first element and update the return type Option[InventorySingleRecord]

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Option[InventorySingleRecord]] = {

    val query: DBIO[Option[InventorySingleRecord]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING id, sku, qty, location;
        """.as[InventorySingleRecord].headOption
    db.run(query)

Our tests then go to validating the option instead of a sequence.

val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
val result: Option[InventorySingleRecord] = Await.result(future, Duration.Inf)
result should equal(Some(InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)))

Implement the raw SQL as a Slick Query

Now let's write the same query using Slick. We will start by using a Scala for comprehension (a nice reference https://medium.com/@scalaisfun/scala-for-comprehension-tricks-9c8b9fe31778).

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Option[InventorySingleRecord]] = {
              
    val upsert = for {
      existing <- {
        this.filter(x => x.location === location && x.sku === sku).forUpdate.result.headOption
      }
    } yield existing
    db.run(upsert.transactionally)
  }

This first step lets us retrieve a record if it already exists, and this is the model we will use to add additional functionality.

We will compose several queries here:

• One to find the existing record (if it exists) this.filter(x => x.location === location && x.sku === sku).forUpdate.result.headOption,
• A Query to create TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
• Finally one to retrieve the value TableQuery[InventorySingleRecords].filter(x => x.location === location && x.sku === sku).result.headOption

I have left the pattern matching unimplemented for the update case just to try and keep things reasonably simple.

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Option[InventorySingleRecord]] = {
    val upsert = for {
      existing <- {
        this.filter(x => x.location === location && x.sku === sku).forUpdate.result.headOption
      }
      _ <- {
        existing match {
          case Some(InventorySingleRecord(_, `sku`, _, `location`)) => 
            // Update
            ???
          case _ => 
            // Create a new record
            TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
        }
      }
      updated <- {
        TableQuery[InventorySingleRecords].filter(x => x.location === location && x.sku === sku).result.headOption
      }
    } yield updated
    db.run(upsert.transactionally)
  }

This should satisfy out tests for a single create, but update is still not implemented.

The logic for doing an update can be implemented as a standard Slick update query.

        existing match {
          case Some(InventorySingleRecord(_, `sku`, _, `location`)) => // Update
            val updateFoo = TableQuery[InventorySingleRecords]
            val q = for {x <- updateFoo if x.location === location && x.sku === sku} yield x.qty
            q.update(qty)

Note that in our update logic we have opted to ignore the existing value for the qty column. You could certainly utilize it if we wanted to log or use it in your update logic, that might look something like this case Some(InventorySingleRecord(_, sku, existingQty, location)) =>

This now should satisfy the tests for both create and update.

Conclusion

We have implemented our create logic in two different ways, one in raw SQL and the other using the Slick functional relational mapper. Hopefully, you found the comparison helpful.

In our previous set of posts, we added progressively more functionality to our basic Scalatra service.

• Creating a Scalatra service
• Scalatra and REST
• Scalatra with Slick and PostgreSQL

Now we would like to explore implementing a system for tracking inventory. What you will get from this post:

• Creating a DB model for a simplified service (tracking inventory)
• Using Slick to query that data
• Using Slick to insert data
• Using Slick and PostgreSQL to upsert
• Tests for the new logic.

Creating a Service to Track Inventory Levels

Create the Database Schema

Let's start with a very basic schema that can track a product/SKU (if you are unfamiliar with the SKU terminology I recommend reading https://en.wikipedia.org/wiki/Stock_keeping_unit), a location, and a quantity. A location could have multiple SKU's in it, and a SKU can be in more than one location.

CREATE TABLE inventory_single
(
  id bigserial NOT NULL,
  sku text,
  qty integer,
  location text,
  CONSTRAINT pk_single PRIMARY KEY (id),
  UNIQUE (sku, location)
);

We can create a few example pieces of inventory:

INSERT INTO inventory_single(sku, qty, location) VALUES
('SKU-01', 2, 'LOC-01'),
('SKU-01', 0, 'LOC-02')
;

Create a DAO for Slick

Now that we have our database schema, lets set up our Scala code to access it. I have chosen here to abstract my database access and Slick queries with DAO object. I referred to this when trying to organize my DAO https://sap1ens.com/blog/2015/07/26/scala-slick-3-how-to-start/, I also found this helpful https://reactore.com/repository-patterngeneric-dao-implementation-in-scala-using-slick-3/.

import org.slf4j.{Logger, LoggerFactory}
import slick.jdbc.{PostgresProfile, TransactionIsolation}
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

case class InventorySingleRecord(
                                  id: Option[Int],
                                  sku: String,
                                  qty: Int,
                                  location: String
                                )

class InventorySingleRecords(tag: Tag) extends Table[InventorySingleRecord](tag, "inventory_single") {
  def id = column[Int]("id", O.PrimaryKey, O.AutoInc)
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def location = column[String]("location")
  def * =
    (id.?, sku, qty, location) <> (InventorySingleRecord.tupled, InventorySingleRecord.unapply)
}

object InventorySingleRecordDao extends TableQuery(new InventorySingleRecords(_)) {

  val logger: Logger = LoggerFactory.getLogger(getClass)

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[InventorySingleRecord]] = {
    db.run(this.result)
  }
}

This gives us a basic DAO that initial supports just a single query to return every record. Then if we want to retrieve the data we would get a Future for all the records in the database val futureResult = Await.result(singleDAO.findAll(database), Duration.Inf)

Testing the New DAO

One of the benefits of organizing our code this way, is the ability to test our database queries in isolation (something I found helpful while experimenting with Slick).

WARNING - the repeated create and drop, is intended to be simple (to understand for the reader) at the cost of being relatively slow and inefficient.

Before writing our tests, we could use a trait to set up a database just for our testing (and avoid clobbering the database used to run the service).

import org.scalatest.{BeforeAndAfterAll, Suite}

import slick.dbio.DBIO
import slick.jdbc.PostgresProfile.api._
import scala.concurrent.Await
import scala.concurrent.duration.Duration

trait PostgresSpec extends Suite with BeforeAndAfterAll {

  private val dbName = getClass.getSimpleName.toLowerCase
  private val driver = "org.postgresql.Driver"

  private val postgres = Database.forURL("jdbc:postgresql://localhost:5432/?user=<TODO-YOUR-USER>&password=<TODO-YOUR-PASSWORD>", driver = driver)

  def dropDB: DBIO[Int] = sqlu"DROP DATABASE IF EXISTS #$dbName"
  def createDB: DBIO[Int] = sqlu"CREATE DATABASE #$dbName"

  override def beforeAll(): Unit = {
    super.beforeAll()
    Await.result(postgres.run(dropDB), Duration.Inf)
    Await.result(postgres.run(createDB), Duration.Inf)
  }

  override def afterAll() {
    super.afterAll()
    Await.result(postgres.run(dropDB), Duration.Inf)
  }

  val database = Database.forURL(s"jdbc:postgresql://localhost:5432/$dbName?user=<TODO-YOUR-USER>&password=<TODO-YOUR-PASSWORD>", driver = driver)
}

This has a connection just for creating a special test database and tearing it down, along with a reference database for you to use in your test suite class.

import org.bitbucket.honstain.PostgresSpec
import org.scalatest.BeforeAndAfter
import org.scalatra.test.scalatest._
import slick.dbio.DBIO
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Await
import scala.concurrent.duration.Duration


class InventorySingleRecordDaoTests extends ScalatraFunSuite with BeforeAndAfter with PostgresSpec {

  def createInventoryTable: DBIO[Int] =
    sqlu"""
          CREATE TABLE inventory_single
          (
            id bigserial NOT NULL,
            sku text,
            qty integer,
            location text,
            CONSTRAINT pk_single PRIMARY KEY (id),
            UNIQUE (sku, location)
          );
      """
  def dropInventoryTable: DBIO[Int] =
    sqlu"""
          DROP TABLE IF EXISTS inventory_single;
      """

  before {
    Await.result(database.run(createInventoryTable), Duration.Inf)
  }

  after {
    Await.result(database.run(dropInventoryTable), Duration.Inf)
  }

  val TEST_SKU = "NewSku"
  val BIN_01 = "Bin-01"
  val BIN_02 = "Bin-02"

  test("findAll") {
    val futureFind = InventorySingleRecordDao.findAll(database)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)

    findResult should equal(List())
  }
}

Create New Inventory

Now that we have a very basic schema for the DB, we want to be able to create new records and inventory. Many of the Slick 3.0 examples I have seen only address the basic insert. We would like to go a bit further and support create and update logic, giving the logic that uses this DAO call the ability to create/destroy/modify inventory levels for a given location and SKU. But to start with let's do the most basic thing and build up.

Our first test could look something like this (note that the Slick documentation can be a good additional reference http://slick.lightbend.com/doc/3.3.0/queries.html#inserting)

    test("create single record and use DAO to validate") {
      val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
      val result: Int = Await.result(future, Duration.Inf)
      // The expected result is just a count of the number of rows impacted.
      result should equal(1)

      // Validate that changes were persisted, in this case we will use a DAO
      // function we previously created to help us validate our new one.
      val futureFind = InventorySingleRecordDao.findAll(database)
      val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
      findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)
    }

If you would prefer not to compose elements of the DAO in tests (to use with setup and decomposition), you could do the following by using new Slick queries for the test validation (inspecting the changes to the database).

    test("create single record and check slick query") {
      val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
      val result: Int = Await.result(future, Duration.Inf)
      // The expected result is just a count of the number of rows impacted.
      result should equal(1)

      // Validate that changes were persisted
      val inventoryTable = TableQuery[InventorySingleRecords]
      val futureFind = database.run(inventoryTable.result)
      val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
      findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)
    }

We can then add the following create method to our DAO

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Int] = {
    val query = TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
    db.run(query)
  }

This is a good starting point, but you will notice that it is fairly restrictive, we would only be able to create records if none existed (because of the unique constraint we previously placed on inventory and SKU columns). I would suggest experimenting with a test to prove this to yourself.

  test("create when unique constraint violated") {
    val resultFirst: Int = Await.result(
      InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01),
      Duration.Inf
    )
    resultFirst should equal(1)

    // This naive test, will result in a PSQLException
    Await.result(
      InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01),
      Duration.Inf
    )
  }

Unfortunately, the stack trace I got, was not very helpful in understanding where the problem occurred in our code base, but we can improve on error handling later.

ERROR: duplicate key value violates unique constraint "inventory_single_sku_location_key"
  Detail: Key (sku, location)=(NewSku, Bin-01) already exists.
org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint "inventory_single_sku_location_key"
  Detail: Key (sku, location)=(NewSku, Bin-01) already exists.
	at org.postgresql.core.v3.QueryExecutorImpl.receiveErrorResponse(QueryExecutorImpl.java:2440)
	at org.postgresql.core.v3.QueryExecutorImpl.processResults(QueryExecutorImpl.java:2183)
	at org.postgresql.core.v3.QueryExecutorImpl.execute(QueryExecutorImpl.java:308)
	at org.postgresql.jdbc.PgStatement.executeInternal(PgStatement.java:441)
	at org.postgresql.jdbc.PgStatement.execute(PgStatement.java:365)
	at org.postgresql.jdbc.PgPreparedStatement.executeWithFlags(PgPreparedStatement.java:143)
	at org.postgresql.jdbc.PgPreparedStatement.executeUpdate(PgPreparedStatement.java:120)
	at slick.jdbc.JdbcActionComponent$InsertActionComposerImpl$SingleInsertAction.$anonfun$run$15(JdbcActionComponent.scala:522)
	at slick.jdbc.JdbcBackend$SessionDef.withPreparedStatement(JdbcBackend.scala:425)
	at slick.jdbc.JdbcBackend$SessionDef.withPreparedStatement$(JdbcBackend.scala:420)
	at slick.jdbc.JdbcBackend$BaseSession.withPreparedStatement(JdbcBackend.scala:489)
	at slick.jdbc.JdbcActionComponent$InsertActionComposerImpl.preparedInsert(JdbcActionComponent.scala:513)
	at slick.jdbc.JdbcActionComponent$InsertActionComposerImpl$SingleInsertAction.run(JdbcActionComponent.scala:519)
	at slick.jdbc.JdbcActionComponent$SimpleJdbcProfileAction.run(JdbcActionComponent.scala:30)
	at slick.jdbc.JdbcActionComponent$SimpleJdbcProfileAction.run(JdbcActionComponent.scala:27)
	at slick.basic.BasicBackend$DatabaseDef$$anon$3.liftedTree1$1(BasicBackend.scala:275)
	at slick.basic.BasicBackend$DatabaseDef$$anon$3.run(BasicBackend.scala:275)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:748)

Create with Update

Now we want to take our current create logic and to go one step further, allowing the caller to also update the volume of an existing record (upsert). Let's start by modifying our test to expect this new behavior.

  test("create with update") {
    val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    Await.result(future, Duration.Inf)

    val futureUpdate = InventorySingleRecordDao.create(database, TEST_SKU, 3, BIN_01)
    val resultUpdate: Int = Await.result(futureUpdate, Duration.Inf)
    resultUpdate should equal(1)

    // Validate that changes were persisted
    val inventoryTable = TableQuery[InventorySingleRecords]
    val futureFind = database.run(inventoryTable.result)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 3, BIN_01)
  }

With the test in place, we can implement our changes. Before we implement the Slick query it is worth reviewing what our specific database supports. In our case, PostgreSQL https://www.postgresql.org/docs/9.5/sql-insert.html supports upsert behavior with the "ON CONFLICT" clause. We could use a SQL query like this to get an atomic upsert.

INSERT INTO inventory_single (sku, qty, location)
VALUES ('SKU-01', 3, 'LOC-01')
ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
DO UPDATE SET qty = EXCLUDED.qty;

The corresponding raw SQL implemented in Slick (this is a useful reference http://slick.lightbend.com/doc/3.3.0/sql.html) would be:

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Int] = {
    //val query = TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
    val query: DBIO[Int] =
      sqlu"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty;
        """
    db.run(query)
  }

That now gives us the ability to create/update quantities for a SKU and location while working within the existing constraints (we said the sku,location needed to be unique). You may not prefer the raw SQL, but we will explore alternatives in the next section.

Create/Update and Return the New/Updated Record

The create DAO only returns an Int to indicate if a row was modified, we would now like to return the new value of the record pending the create/update. We can modify our SQL by adding the RETURNING clause to the query.

INSERT INTO inventory_single (sku, qty, location)
VALUES ('SKU-01', 3, 'LOC-01')
ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
DO UPDATE SET qty = EXCLUDED.qty
RETURNING sku, qty, location;

Which means we then need to update the types in our DAO and it's tests.

  test("create") {
    val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    val result: Seq[(String, Int, String)] = Await.result(future, Duration.Inf)
    // The expected result is just a count of the number of rows impacted.
    result should contain only((TEST_SKU, 1, BIN_01))

    // Validate that changes were persisted
    val inventoryTable = TableQuery[InventorySingleRecords]
    val futureFind = database.run(inventoryTable.result)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)
  }

  test("create with update") {
    val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    Await.result(future, Duration.Inf)

    val futureUpdate = InventorySingleRecordDao.create(database, TEST_SKU, 3, BIN_01)
    val resultUpdate: Seq[(String, Int, String)] = Await.result(futureUpdate, Duration.Inf)
    resultUpdate should contain only((TEST_SKU, 3, BIN_01))

    // Validate that changes were persisted
    val inventoryTable = TableQuery[InventorySingleRecords]
    val futureFind = database.run(inventoryTable.result)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 3, BIN_01)
  }

The create query in the DAO then becomes:

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Seq[(String, Int, String)]] = {
    val query: DBIO[Seq[(String, Int, String)]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING sku, qty, location;
        """.as[(String, Int, String)]
    db.run(query)
  }

The astute reader will notice that we no longer have a mapping to the InventorySingleRecord case class that we set up. We started by just passing back a tuple of (String, Int, String) to represent the record.

Summary

We made it as far as creating the schema, reading from the DB and doing some progressively complicated upsert behavior. In the next posts, we will expand on this functionality and attempt to transfer inventory.

In our previous set of posts, we added progressively more functionality to our basic Scalatra service.

• Creating a Scalatra service
• Scalatra and REST
• Scalatra with Slick and PostgreSQL

Now we would like to explore implementing a system for tracking inventory. What you will get from this post:

• Creating a DB model for a simplified service (tracking inventory)
• Using Slick to query that data
• Using Slick to insert data
• Using Slick and PostgreSQL to upsert
• Tests for the new logic.

Creating a Service to Track Inventory Levels

Create the Database Schema

Let's start with a very basic schema that can track a product/SKU (if you are unfamiliar with the SKU terminology I recommend reading https://en.wikipedia.org/wiki/Stock_keeping_unit), a location, and a quantity. A location could have multiple SKU's in it, and a SKU can be in more than one location.

CREATE TABLE inventory_single
(
  id bigserial NOT NULL,
  sku text,
  qty integer,
  location text,
  CONSTRAINT pk_single PRIMARY KEY (id),
  UNIQUE (sku, location)
);

We can create a few example pieces of inventory:

INSERT INTO inventory_single(sku, qty, location) VALUES
('SKU-01', 2, 'LOC-01'),
('SKU-01', 0, 'LOC-02')
;

Create a DAO for Slick

Now that we have our database schema, lets set up our Scala code to access it. I have chosen here to abstract my database access and Slick queries with DAO object. I referred to this when trying to organize my DAO https://sap1ens.com/blog/2015/07/26/scala-slick-3-how-to-start/, I also found this helpful https://reactore.com/repository-patterngeneric-dao-implementation-in-scala-using-slick-3/.

import org.slf4j.{Logger, LoggerFactory}
import slick.jdbc.{PostgresProfile, TransactionIsolation}
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

case class InventorySingleRecord(
                                  id: Option[Int],
                                  sku: String,
                                  qty: Int,
                                  location: String
                                )

class InventorySingleRecords(tag: Tag) extends Table[InventorySingleRecord](tag, "inventory_single") {
  def id = column[Int]("id", O.PrimaryKey, O.AutoInc)
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def location = column[String]("location")
  def * =
    (id.?, sku, qty, location) <> (InventorySingleRecord.tupled, InventorySingleRecord.unapply)
}

object InventorySingleRecordDao extends TableQuery(new InventorySingleRecords(_)) {

  val logger: Logger = LoggerFactory.getLogger(getClass)

  def findAll(db: PostgresProfile.backend.DatabaseDef): Future[Seq[InventorySingleRecord]] = {
    db.run(this.result)
  }
}

This gives us a basic DAO that initial supports just a single query to return every record. Then if we want to retrieve the data we would get a Future for all the records in the database val futureResult = Await.result(singleDAO.findAll(database), Duration.Inf)

Testing the New DAO

One of the benefits of organizing our code this way, is the ability to test our database queries in isolation (something I found helpful while experimenting with Slick).

WARNING - the repeated create and drop, is intended to be simple (to understand for the reader) at the cost of being relatively slow and inefficient.

Before writing our tests, we could use a trait to set up a database just for our testing (and avoid clobbering the database used to run the service).

import org.scalatest.{BeforeAndAfterAll, Suite}

import slick.dbio.DBIO
import slick.jdbc.PostgresProfile.api._
import scala.concurrent.Await
import scala.concurrent.duration.Duration

trait PostgresSpec extends Suite with BeforeAndAfterAll {

  private val dbName = getClass.getSimpleName.toLowerCase
  private val driver = "org.postgresql.Driver"

  private val postgres = Database.forURL("jdbc:postgresql://localhost:5432/?user=<TODO-YOUR-USER>&password=<TODO-YOUR-PASSWORD>", driver = driver)

  def dropDB: DBIO[Int] = sqlu"DROP DATABASE IF EXISTS #$dbName"
  def createDB: DBIO[Int] = sqlu"CREATE DATABASE #$dbName"

  override def beforeAll(): Unit = {
    super.beforeAll()
    Await.result(postgres.run(dropDB), Duration.Inf)
    Await.result(postgres.run(createDB), Duration.Inf)
  }

  override def afterAll() {
    super.afterAll()
    Await.result(postgres.run(dropDB), Duration.Inf)
  }

  val database = Database.forURL(s"jdbc:postgresql://localhost:5432/$dbName?user=<TODO-YOUR-USER>&password=<TODO-YOUR-PASSWORD>", driver = driver)
}

This has a connection just for creating a special test database and tearing it down, along with a reference database for you to use in your test suite class.

import org.bitbucket.honstain.PostgresSpec
import org.scalatest.BeforeAndAfter
import org.scalatra.test.scalatest._
import slick.dbio.DBIO
import slick.jdbc.PostgresProfile.api._

import scala.concurrent.Await
import scala.concurrent.duration.Duration


class InventorySingleRecordDaoTests extends ScalatraFunSuite with BeforeAndAfter with PostgresSpec {

  def createInventoryTable: DBIO[Int] =
    sqlu"""
          CREATE TABLE inventory_single
          (
            id bigserial NOT NULL,
            sku text,
            qty integer,
            location text,
            CONSTRAINT pk_single PRIMARY KEY (id),
            UNIQUE (sku, location)
          );
      """
  def dropInventoryTable: DBIO[Int] =
    sqlu"""
          DROP TABLE IF EXISTS inventory_single;
      """

  before {
    Await.result(database.run(createInventoryTable), Duration.Inf)
  }

  after {
    Await.result(database.run(dropInventoryTable), Duration.Inf)
  }

  val TEST_SKU = "NewSku"
  val BIN_01 = "Bin-01"
  val BIN_02 = "Bin-02"

  test("findAll") {
    val futureFind = InventorySingleRecordDao.findAll(database)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)

    findResult should equal(List())
  }
}

Create New Inventory

Now that we have a very basic schema for the DB, we want to be able to create new records and inventory. Many of the Slick 3.0 examples I have seen only address the basic insert. We would like to go a bit further and support create and update logic, giving the logic that uses this DAO call the ability to create/destroy/modify inventory levels for a given location and SKU. But to start with let's do the most basic thing and build up.

Our first test could look something like this (note that the Slick documentation can be a good additional reference http://slick.lightbend.com/doc/3.3.0/queries.html#inserting)

    test("create single record and use DAO to validate") {
      val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
      val result: Int = Await.result(future, Duration.Inf)
      // The expected result is just a count of the number of rows impacted.
      result should equal(1)

      // Validate that changes were persisted, in this case we will use a DAO
      // function we previously created to help us validate our new one.
      val futureFind = InventorySingleRecordDao.findAll(database)
      val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
      findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)
    }

If you would prefer not to compose elements of the DAO in tests (to use with setup and decomposition), you could do the following by using new Slick queries for the test validation (inspecting the changes to the database).

    test("create single record and check slick query") {
      val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
      val result: Int = Await.result(future, Duration.Inf)
      // The expected result is just a count of the number of rows impacted.
      result should equal(1)

      // Validate that changes were persisted
      val inventoryTable = TableQuery[InventorySingleRecords]
      val futureFind = database.run(inventoryTable.result)
      val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
      findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)
    }

We can then add the following create method to our DAO

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Int] = {
    val query = TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
    db.run(query)
  }

This is a good starting point, but you will notice that it is fairly restrictive, we would only be able to create records if none existed (because of the unique constraint we previously placed on inventory and SKU columns). I would suggest experimenting with a test to prove this to yourself.

  test("create when unique constraint violated") {
    val resultFirst: Int = Await.result(
      InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01),
      Duration.Inf
    )
    resultFirst should equal(1)

    // This naive test, will result in a PSQLException
    Await.result(
      InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01),
      Duration.Inf
    )
  }

Unfortunately, the stack trace I got, was not very helpful in understanding where the problem occurred in our code base, but we can improve on error handling later.

ERROR: duplicate key value violates unique constraint "inventory_single_sku_location_key"
  Detail: Key (sku, location)=(NewSku, Bin-01) already exists.
org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint "inventory_single_sku_location_key"
  Detail: Key (sku, location)=(NewSku, Bin-01) already exists.
	at org.postgresql.core.v3.QueryExecutorImpl.receiveErrorResponse(QueryExecutorImpl.java:2440)
	at org.postgresql.core.v3.QueryExecutorImpl.processResults(QueryExecutorImpl.java:2183)
	at org.postgresql.core.v3.QueryExecutorImpl.execute(QueryExecutorImpl.java:308)
	at org.postgresql.jdbc.PgStatement.executeInternal(PgStatement.java:441)
	at org.postgresql.jdbc.PgStatement.execute(PgStatement.java:365)
	at org.postgresql.jdbc.PgPreparedStatement.executeWithFlags(PgPreparedStatement.java:143)
	at org.postgresql.jdbc.PgPreparedStatement.executeUpdate(PgPreparedStatement.java:120)
	at slick.jdbc.JdbcActionComponent$InsertActionComposerImpl$SingleInsertAction.$anonfun$run$15(JdbcActionComponent.scala:522)
	at slick.jdbc.JdbcBackend$SessionDef.withPreparedStatement(JdbcBackend.scala:425)
	at slick.jdbc.JdbcBackend$SessionDef.withPreparedStatement$(JdbcBackend.scala:420)
	at slick.jdbc.JdbcBackend$BaseSession.withPreparedStatement(JdbcBackend.scala:489)
	at slick.jdbc.JdbcActionComponent$InsertActionComposerImpl.preparedInsert(JdbcActionComponent.scala:513)
	at slick.jdbc.JdbcActionComponent$InsertActionComposerImpl$SingleInsertAction.run(JdbcActionComponent.scala:519)
	at slick.jdbc.JdbcActionComponent$SimpleJdbcProfileAction.run(JdbcActionComponent.scala:30)
	at slick.jdbc.JdbcActionComponent$SimpleJdbcProfileAction.run(JdbcActionComponent.scala:27)
	at slick.basic.BasicBackend$DatabaseDef$$anon$3.liftedTree1$1(BasicBackend.scala:275)
	at slick.basic.BasicBackend$DatabaseDef$$anon$3.run(BasicBackend.scala:275)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:748)

Create with Update

Now we want to take our current create logic and to go one step further, allowing the caller to also update the volume of an existing record (upsert). Let's start by modifying our test to expect this new behavior.

  test("create with update") {
    val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    Await.result(future, Duration.Inf)

    val futureUpdate = InventorySingleRecordDao.create(database, TEST_SKU, 3, BIN_01)
    val resultUpdate: Int = Await.result(futureUpdate, Duration.Inf)
    resultUpdate should equal(1)

    // Validate that changes were persisted
    val inventoryTable = TableQuery[InventorySingleRecords]
    val futureFind = database.run(inventoryTable.result)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 3, BIN_01)
  }

With the test in place, we can implement our changes. Before we implement the Slick query it is worth reviewing what our specific database supports. In our case, PostgreSQL https://www.postgresql.org/docs/9.5/sql-insert.html supports upsert behavior with the "ON CONFLICT" clause. We could use a SQL query like this to get an atomic upsert.

INSERT INTO inventory_single (sku, qty, location)
VALUES ('SKU-01', 3, 'LOC-01')
ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
DO UPDATE SET qty = EXCLUDED.qty;

The corresponding raw SQL implemented in Slick (this is a useful reference http://slick.lightbend.com/doc/3.3.0/sql.html) would be:

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Int] = {
    //val query = TableQuery[InventorySingleRecords] += InventorySingleRecord(Option.empty, sku, qty, location)
    val query: DBIO[Int] =
      sqlu"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty;
        """
    db.run(query)
  }

That now gives us the ability to create/update quantities for a SKU and location while working within the existing constraints (we said the sku,location needed to be unique). You may not prefer the raw SQL, but we will explore alternatives in the next section.

Create/Update and Return the New/Updated Record

The create DAO only returns an Int to indicate if a row was modified, we would now like to return the new value of the record pending the create/update. We can modify our SQL by adding the RETURNING clause to the query.

INSERT INTO inventory_single (sku, qty, location)
VALUES ('SKU-01', 3, 'LOC-01')
ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
DO UPDATE SET qty = EXCLUDED.qty
RETURNING sku, qty, location;

Which means we then need to update the types in our DAO and it's tests.

  test("create") {
    val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    val result: Seq[(String, Int, String)] = Await.result(future, Duration.Inf)
    // The expected result is just a count of the number of rows impacted.
    result should contain only((TEST_SKU, 1, BIN_01))

    // Validate that changes were persisted
    val inventoryTable = TableQuery[InventorySingleRecords]
    val futureFind = database.run(inventoryTable.result)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 1, BIN_01)
  }

  test("create with update") {
    val future = InventorySingleRecordDao.create(database, TEST_SKU, 1, BIN_01)
    Await.result(future, Duration.Inf)

    val futureUpdate = InventorySingleRecordDao.create(database, TEST_SKU, 3, BIN_01)
    val resultUpdate: Seq[(String, Int, String)] = Await.result(futureUpdate, Duration.Inf)
    resultUpdate should contain only((TEST_SKU, 3, BIN_01))

    // Validate that changes were persisted
    val inventoryTable = TableQuery[InventorySingleRecords]
    val futureFind = database.run(inventoryTable.result)
    val findResult: Seq[InventorySingleRecord] = Await.result(futureFind, Duration.Inf)
    findResult should contain only InventorySingleRecord(Some(1), TEST_SKU, 3, BIN_01)
  }

The create query in the DAO then becomes:

  def create(db: PostgresProfile.backend.DatabaseDef,
               sku: String,
               qty: Int,
               location: String
              ): Future[Seq[(String, Int, String)]] = {
    val query: DBIO[Seq[(String, Int, String)]] =
      sql"""
           INSERT INTO inventory_single (sku, qty, location)
           VALUES ($sku, $qty, $location)
           ON CONFLICT ON CONSTRAINT inventory_single_sku_location_key
              DO UPDATE SET qty = EXCLUDED.qty
           RETURNING sku, qty, location;
        """.as[(String, Int, String)]
    db.run(query)
  }

The astute reader will notice that we no longer have a mapping to the InventorySingleRecord case class that we set up. We started by just passing back a tuple of (String, Int, String) to represent the record.

Summary

We made it as far as creating the schema, reading from the DB and doing some progressively complicated upsert behavior. In the next posts, we will expand on this functionality and attempt to transfer inventory.

Building on the last several posts (creating a Scalatra service and supporting REST), we would now like to add support for a database. I have chosen to use PostgreSQL for this guide.

Versions being used in this guide:

• Scalatra version 2.6.4 http://scalatra.org/
• Scala version 2.12.6 https://www.scala-lang.org/
• PostgreSQL 10.6 PostgreSQL 10.6 (Ubuntu 10.6-0ubuntu0.18.10.1) on x86_64-pc-linux-gnu installed locally on Ubuntu 18.10 using sudo apt install postgresql https://www.postgresql.org/
• Ubuntu 18.10 http://releases.ubuntu.com/18.10/ (I tend to run this in VMware Workstation 15 Player for convenience)

Assumptions:

• You already have a basic Scalatra service started.

Details

You can start with the official Scalatra guide for integrating with a persistence framework and the manual for Slick:

• http://scalatra.org//guides/2.6/persistence/introduction.html
• http://scalatra.org/guides/2.6/persistence/slick.html

I wanted to start with Slick based on the positive things I had heard about it from my peers more knowledgeable in Scala. However I wanted to start with PostgreSQL instead of H2 (as I was interested in being able to do some naive bench-marking and eventually run the service in Heroku).

Getting Your Database Running

If you prefer to run Docker or have an alternative approach, feel free to skip this section.

This may not be the right path for you, this is optimized for local development and direct administration of the DB. It is NOT SECURE, and NOT MEANT FOR PRODUCTION.

• Install PostgreSQL - I have opted to use the Ubuntu package sudo apt install postgresql. I found this resource helpful (DigitalOcean produces some very helpful guides) https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-18-04
• Create a user and a new DB

sudo -i -u postgres
> createuser --interactive
> createdb toyinventory

• Allow access to the local database via trust authentication (I am using this because I have a single-user workstation for development - PostgreSQL assumes anyone who can connect is authorized with whatever user they want). Some additional references if your interested https://www.postgresql.org/docs/9.1/auth-pg-hba-conf.html and https://www.postgresql.org/docs/9.1/auth-methods.html#AUTH-TRUST
• Use the editor of your choice to open your pg_hba.conf file. sudo emacs /etc/postgresql/10/main/pg_hba.conf and set the IPv4 and IPv6 to trust.

• UPDATE TO GUIDE - I also ended up setting "local" to trust also so that I could easily get assess with psql from the command line
• Restart PostgreSQL sudo service postgresql restart

You can connect and interact with the database via psql using the account you previously created. sudo -i -u toyinventory psql.

You can connect and interact with the database via psql using the account you previously created. psql -U toyinventory. This can be a helpful guide if your PSQL is rusty http://postgresguide.com/utilities/psql.html

You can then validate by accessing the database using IntelliJ, as I frequently prefer to execute queries and inspect the database from IntelliJ.

Creating Table and Records

You will want a simple table and some records to start working with, for this guide we will avoid going into schema management. First, create your table:

CREATE TABLE inventory
(
  id bigserial NOT NULL,
  sku text,
  qty integer, -- https://www.postgresql.org/docs/10/datatype-numeric.html
  description text,
  CONSTRAINT pk PRIMARY KEY (id)
)

A little off topic, but some interesting references if you are considering what column type to use for strings with PostgreSQL https://stackoverflow.com/questions/4848964/postgresql-difference-between-text-and-varchar-character-varying and https://www.depesz.com/2010/03/02/charx-vs-varcharx-vs-varchar-vs-text/

Insert some data to work with:

INSERT INTO inventory(sku, qty, description) VALUES 
('ZL101', 1, 'Black shoes'), 
('ZL102', 0, 'Red dress'), 
('ZL103', 4, 'Block of wood');

Adding the Necessary Scalatra Dependencies

Now that you have a running database, let's get Scalatra to talk to it.

If you started with the Slick documentation http://slick.lightbend.com/doc/3.3.0/gettingstarted.html you found it also used the H2 database. I found it difficult to follow (but that's probably my weakness more than anything).

I added the following dependencies to my projects build.sbt

libraryDependencies ++= Seq(
  "com.typesafe.slick" %% "slick" % "3.3.0",
  "org.postgresql" % "postgresql" % "42.2.5", // org.postgresql.ds.PGSimpleDataSource dependency
)

• Slick version 3.3.0 http://slick.lightbend.com/doc/3.3.0/
• PostgreSQL JDBC https://github.com/pgjdbc/pgjdbc If you went through the Slick documentation you will see that http://slick.lightbend.com/doc/3.3.0/database.html recommended version 9.4-1206-jdbc42 and I have opted to use the most recent version of 42.2.5.

Connecting to the Database

I want to see the code talk to the DB, so I ignored proper management of connections and dependencies to get things started.

I added the following imports to my Servlet that is responsible for the REST endpoints. NOTE - this was where I got tripped up trying to follow the other guides, there are a number of ways to use this library, and if you let IntelliJ handle the auto-import it is very likely that end up with a confusing mess.

import slick.jdbc.PostgresProfile.api._

import scala.concurrent.{Await, Future}
import scala.concurrent.duration.Duration

Now specific the code needed to make the database connection, I have opted to retrieve the postgres user and password from environment variables as opposed to checking them in directly to source code.

val postgres_user = sys.env("postgres_user")
val postgres_password = sys.env("postgres_password")
val connectionUrl = s"jdbc:postgresql://localhost:5432/toyinventory?user=${postgres_user}&password=${postgres_password}"

Now specific a class to model your database record.

class InventoryRecord(tag: Tag) extends
  Table[(Int, String, Int, String)](tag, "inventory") {

  def id = column[Int]("id")
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def description = column[String]("description")

  def * = (id, sku, qty, description)
}

Now your ready to run a SELECT all query using Slick

val db = Database.forURL(connectionUrl, driver = "org.postgresql.Driver")

try {
  val users = TableQuery[InventoryRecord]
  val query = users.map(_.sku)
  val action = query.result
  val result: Future[Seq[String]] = db.run(action)
  val futureResult = Await.result(result, Duration.Inf)
  futureResult.map { sku => logger.debug(s"SKU: ${sku}") }
} finally db.close

Now that you have all of the pieces, I slammed that code into my GET endpoint that I defined in http://honstain.com/rest-in-a-scalatra-service/ and sent some HTTP requests.

Don't forget to set your environment variables if you opt to run via IntelliJ

import org.scalatra._
import org.slf4j.LoggerFactory
// JSON-related libraries
import org.json4s.{DefaultFormats, Formats}
// JSON handling support from Scalatra
import org.scalatra.json._

import slick.jdbc.PostgresProfile.api._

import scala.concurrent.{Await, Future}
import scala.concurrent.duration.Duration
import scala.concurrent.ExecutionContext.Implicits.global

class ToyInventory extends ScalatraServlet with JacksonJsonSupport {

  val logger = LoggerFactory.getLogger(getClass)
  protected implicit val jsonFormats: Formats = DefaultFormats

  before() {
    contentType = formats("json")
  }

  get("/") {
    val postgres_user = sys.env("postgres_user")
    val postgres_password = sys.env("postgres_password")
    val connectionUrl = s"jdbc:postgresql://localhost:5432/toyinventory?user=${postgres_user}&password=${postgres_password}"

    val db = Database.forURL(connectionUrl, driver = "org.postgresql.Driver")

    try {
      val users = TableQuery[InventoryRecord]
      val query = users.map(_.sku)
      val action = query.result
      val result: Future[Seq[String]] = db.run(action)
      val futureResult = Await.result(result, Duration.Inf)
      futureResult.map { sku => logger.debug(s"SKU: ${sku}") }
    } finally db.close

    InventoryData.all
  }

  post("/") {
    val newInventory = parsedBody.extract[Inventory]
    logger.debug(s"Creating inventory sku:${newInventory.sku}")
    logger.debug("Creating inventory {}", newInventory.toString)
    InventoryData.all = newInventory :: InventoryData.all
    newInventory
  }

}

case class Inventory(sku: String, qty: Int, description: String)

object InventoryData {

  var all = List(
    Inventory("ZL101", 1, "Black shoes"),
    Inventory("ZL102", 0, "Red dress"),
    Inventory("ZL103", 4, "Block of wood"),
  )
}

class InventoryRecord(tag: Tag) extends
  Table[(Int, String, Int, String)](tag, "inventory") {

  def id = column[Int]("id")
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def description = column[String]("description")

  def * = (id, sku, qty, description)
}

The result of this generated the following logs, Slick generated a significant amount of logging that I thought was very detailed (but would probably immediately trim down).

Summary

Now that you have a basic query working, you can start writing more advanced queries. You will also want to start managing your database initialization and connections more appropriately.

References I Found Helpful

• Slick Documentation http://scalatra.org/guides/2.6/persistence/slick.html
• Slick Queries http://slick.lightbend.com/doc/3.3.0/queries.html
• PSQL cheat sheet http://postgresguide.com/utilities/psql.html
• This guide helped me by demonstrating some basic postgres queries from Slick http://queirozf.com/entries/scala-slick-simple-example-on-connecting-to-a-postgresql-database

Building on the last several posts (creating a Scalatra service and supporting REST), we would now like to add support for a database. I have chosen to use PostgreSQL for this guide.

Versions being used in this guide:

• Scalatra version 2.6.4 http://scalatra.org/
• Scala version 2.12.6 https://www.scala-lang.org/
• PostgreSQL 10.6 PostgreSQL 10.6 (Ubuntu 10.6-0ubuntu0.18.10.1) on x86_64-pc-linux-gnu installed locally on Ubuntu 18.10 using sudo apt install postgresql https://www.postgresql.org/
• Ubuntu 18.10 http://releases.ubuntu.com/18.10/ (I tend to run this in VMware Workstation 15 Player for convenience)

Assumptions:

• You already have a basic Scalatra service started.

Details

You can start with the official Scalatra guide for integrating with a persistence framework and the manual for Slick:

• http://scalatra.org//guides/2.6/persistence/introduction.html
• http://scalatra.org/guides/2.6/persistence/slick.html

I wanted to start with Slick based on the positive things I had heard about it from my peers more knowledgeable in Scala. However I wanted to start with PostgreSQL instead of H2 (as I was interested in being able to do some naive bench-marking and eventually run the service in Heroku).

Getting Your Database Running

If you prefer to run Docker or have an alternative approach, feel free to skip this section.

This may not be the right path for you, this is optimized for local development and direct administration of the DB. It is NOT SECURE, and NOT MEANT FOR PRODUCTION.

• Install PostgreSQL - I have opted to use the Ubuntu package sudo apt install postgresql. I found this resource helpful (DigitalOcean produces some very helpful guides) https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-18-04
• Create a user and a new DB

sudo -i -u postgres
> createuser --interactive
> createdb toyinventory

• Allow access to the local database via trust authentication (I am using this because I have a single-user workstation for development - PostgreSQL assumes anyone who can connect is authorized with whatever user they want). Some additional references if your interested https://www.postgresql.org/docs/9.1/auth-pg-hba-conf.html and https://www.postgresql.org/docs/9.1/auth-methods.html#AUTH-TRUST
• Use the editor of your choice to open your pg_hba.conf file. sudo emacs /etc/postgresql/10/main/pg_hba.conf and set the IPv4 and IPv6 to trust.

• UPDATE TO GUIDE - I also ended up setting "local" to trust also so that I could easily get assess with psql from the command line
• Restart PostgreSQL sudo service postgresql restart

You can connect and interact with the database via psql using the account you previously created. sudo -i -u toyinventory psql.

You can connect and interact with the database via psql using the account you previously created. psql -U toyinventory. This can be a helpful guide if your PSQL is rusty http://postgresguide.com/utilities/psql.html

You can then validate by accessing the database using IntelliJ, as I frequently prefer to execute queries and inspect the database from IntelliJ.

Creating Table and Records

You will want a simple table and some records to start working with, for this guide we will avoid going into schema management. First, create your table:

CREATE TABLE inventory
(
  id bigserial NOT NULL,
  sku text,
  qty integer, -- https://www.postgresql.org/docs/10/datatype-numeric.html
  description text,
  CONSTRAINT pk PRIMARY KEY (id)
)

A little off topic, but some interesting references if you are considering what column type to use for strings with PostgreSQL https://stackoverflow.com/questions/4848964/postgresql-difference-between-text-and-varchar-character-varying and https://www.depesz.com/2010/03/02/charx-vs-varcharx-vs-varchar-vs-text/

Insert some data to work with:

INSERT INTO inventory(sku, qty, description) VALUES 
('ZL101', 1, 'Black shoes'), 
('ZL102', 0, 'Red dress'), 
('ZL103', 4, 'Block of wood');

Adding the Necessary Scalatra Dependencies

Now that you have a running database, let's get Scalatra to talk to it.

If you started with the Slick documentation http://slick.lightbend.com/doc/3.3.0/gettingstarted.html you found it also used the H2 database. I found it difficult to follow (but that's probably my weakness more than anything).

I added the following dependencies to my projects build.sbt

libraryDependencies ++= Seq(
  "com.typesafe.slick" %% "slick" % "3.3.0",
  "org.postgresql" % "postgresql" % "42.2.5", // org.postgresql.ds.PGSimpleDataSource dependency
)

• Slick version 3.3.0 http://slick.lightbend.com/doc/3.3.0/
• PostgreSQL JDBC https://github.com/pgjdbc/pgjdbc If you went through the Slick documentation you will see that http://slick.lightbend.com/doc/3.3.0/database.html recommended version 9.4-1206-jdbc42 and I have opted to use the most recent version of 42.2.5.

Connecting to the Database

I want to see the code talk to the DB, so I ignored proper management of connections and dependencies to get things started.

I added the following imports to my Servlet that is responsible for the REST endpoints. NOTE - this was where I got tripped up trying to follow the other guides, there are a number of ways to use this library, and if you let IntelliJ handle the auto-import it is very likely that end up with a confusing mess.

import slick.jdbc.PostgresProfile.api._

import scala.concurrent.{Await, Future}
import scala.concurrent.duration.Duration

Now specific the code needed to make the database connection, I have opted to retrieve the postgres user and password from environment variables as opposed to checking them in directly to source code.

val postgres_user = sys.env("postgres_user")
val postgres_password = sys.env("postgres_password")
val connectionUrl = s"jdbc:postgresql://localhost:5432/toyinventory?user=${postgres_user}&password=${postgres_password}"

Now specific a class to model your database record.

class InventoryRecord(tag: Tag) extends
  Table[(Int, String, Int, String)](tag, "inventory") {

  def id = column[Int]("id")
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def description = column[String]("description")

  def * = (id, sku, qty, description)
}

Now your ready to run a SELECT all query using Slick

val db = Database.forURL(connectionUrl, driver = "org.postgresql.Driver")

try {
  val users = TableQuery[InventoryRecord]
  val query = users.map(_.sku)
  val action = query.result
  val result: Future[Seq[String]] = db.run(action)
  val futureResult = Await.result(result, Duration.Inf)
  futureResult.map { sku => logger.debug(s"SKU: ${sku}") }
} finally db.close

Now that you have all of the pieces, I slammed that code into my GET endpoint that I defined in http://honstain.com/rest-in-a-scalatra-service/ and sent some HTTP requests.

Don't forget to set your environment variables if you opt to run via IntelliJ

import org.scalatra._
import org.slf4j.LoggerFactory
// JSON-related libraries
import org.json4s.{DefaultFormats, Formats}
// JSON handling support from Scalatra
import org.scalatra.json._

import slick.jdbc.PostgresProfile.api._

import scala.concurrent.{Await, Future}
import scala.concurrent.duration.Duration
import scala.concurrent.ExecutionContext.Implicits.global

class ToyInventory extends ScalatraServlet with JacksonJsonSupport {

  val logger = LoggerFactory.getLogger(getClass)
  protected implicit val jsonFormats: Formats = DefaultFormats

  before() {
    contentType = formats("json")
  }

  get("/") {
    val postgres_user = sys.env("postgres_user")
    val postgres_password = sys.env("postgres_password")
    val connectionUrl = s"jdbc:postgresql://localhost:5432/toyinventory?user=${postgres_user}&password=${postgres_password}"

    val db = Database.forURL(connectionUrl, driver = "org.postgresql.Driver")

    try {
      val users = TableQuery[InventoryRecord]
      val query = users.map(_.sku)
      val action = query.result
      val result: Future[Seq[String]] = db.run(action)
      val futureResult = Await.result(result, Duration.Inf)
      futureResult.map { sku => logger.debug(s"SKU: ${sku}") }
    } finally db.close

    InventoryData.all
  }

  post("/") {
    val newInventory = parsedBody.extract[Inventory]
    logger.debug(s"Creating inventory sku:${newInventory.sku}")
    logger.debug("Creating inventory {}", newInventory.toString)
    InventoryData.all = newInventory :: InventoryData.all
    newInventory
  }

}

case class Inventory(sku: String, qty: Int, description: String)

object InventoryData {

  var all = List(
    Inventory("ZL101", 1, "Black shoes"),
    Inventory("ZL102", 0, "Red dress"),
    Inventory("ZL103", 4, "Block of wood"),
  )
}

class InventoryRecord(tag: Tag) extends
  Table[(Int, String, Int, String)](tag, "inventory") {

  def id = column[Int]("id")
  def sku = column[String]("sku")
  def qty = column[Int]("qty")
  def description = column[String]("description")

  def * = (id, sku, qty, description)
}

The result of this generated the following logs, Slick generated a significant amount of logging that I thought was very detailed (but would probably immediately trim down).

Summary

Now that you have a basic query working, you can start writing more advanced queries. You will also want to start managing your database initialization and connections more appropriately.

References I Found Helpful

• Slick Documentation http://scalatra.org/guides/2.6/persistence/slick.html
• Slick Queries http://slick.lightbend.com/doc/3.3.0/queries.html
• PSQL cheat sheet http://postgresguide.com/utilities/psql.html
• This guide helped me by demonstrating some basic postgres queries from Slick http://queirozf.com/entries/scala-slick-simple-example-on-connecting-to-a-postgresql-database