DEV Community: Saleor Commerce

Building Reliable Software: The Trap of Convenience

Patryk Zawadzki — Mon, 16 Feb 2026 14:53:09 +0000

When I started to learn programming a PC (as opposed to programming an Amiga), it was still the 20th century. In the days of yore, when electricity was a novel concept and computer screens had to be illuminated by candlelight in the evenings, we'd use languages like C or Pascal. While the standard libraries of those languages provided most of the needed primitives, it was by no means a "batteries included" situation. And even where a standard library solution existed, we'd still drop to inline assembly for performance-critical sections because those computers were definitely not fast enough to spare any CPU cycles. PCs were also still similar enough that they used the same CPU architecture, and thus the same machine code, so the assembly sections were not that hard to maintain.

Today, the x86 architectures come with dozens of optional extensions and you're not even guranteed to encounter an "Intel" machine (technically referred to as "amd64"). RISC CPUs are coming back to reclaim computing thanks to the efforts of Apple (Apple Silicon), Amazon (AWS Graviton), Microsoft (Azure Cobalt), and others licensees of ARM. In 2026, writing assembly code is something you only do if there is absolutely no other solution. The number of versions of that inline section keeps growing with every new CPU family. Meanwhile, modern compilers are getting so good at optimizing the resulting machine code, and the computers got so fast, that manual optimization is usually not worth the effort. Unless it absolutely is.

So the modern programming languages split. There are system programming languages that optimize for the performance with an extra focus on safety, like Rust. And there are application programming languages that optimize for "productivity", that is the speed at which we produce useful software, rather than the speed at which said software runs.

Productivity Through Convenience

Productivity demands higher-order abstractions. Instead of representing how the underlying hardware works, the programming languages and their libraries instead model how people think about the problems.

Thanks to this, instead of writing several pages of C code to allocate a send buffer and a receive buffer, open a socket, set its options, resolve the target hostname, establish a connection, and so on, you can fetch and parse a web resource in a few lines of Python:

import requests

def fetch_json(url):
    data = requests.get(url)
    return data.json()

With just a few keystrokes I can achieve what used to take me hours just to type out. Thanks to both Python (and C#, and TypeScript, and likely also your favorite language) and the requests library (and its equivalents) being open-source and available for everyone to use for free, we can all collectively and individually build more complex systems with less effort.

Except that, as I mentioned in my previous post, it's systems all the way down. And all those systems make a (conscious or not) choice on what it means to be a reliable tool.

As a fun exercise, look at the above example and try to figure out what the biggest problem with that bit of code is. It certainly works for the happy path, which would make it pass a lot of the unit tests!

Let's walk through several (but not all, the complete list would be way too long) of the things that can go wrong in just two lines of code.

A Litany of Failure Modes

data = requests.get(url)
return data.json()

An error will be raised if the URL is not a valid URL (or not even a string, yay modern languages!).
An error will be raised if the target hostname cannot be resolved (either the domain does not exist, or your DNS server cannot be reached).
If the target hostname resolves to multiple IP (IPv6 or IPv4) addresses, then try each one is tried in sequence until one accepts the connection on the destination port. Since no timeout is specified, the default system timeout for TCP is used (6 connection attempts totalling about 127 seconds on modern Linux systems) for each individual IP address. If none of the IP addresses end up accepting, an error is raised.
If the target system does not speak our desired protocol and responds with random gibberish, an error is raised.
An error is raised if the protocol is secure (like HTTPS) and the target server does not offer any of the TLS variants we trust.
If the protocol is secure (like HTTPS) and the target system responds with an invalid TLS certificate (either broken, expired, or not trusted by any of the certificates our system trusts), an error is raised.
An error is raised if the certificate is valid but does not match the target hostname.
If the target system stops responding, an error is raised. Since no timeout is specified, the default system TCP read timeout is used (60 seconds on modern Linux systems). If the target system sends anything during that time window, the system timer will be reset as the read was successful.
If the response is a valid HTTP redirect response, the process is restarted from step 1, using the redirect URL as the new target URL.
If we somehow get to this point (as unlikely as it seems) and the response is not a valid JSON string, an error is raised.

Different parts of the above are problematic, or extremely problematic, depending on what your code is attempting to achieve.

If your goal is to download a movie to watch, preserve artifacts of a system you're about to delete, or create complete copies of websites for a project like the Internet Archive's Wayback Machine, then chances are you want the code to take all the necessary time, perhaps even multiple attempts instead of giving up on the first transient error. The desired outcome is to access the resource at all costs.

But if your goal is to figure out if an order is eligible for free delivery, you probably don't want to keep the user waiting for literally minutes just because some external server crashed. By the time you send your fallback response, the user will be nowhere to be found, having abandoned their order and long since closed the browser tab.

A web API that takes minutes to respond is a useless one, but the same is true for many other use cases. Imagine having to stand in front of an ATM for several minutes before the machine finally spits your card out with an error. All the while people behind you start to make arrangements for your upcoming funeral.

Failing Fast

If you guessed that the problem with the code is that it could crash, you probably guessed wrong. I'm going with "probably", because I don't know what your use case is. But most systems handle failing fast rather gracefully.

A simple try/except block wrapped around the call to our function could take care of specifying the fallback behavior. And even that is absent, the underlying framework is likely built to withstand that and return an error instead of crashing, like in the old times. What it can't do is rewind the time it took the code to fail.

Resisting Abuse

You can't have reliability with at least some resilience (but I guess failing reliably is also a form of consistency). So you need to teach the system how to defend itself against undesirable behaviors. Some of them outright malicious, some not.

In the above example, an extremely malicious behavior would be to take a domain name and configure its zone record to resolve to 511 different IP addresses, all from non-routable network segments such as 196.168.0.0/16.

Or to have a domain resolve to 9 non-routable IPs and one that returns a HTTP redirect to the same domain.

Or to point the URL to a server that streams the response by sending one byte every 50 seconds, thus never triggering a read timeout.

If those numbers sound oddly specific, this is because we did all those things internally at Saleor. I don't remember why 511 was the number of IPs we went for, maybe CloudFlare didn't allow more records to be added, maybe it didn't matter because no one was going to wait for that test to time out anyway.

But a malicious actor could also ask your system to access a URL of an internal system they can't access directly. If the URL comes from an untrusted source, it could be used to probe your internal network for open ports, based on the error codes you send back. And if your system is foolish enough to show the entire "unexpected response" from such an URL, also to steal your credentials.

Did you know that any EC2 instance on AWS can make a request to http://169.254.169.254/latest/meta-data/ to learn about its own roles? And that a subsequent call to http://169.254.169.254/latest/meta-data/iam/security-credentials/<role-id>/ returns both an AWS access key and its corresponding secret? Yikes on leaking that!

Final Thoughts

Convenience is the biggest pitfall of the modern high-abstraction productivity. All the important bits and compromises are buried deep in the convenience layers, making it impossible to reason about systems without popping the hood. Meanwhile, your IDE, your code review tools, your whiteboard interviews, surface the types of problems that—in the grand scheme of things—don't matter all that much: the ones your system can recover from automatically.

If you ever find yourself accessing the great unknown from Python code, take a look at the requests-hardened wrapper we created for requests. It makes it safe to point the library at untrusted URLs from code that doesn't have forever to wait for the outcome. It also works around a DoS potential in Python's standard library that we also reported (responsibly, it's only public because we were asked by the maintainers to make it public).

Make sure your team doesn't mistake simple code for the simplicity of the underlying systems. The reassurance offered by the complexity becoming invisible is a fake one.

Happy failures. Farewell and until next time!

Building Reliable Software: Planning for Things to Break

Patryk Zawadzki — Fri, 13 Feb 2026 15:18:24 +0000

We often joke that software is usually implemented in two steps: the first 80% of the time is spent on making it work, and then the second 80% of the time is spend on making it work well. People mistake demos, proofs-of-concept, and walking skeletons for products because the optimistic path is often realized in full, so under ideal lab conditions, a PoC behaves just like the full product.

At Saleor, where I act as a CTO, we spend a significant part of our engineering effort embracing the different failure states and making sure the unhappy paths are covered as well as the happy ones.

Embracing the Failure

Because it does not matter how good your software is or how expensive your hardware is, something will eventually break. The only systems that never break are ones that are never used. Amazon's AWS spends more money on preventive measures than you will ever be able to, and yet, a major outage took out the entire us-east-1 region just last October. In 2016, the world's largest particle accelerator, CERN's Large Hadron Collider, was taken offline by a single weasel. Google's Chromecast service was down for days because someone forgot to renew an intermediate CA certificate, something that needs to be done once every 10 years.

The question is not if but when. Reliability is both about pushing that point as far it's practically possible and about planning what happens when it inevitably comes. And both suffer from brutally diminishing returns.

Every additional "nine" in your uptime—getting from 90% to 99%, from 99% to 99.9%, and so on—requires ten times as much resources as the previous one. Getting from one nine to two is usually trivial and gives you roughly 33 days of additional uptime per year. The next step is ten times as much work for only 3.2 additional days. Then it's even more expensive and results in just under 8 hours of additional uptime. You then get to 47 minutes, 4.7 minutes, 37 seconds, and so on. At some point the cost of getting to the next step exceeds the losses from being unavailable.

It's similar with your firefighting tools. You can get from multiple down to one business day per simple fix with relatively simple measures. It takes more expensive tools, stricter procedures, and paid on-call duty to guarantee a same-day attempt at fixing. Shortening it further requires investing in even more specialized (and costlier) tools, better training for engineers, and a lot of upfront work on observability. And again, at some point the cost of lowering the downtime even further is guaranteed to exceed the cost of any prevented downtime.

Some of the component failures you'll encounter will be self-inflicted. Because one day you'll discover that a database server needs to be brought offline to upgrade it to the newer version that fixes a critical CVE.

Given all the above, the pragmatic approach dictates that instead of trying to achieve the impossible, we should build systems that anticipate failures, and, ideally, recover from them without human intervention. While every component's availability is capped by the product of all the SLOs of its direct dependencies, the larger system can be built to tolerate at least some failing components.

The CAP Theorem

The CAP theorem dictates that any distributed stateful system can only achieve at most two of the three guarantees: consistency, availability, and partition tolerance.

What is a distributed stateful system? Anything that stores any data and consists of more than one component. A shell script accessing a database is such a system, and so is a Kubernetes service talking to a server-less database.

The consistency guarantee demands that every time the system returns data, it either returns the most up-to-date data, or the read fails. Under no circumstances can the system return a stale copy as doing so could break an even larger system for which your system is a dependency.

The availability guarantee dictates that if the system receives a request, it must not fail to provide a response.

Partition tolerance means the system needs to remain fully operational even if some of its components are unable to communicate with some other components.

I think it's clear that it's impossible for a system to always return the latest data and never return an error while it can't reach its main database. That's why you can only pick two of the virtues and in most cases it's only practical to achieve one.

It's Systems All the Way Down

It's also important to note that any complex solution is usually a multitude of smaller systems in a trench coat. You can have systems within systems and you can pick different corners of the CAP triangle for every individual subsystem.

A practical example may be an online store that uses an external system to figure out if a given order qualifies for free shipping. The free shipping decision is delegated to a third-party system, a black box only accessed through its API. The order lines and the cost of regular shipping are stored in some sort of a database, and the storefront is backed by a web service that needs to return the valid shipping methods.

Now we have the following systems:

The external shipping discount service that we don't control. that can provide any of the CAP guarantees. Whatever it does is beyond our control.
Our internal free shipping eligibility service that depends on the database (as it needs to be able to send the cart contents) and the external service (as it needs to receive the response).
Our public web service that tells the storefront what shipping methods are available that depends on our internal free shipping eligibility service and the database (to figure out the cost of regular shipping).
The entire store that depends on the storefront running in the client's browser being able to communicate, over the internet, with our public web service.

Since we can't do much about the external system (and if it goes down, fixing it is beyond our reach), we can make the pragmatic decision to make any system that depends on it focus on partition tolerance. For example, we could decide that if the external system can't be reached, any order is eligible for free shipping. This way, when the external system inevitably goes down, we can err on the side of generosity and lose some money on shipping but keep our store transactional (which usually more than makes up for the shipping cost). We could also decide the opposite, that if the service is down, no order can be shipped for free, potentially upsetting some customers, but still taking orders from everyone else.

Better Fault Tolerance

I think it's clear that whichever way we choose is preferable to the entire store becoming unavailable and thus accepting no orders at all.

If we broaden up the partition tolerance to general fault tolerance, we can design systems that are internally as fault-tolerant as is pragmatic and externally as available as practically possible. This prevents cracks from propagating from component to component, which gives the larger system a chance of staying transactional even while some of its individual subsystems struggle to stay online.

Fault tolerance can be achieved through documented fallbacks and software design patterns. It's a process that needs to start during the design stages as it's not easy to bolt onto an existing system. All external communication has to be safeguarded and time-boxed, with timeouts short enough not to grind the larger system to a halt. Repeated failures can temporarily eliminate the external dependency through patterns like the circuit breaker.

High availability is usually achieved through redundancy. If a single component has a 1% chance of randomly failing, adding a second duplicate as a fallback reduces that chance to 0.01%. With proper load balancing it also provides additional capacity and is a first step to auto-scaling. Of course, failure is rarely truly random and is often tied to the underlying hardware or other components, so those, too, may need to be made redundant. Multi-zone or multi-region deployments, database clustering, those are all tools that let you lower the chance of things going south at the expense of hard earned cash.

It's up to you to figure out the sweet spot that offers you relative peace of mind while still keeping the operational expenses below the potential losses.

Self-Healing Systems

Given that we can't fully prevent components from failing, what if we at least eliminated the necessity of a human tending to them once they do? A self-healing system is one that is designed to recover from failures without external intervention. I'm not talking about self-adapting code paths that the prophets of AGI promise, I'm talking about automatic retry mechanisms, dead letter queues for unprocessable events, and robust work queues that guarantee at-least-once delivery.

A good system is one that fails in a predictable manner and recovers from the failure in a similarly predictable manner. Eventual consistency is much easier to achieve than immediate consistency. Exactly-once delivery is often impossible to guarantee but at-least-once beats at-most-once under most circumstances.

Design your systems with idempotency in mind so it's safe to retry partial successes. Use fair queues to prevent a single noisy task from adding hours to wait time to all its neighbors. Treat every component as if it was malfunctioning or outright malicious and ask yourself, "How can I have the system not only tolerate this but also fully recover?"

Perhaps the most extreme version of this is the Chaos Monkey from Netflix, a tool designed to break your system's components in controllable yet unpredictable way. The engineers behind Chaos Monkey theorized that in a system designed around reliability, the actions of the Monkey should be completely invisible from the outermost systems perspective. True, with an asterisk that if you get anything wrong, your services are down and you're losing money. Perhaps not everyone can afford that.

And to get it right is often more about being smart than clever. The self-healing part could be as easy as implementing a health check and restarting the component. Or it could mean dropping the cache if you're unable to deserialize its contents, because maybe you forgot that caches can persist across schema changes. Or even restarting your HTTP server every 27 requests while you're figuring out why the 29th request always causes it to crash. Observe your systems and learn from their failures, adding preventive measures for similar classes of future problems.

Remain Vigilant

In 2026, perhaps more than ever, remain vigilant. With the advent of generative AI, some parts of your service will likely end up being written by an LLM. That model, like all models, was trained on a large corpus of code, both purely commercial and Open Source. You have to remember that most of this code, even if it didn't completely neglect its reliability engineering homework, may have vastly different assumptions about where it stands with regard to the CAP theorem.

You cannot blindly transplant code from one project to another, from an AI chatbot, or from a StackOverflow answer, without also consciously asking yourself, "How does this code anticipate and deal with failures? And does it fit my goals for this particular subsystem?"

Happy failures. Farewell and until next time!

Cleaning up large frontend codebase

Lukasz Ostrowski — Wed, 15 Oct 2025 14:21:30 +0000

Recently I started work on the new extensions functionality in Saleor Dashboard. This repo is quite large (450k LOC). I decided to make some cleanup before I introduce the feature.

So the plan was:

Make a feature...
... but first, refactor this and that....
... but first, remove some dead code.

tldr: This post is about removing approx 30k LOC (~6.6%) of the codebase and bundle size (pre-gzipped) lowered by 350KB

Diagnosis

First of all, I have diagnosed where the main gains are. I found three main areas

Invalid module refactor
Stale feature flags
Unused graphQL queries

I wanted to focus mainly on them, because I already had some understanding what's going on. I also wanted to keep them specifically, to reduce the code complexity before my change.

Invalid module refactor

Some time ago Saleor consolidated extensions model - we have merged Apps, Plugins and Webhooks under the single domain - extensions.

The refactor happened using feature flag, but it was not "branching" with specific differences (like show route A or B). Instead entire module was copy pasted 1:1 to a new directory. Then for few months we maintained both of them and they slowly started to differ.

The goal is to drop the old code without breaking anything

Stale feature flags

We also had several feature flags, all of them quite stale. All of them enabled, but entire code branching for disabled flags still was in the source. The goal here was to drop flags and remove dead code.

Unused queries

When I removed flags, I realised many graphQL queries exist in the codebase (and are processed by codegen into types and executable operations). The goal here was to remove as many of them as possible

Techniques

I will not write a deep dive of my every move in this process, but rather share some learnings on the process

Static analysis

During the cleanup I was using existing static analysis tool and improved their config. It's probably the best possible way to diagnose and maintain quality around dead code.

ESLint - detect unused declarations, plugins like graphQL plugin can help detecting issues with queries, etc.
Knip - scans the code for unused exports. Not always working, but it can show not-so-easy dependencies. For example, when code is imported by test, technically this code is not "unused". Knip can detect that
Dependency cruiser - can enforce architecture decisions like forbid circular deps etc

I was using such tools on every PR to validate my changes and find new issues

Tests

Obviously before the refactor, we should have good tests coverage to verify if our changes didn't break anything.

With AI this is easier than ever. Code that is hard to test is often not tested. Claude wrote tests for me, I only reviewed if assertions are valid.

Dropping `default export` and barrel files

Both export default and barrel files (index.js/ts) are known anti-patterns. Their existence make static analysis a nightmare. I did several runs to remove them before moving with other changes

Small PRs

It's tempting to add more and more changes into the same PR, but it never works.

Large PR is hard/impossible to be checked by human properly
LLMS context is too low to review them as well
It's not friendly to ask someone to check such code

Instead, I tried (not always successfully, but it's something) to introduce small and cohesive changes:

PR 1: Remove export default statements and update imports → reviewer only has one "context" to verify and usually if it builds, it works
PR 2: Remove barrel files and update imports → ditto
PR 3: Remove bunch of files, nothing else

etc.

I broke this rule once - and on the review the bug was found. I didn't have time to fix it then, and the change was quite large. Before I was able to go back to my work, I had so many conflicts, I had to start from scratch

AI codemods instead of direct changes

I realized using AI that for such a large codebase, AI often fail to keep the context. I use it to write a test suite, but I can't ask it to refactor the codebase.

What I did instead was starting to use AI to write codemods and other scripts.

For example, I haven't found a tool that would find unused graphQL queries (maybe because we colocate them in .ts files?). It's not easy to find dead code here, because codegen is transforming them to documents, hooks etc. So only way to find it is

Remove document, rebuild codegen, build app/types and check if it's failing
Automate it somehow

To automate it, I gave Claude rules how codegen is generating queries (eg query ProductsPage generates useProductsPage hook). It took approx 30 minutes, but it vibecoded a script that pretty much worked. Script itself can be a trash that I won't maintain, but I can use it to find what to remove, and delete it afterwards.

Keep flags clean

Our flags are controlled custom way, so we don't have any fancy tools to control their staleness. But we should, either use a service or introduce a process that will allow us to periodically drop them. Flags usually add major complexity and should be short living.

Upgrading React 17 to 18 in a large codebase using AI

Lukasz Ostrowski — Mon, 11 Aug 2025 06:24:11 +0000

Recently, at Saleor, we invested some time into CMD+K (command bar) enhancements. While working on it, I realised our custom solution had become too limited and hard to maintain, so it was time to switch to an existing library.

Our Dashboard - a large and mature codebase - is still running on React 17, which turned out to be a blocker because the library requires v18. You might wonder why we’re still on a five-year-old version. The answer is simple: if we don’t need a change, we prioritise other work. Until now, there was no real need to upgrade.

So, the question was: is the new CMD+K enough of a reason to invest the time in upgrading?

Scope of Changes

Fortunately, changes from 17 to 18 are quite simple:

Change how ReactDOM creates a root node (manual change, usually once per project)
Upgrade types: get rid of React.FC and fix types in general.

I couldn’t find a codemod that safely migrated React.FC to the shape:

const Component = (props: Pros) => JSX

so I started doing this manually.

Trying an Agent

Manually fixing these would be a monkey job, so it's time to leverage AI for help.

Spoiler: it worked, but I had a few rounds of incrementing prompts:

Precise Prompt

Explaining to the model what to do worked quite well, but it was too literal.

For example, some components used destructuring ({a, b, c}: Props), others used props: Props. This mattered - in some places we passed props to legacy Material UI styling via useStyles(props), so destructuring broke the flow.

I had to do a few rounds to explain exactly what to do.

Focus on Type-Checked Files

Instead of scanning all the files, I told the agent to run tsc first and aggregate files with errors. This kept the AI focused on relevant files.

Working in Batches

Model context was clearly not enough to scan entire codebase. I explicitly asked to work in batches, clearing context in the meantime.

Saving State

At the end of each prompt, I asked to dump the “enhanced" prompt in the .md file, including:

The original prompt
Its refined version
A list of files already fixed
Any performance optimisations it used

I committed these files to git to make it easy to pause, resume later, or hand off to another AI. The results were surprisingly good.

Picking up by another agent

To avoid hitting usage limits, I switched between Claude Code, Atlassian's Rovo, and JetBrains Juni. Each could pick up exactly where the other left off using the saved prompt.

Live Editing vs Codegen

While researching this topic, I noticed an interesting approach, heavily used by Juni. It created codemods instead of fixing each file directly in the following flow:

Write a transformation script
Test it on one file
Iterate
Apply it to the whole codebase

In future upgrades, I might skip manual batching and go straight to having AI generate a codemod.

Branded Types in TypeScript: techniques

Krzysztof Żuraw — Wed, 11 Jun 2025 05:58:04 +0000

In this post, I’ll walk you through several ways to implement branded types in TypeScript. If you’re new to the concept, check out this intro to branded types before diving in.

Branded types let you create more specific types from primitives like string or number. This helps TypeScript catch bugs where you might accidentally mix up values that are technically the same primitive type but represent different concepts (e.g., UserId vs. string).

1. Using a Type Wrapper

type UserId = string & { __brand: 'UserId' };

const createUserId = (raw: string): UserId => {
  // Add validation logic here if needed
  return raw as UserId;
};

const userId = createUserId("user_id_42");

function getUser(id: UserId) { /* ... */ }

getUser(userId);        // ✅ Works
getUser("user_id_42");  // ❌ Type error

This pattern is lightweight and doesn’t require any extra dependencies. You define a branded type and enforce its usage via a factory function (createUserId). This ensures only properly branded values are passed around your codebase.

Pros:

Zero dependencies
Simple to implement

Cons:

No runtime validation unless you add it yourself
The __brand property is only a TypeScript construct—it doesn’t exist at runtime

2. Using JavaScript Classes / Objects

class UserId {
  constructor(private _id: string) {}

  get id() {
    return this._id;
  }
}

const userId = new UserId("user_id_42");

function getUser(id: UserId) { /* ... */ }

getUser(userId);        // ✅ Works
getUser("user_id_42");  // ❌ Type error

If you want to encapsulate logic (like validation, formatting, or transformation), classes are a good fit. For simple cases, though, this approach can be a bit verbose.

Pros:

Can add methods, validation, and encapsulate logic
Runtime type information

Cons:

More boilerplate
Not always necessary for simple cases
Hard to compare classes - instead of comparing UserId you need to compare its internal id property

3. Using Zod’s `brand()` Method

import { z } from "zod";

const userIdSchema = z
  .string()
  .startsWith("user_id")
  .brand("UserId");

export const createUserId = (raw: string) => userIdSchema.parse(raw);

export type UserId = z.infer<typeof userIdSchema>;

function getUser(id: UserId) { /* ... */ }

const userId = createUserId("user_id_42");
getUser(userId);        // ✅ Works
getUser("user_id_42");  // ❌ Type error

If you’re already using Zod, its `.brand()` method gives you branded types with built-in validation. This is especially handy for APIs or form inputs.

Pros:

Built-in validation
Clean integration with Zod schemas
Type-safe and runtime-safe

Cons:

Requires Zod as a dependency

Summary

Type wrapper: Great for lightweight use cases, no dependencies.
Class-based: Useful when you need encapsulation or extra logic.
Zod brand: Perfect if you already use Zod and want validation + branding.

Branded types are a powerful way to make your TypeScript code safer and more expressive. Pick the approach that fits your project and team best! We in Saleor use both Zod brand and classes.

TypeScript type inference - the dark side

Lukasz Ostrowski — Thu, 05 Jun 2025 06:47:17 +0000

Type inference in TypeScript allows it to figure out what is the type, without explicitly declaring it.

let mutableVersion = 1 // Type is number
const immutableVersion = 1 // Type is 1

You can try it here

TypeScript is not only smart enough to figure out that 1 is a number (duh) but also to understand that const declaration for a primitive can't be reassigned (it's a value, not a reference) - hence it will stay 1 forever, contrary to let which can change.

TypeScript tries to do it's best and usually it works quite well. Together with satisfies and as const statements we can write type-safe code barely declaring anything.

However, there are code-architecture downsides to relying too heavily on type inference, which can eventually make maintenance difficult.

Code first or design first

From my experience, most developers tend to write code and figure out the design as the outcome. "Something" eventually works, a few tests are added on top and we are done.

This approach may be more satisfying but is more "artistic" than an "engineering" approach. The implementation of the logic itself is not too important, if:

It works, which tests proof
Is performant enough to match our metrics
Is encapsulated, so it doesn't leak where it doesn't belong to

If all these 3 are met, we can always easily replace the implementation without affecting the rest of the program.

In the context of the design, encapsulation is critical. It draws the boundary of the abstractions (function, classes, modules) and allows us to design how they coexist and communicate.

At this point, you may be thinking - what does it have in common with inference?

Interface vs inference

By allowing language to infer the type, we accept it to follow a "code first" approach.

const wrapCollection = (collection: Array<{id: string; name: string}>) => collection.reduce((acc, next) => {
  acc[next.id] = next.string
}, {})

What does it return? Apart from the cognitive load (you force someone to read and understand implementation to understand what is returned), you just let TypeScript figure it out. And this is a simple function, for sure you have seen multiple-layered map/filter/reduce monster, best if placed in some React component, to make testing even harder 🥲

You can also be a good colleague and do this.

type CollectionItem = {id: string; name: string}

type WrapCollection = (collection: Array<CollectionItem>): Record<string, string>

const wrapCollection: WrapCollection = ...

What has changed? You started with declaring the data shape and data flow (in and out), then started to implement. Even empty, not implemented functions will be ready to import and write tests at an early stage, where you can validate the API.

Relying on inference is like writing only half of the interface.

Impact on the maintenance

Using inference not only makes it difficult to design a good code but also makes it harder to maintain.

Our wrapCollection in a few months can be used by many engineers in many places. They will rely on inferred type... Then you need to refactor.

Say, you want to change it to for instead of reduce because you operate on a large amount of data and need to improve performance.

You change the inner implementation, but there is no Typescript boundary preventing you from changing the outer shape. Yes, the rest of the code hopefully will be "red" and your tests will fail. But there are many codebases, including ones with not full TypeScript coverage and missing tests.

But every time, your function defines its outer shape (doesn't have to be an interface, can be just a static declaration of the returned type), you are locally protected from breaking that contract.

Summary

I'm not declaring types literally everywhere, but I believe strong type coverage makes code more maintainable.

The more complex the function is, the higher the ROI is. Simple, especially private functions are not that important if we know that only one caller exists. But public methods, widely used across the codebase, benefit from being typed.

You can use ESLint rule to require explicit function return type as well.

Error modelling

Lukasz Ostrowski — Thu, 29 May 2025 06:52:24 +0000

Intro

Let’s have a conceptual look at error modeling. I will use Node.js ecosystem and TypeScript in these examples (and some pseudo-code). I find built-in error management in the JS ecosystem rather poor compared to some other languages, which makes it even more important to treat this topic seriously in this tech stack

I focus on the error modeling, but I don’t focus on the data flow. In another article, I will write more about managing errors Rust-way (which has the built-in distinction between recoverable and non-recoverable errors)

Role of errors

Let’s think about all of these:

SyntaxError: JSON.parse: unexpected character
TypeError: Cannot read property 'value' of null
ValidationError: Email already exists
Internal Server Error

Each of them is an error with a different origin and reason.

First, JSON.parse will happen when we try to parse a string that is not valid JSON. It can occur when we directly catch the external API response body and without checking the response type, we parse e.g. error page which is HTML

Another TypeError can be a pure static code issue - we can try to access a property of nullish value, for example, accessing an object property before it has been created.

Common things for these two is that they are mainly useful for the developer. Best if they are caught during compilation or static analysis if possible, then we can protect ourselves by writing proper tests. Once we reach the runtime, we must ensure we will be able to recognize them when the application crashes - in logs or error-tracking platforms like Sentry. These errors are also often non-recoverable - the app probably can’t find another way to work if the code can’t execute anymore.

Once we reach ValidationError we change the abstraction level. First of all, it’s not language that will throw such errors, but either our database or our internal data layer that is trying e.g. to insert a user into the database. Validation is a graceful way to recover from the issue, giving clear feedback without crashing the app. Such an error is also different from the previous two: it’s rather not interesting to track it in the error tracker (it’s not something we can fix) and this error should be returned in the response, so the user/frontend can handle it.

Internal Server Error on the other hand is an error on the HTTP layer. It’s represented by the semantic code (500) but also provides information that it’s a crash on the server side. Something we definitely should catch and fix. We definitely need as many details as possible in our internal tracking systems, but also do not expose any detail to the front end to avoid leaking any implementation details.

You can see now, that errors are not equal to errors - depending on the context they differ. And for that reason, it requires us to model errors carefully.

Abstraction is the problem

Conceptually errors can propagate through the stack trace:

FunctionA()
  FunctionB()
    FunctionC()
        throw new Error()

The stack trace follows the function execution. Then, the opposite when we are catching it:

try {
  FunctionA()
    try {
      FunctionB()
        try{
          FunctionC()
            throw new Error()
        }
    }
}

The inner error will be traveling through the execution until some catch block intercepts it (or the program finishes with the unhandled exception).

Now when we think about it in scale - a program running hundreds of functions to process the request, we travel through the abstraction layers.

Errors that arise in the controllers can be often caused by validation logic, partially represented business rules (minimal password length), partially expected data format (JSON), etc.

Errors that are caught in the model are likely related strictly to the domain, for example, we can’t add to a cart product that doesn’t exist anymore.

Sometimes, errors happen in external services. Can be our database downtime or external API not responding.

And in every other place, we can face dozens of programming errors, caused by wrong implementation on the language level.

Depending on the abstraction we will need a different handling

Errors chaining

In Python, there is a concept of raise ErrorA from ErrorB. Its purpose is to indicate one error is caused by another, especially useful when we transform errors.

In the JS stack, we can use Error.prototype.cause for that.

// not real API
try {
  stripe.pay()
}catch(stripeError) {
  if(stripeError instanceOf Stripe.InvalidCardDetails) {
    throw new PaymentFailedError("Payment failed to due invalid payment details", {
      cause: stripeError
    })
  }
}

This is a powerful pattern.

First, we have locally intercepted errors from the 3rd party API. It gives us control, at this point, we can log, track, set metrics, emit events, or anything else.
Second, we can match the error type. External APIs will provide us a unified errors layer (likely HTTP serialized errors if a list of enum codes) - some of them can be recoverable, some not.

An error like “invalid card details” is expected and recoverable - the user must try again.

An error like “invalid Stripe secret key” is not an action for the customer, but definitely should reach the payment operator to fix it, otherwise, the business critical path may be down.

Third, we still chain the reasons, allowing us to track not only the stack tree (representing function calls) but also the human-readable messages we wrote in our code.

When we move level up from the payment example above, we will be able to see simplified reasoning of how powerful error matching is:

// controller / app service / use case

...

try {
  paymentProvider.pay(request.body)
}catch(error){
  switch(true) {
    case error instanceOf PaymentFailedError: {
      tracker.trackEvent("invalid_payment")

      // In real life respond with a json-like structure with a payment refusal reason
      return new Response("Invalid payment details", {status: 400})
    }
    case error instanceOf GatewayAuthError: {
      captureException(new Error("Payment Gateway auth rejected", {cause: error}), {level: "FATAL"})

      return new Response("Error processing payment, please try a different payment method",
      {status: 500})
    }
  }
}

In real life, it will be much broader, due to all handled error cases - but conceptually, we can achieve the same thing: a strong and clear distinction between what class of error we are dealing with, who should receive it, what data we provide and how do we monitor these.

Passing cause gives us additional context we can log (e.g. into Sentry), but we don’t have to return it to the storefront. Or maybe we want to, but only for test environments (we do that in our Stripe App in Saleor)

Error matching (that can be implemented with extending Errors or by enum-like reasons) allows us to route error handling and react properly depending on the issue.

Summary

Try to think about what types of errors your application can produce
Model what data you need to attach to your errors (both internal and external systems)
Leverage the Error.prototype.cause field to chain errors
Transform errors when they travel through the abstraction layers

In the upcoming article, I will write more about error implementation and error flow in the application.

Dynamic Configuration for MCP Servers Using Environment Variables

Krzysztof Żuraw — Thu, 29 May 2025 06:24:56 +0000

This blog post explains how to configure Model Context Protocol (MCP) server that can be dynamically controlled through environment variables.

Problem

When setting up mcp-graphql, we needed a way for the MCP server to use a dynamic GraphQL endpoint and token. Hardcoding these values was not an option, as different Saleor environments require different configurations.

Solution

Here’s what we did:

Created a shell script to manage the mcp-graphql startup.
Loaded the endpoint and token from a .env file within the script.
Launched the MCP server using these environment variables.
Used this shell script as the entry point for MCP configuration in clients like Cursor or VSCode

Below is the shell script (start-mcp-graphql.sh) that performs steps 1–3:

#!/usr/bin/env bash

set -a
# Load environment variables from .env file next to this script
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/.env"
set +a

ENDPOINT="$MCP_GRAPHQL_ENDPOINT" HEADERS="{\"Authorization\":\"Bearer $MCP_GRAPHQL_TOKEN\"}" npx mcp-graphql

Using the Script in MCP Clients

To use this setup with Cursor, add the following to your configuration:

{
  "mcpServers": {
    "Saleor GraphQL API": {
      "command": "./mcp/start-mcp-graphql.sh"
    }
  }
}

For VSCode, configure the server as follows:

{
  "servers": {
    "Saleor GraphQL API": {
      "type": "stdio",
      "command": "${workspaceFolder}/mcp/start-mcp-graphql.sh"
    }
  }
}

Summary

With this approach, you can easily configure your MCP server dynamically using environment variables. You’ll find all the source code, scripts, and editor configs ready to explore in the Saleor apps repository.

UUID migration in Django with PostgreSQL

Iga Karbowiak — Tue, 18 Feb 2025 11:38:54 +0000

What is UUID?

UUID (universally unique identifier) is a 128-bit label, generated with the use of the standardized algorithm, almost impossible to duplicate, which makes it a perfect identifier. It’s represented as a string that contains five groups of 32 hexadecimal digits separated by hyphens. Here is an example:

f6a7f195-8220-408c-9906-7395b870db61

Why it’s so useful?

The question arises as to why UUID is better than the typical sequential integer Primary Key (PK) generated by the database, which seems to be handled efficiently.
We have been using integer IDs for many years, as this is what databases and Django does by default. We decided to move to UUID for a few reasons.

Firstly, UUIDs are unpredictable, unlike standard integer IDs. This lack of predictability enhances security.

Secondly, consider a system usable both online and offline, where users can create new content. When the user reconnects to the internet, the new instances are merged into the database. With conventional auto-incrementing primary keys, there's a significant chance of conflicts. However, by employing UUIDs as primary keys, the likelihood of encountering such conflicts is nearly eliminated, providing a robust solution to potential problems.

Aside from that UUIDs are less prone to human error when writing queries and working with code, it's hard to spot that a wrong field has been used in a JOIN statement and using integer IDs is less likely to cause an error in cases like that. With UUIDs it's less likely.

How to migrate my data from ID to UUID while ensuring both the wolves are satisfied and the sheep remain unharmed

So, what should you do if you decide that UUIDs are necessary and want to migrate your database objects to use UUIDs as primary keys? If you’re in the early stages, without a production environment, the transition is relatively straightforward. However, if your system is already in production, hosting millions of objects with complex relationships, you’ll need to carefully consider this decision. The process can be challenging and require significant effort. But don’t worry, I’ll guide you through it to make it as smooth as possible. 🙂

Happy scenario

To illustrate the problem, imagine we have the following Order model, which represents an order placed by a customer in an online store.

class Order(models.Model):
    id = models.PositiveIntegerField(unique=True)
    created_at = models.DateTimeField(auto_now_add=True)
    total_price = models.DecimalField(
        max_digits=10,
        decimal_places=2,
    )
    currency = models.CharField(
        max_length=3,
    )

The most straightforward solution, that probably came to your mind, is to add a new UUID field that will be the new primary key (PK). Let’s name it token. Populate it with unique values and make this field the new PK. Let's illustrate this process using the Order model as an example.

Note: All examples in this article are for illustration purposes; production systems will need solutions that scale with locking and batch updates.

Migration for adding new token field:

from django.db import migrations, models
import uuid

class Migration(migrations.Migration):

    dependencies = [
        ('order', '0135_alter_order_options'),
    ]

    operations = [
        migrations.AddField(
            model_name='order',
            name='token',
            field=models.UUIDField(null=True, unique=True, blank=True),
        )
    ]

Custom migration that populates the token field of existing instances with unique UUID values.

from django.db import migrations
from django.contrib.postgres.functions import RandomUUID

def set_order_token_values(apps, _schema_editor):
    Order = apps.get_model("order", "Order")

    Order.objects.filter(token__isnull=True).update(
        token=RandomUUID()
    )

class Migration(migrations.Migration):

    dependencies = [
        ('order', '0136_order_token'),
    ]

    operations = [
        migrations.RunPython(
            set_order_token_values,
            migrations.RunPython.noop,
        ),
    ]

Changing token into the primary key

from django.db import migrations, models
import uuid

class Migration(migrations.Migration):

    dependencies = [
        ("order", "0137_fulfil_order_token"),
    ]

    operations = [
        migrations.AlterField(
            model_name="order",
            name="token",
            field=models.UUIDField(
                default=uuid.uuid4,
                editable=False,
                primary_key=True,
                serialize=False,
                unique=True,
            ),
        ),
    ]

And... this will work, but EXCLUSIVELY when your model contains ONLY one to many relations.

Now, consider that the Order model has a many-to-one relationship with the Invoice model, where each Invoice represents a generated invoice.

class Invoice(models.Model):
    order = models.ForeignKey(
        Order,
        related_name="invoices",
        null=True,
        on_delete=models.SET_NULL,
    )

In this case, the migration would fail with the following error:

django.db.utils.InternalError: cannot drop constraint order_ordereditem_pkey on table order_order because other objects depend on it.

Why is that?

The reason is that your related models will still have primary key columns pointing to the obsolete pk values, which will no longer exist. If things seem a bit foggy, no worries! Check out the next section that explains in detail how relationships are established in the database.

How the relations are defined in your database?

Before we go on let me explain how the relations that you define in ORM are implemented in the database. If it’s clear to you, you can skip this section and go directly to So what is the problem?

The relational database consists of tables with columns and constraints that specify the rules for the data in tables. All limitations are ensured by the constraints, like uniqueness, value requirement, primary keys, and relations.

Many-to-one

In the many-to-one relation, we have two models where the entity of model A can have multiple associations with entities of model B, but the entity of model B can have only one association with the entity of model A.

In the Django framework, it’s defined with the use of ForeignKey in model B, which points the model A. Under the hood, the new column is added to the model B, and the foreign key constraint is created. The column name is the field name with _id ending and will keep the ids of associated entities. The foreign key constraint is just the rule of the database table (model A) that says the values in a given column must match the values (in our case the id) of a column in some other table (model A). The referenced column (in our case is on mode a) must contain only unique values. So the foreign key constraint depends on the unique or primary key constraint from the relational table.

One-to-one

In one-to-one relationship, the entity of model A can have only one association with entities of model B, and the same rule applies to model A in relation to model B. In the Django framework, it’s defined with the use of the OneToOne field on any of those models. Under the hood, the same things happened as in a many-to-one relationship, but also the unique constraint for the newly created column is added, to ensure that only one entity of model A will exist with the given field value of the pointed column in table B.

Many-to-many

In many-to-many relation entities of model A can have multiple associations with entities of model B, and model B can have multiple associations with entities of model A. In Django framework, it’s defined with the use of the ManyToMany field on any model. Under the hood, this case is a little bit more complex than the previous ones. As we can have multiple connections from both sides of the relationship, we cannot just create a new column on one of the tables. Instead, a new table is created that keeps the ids from both sides of relations. The new table contains columns, one for each site of relations, that keep the corresponding entity field value. To ensure references, for each field the foreign key constraint is created. Additionally, a unique constraint is added to ensure that there is only one row responsible for the relationship between every two instances.

So what is the problem?

As we learned in the previous section, relationships based on foreign key constraints utilize a primary key or unique constraint. Modifying the model's pk to UUID involves recreating the primary key, which deletes the old constraint and creates a new one. If you try to change the primary key, you might encounter errors such as:

django.db.utils.InternalError: cannot drop constraint order_ordereditem_pkey on table order_order because other objects depend on it.

This error implies that the primary key constraint of the id field, which defines foreign key relations, cannot be dropped.

That's why we had to update the relations before modifying the pk.

The solution in a nutshell

To solve the issue, we will introduce a new field called old_id to keep a copy of the old Order id. Then, we will redirect our existing relationships to this new field, and create another field on related models to store the new UUID values (that will become the pk values) of related instances. After changing the ID to UUID in our target model, on the related models, we'll transform the fields that store related instances' UUID values into relational fields, and remove the old relational fields pointing to old_ids. This way, we’ll maintain the same relationships, but with pointing to new UUID values. Sounds complicated? Let’s explore the whole process in the example to make it clear.

💡 Solution Shortcut

On the target model (e.g. Order) create the new fields, one the UUID field (e.g. token field) that will become a PK, and one for keeping the old ID (e.g. old_id field)
Populate those fields
Redirect each existing relation to the field with the old id (old_id field)
On each relation model create a new field that will keep the new UUID values of the related instances (e.g. order_token)
Change the UUID field into the primary key.
On each relation model, change the field that keeps new UUID values (order_token) into the relation field (e.g.ForeginKey)
On each relation model, remove the old relation field
On each relation model, rename the new relation field to the initial name

Preparation

Before delving into managing relationships, let's add an old_id field to store a copy of the previous integer primary key. We also need a token field, which will later serve as our new primary key. Let’s update the changes introduced in our happy scenario.

The first step is adding a new nullable token and old_id fields.

Here are the changes in the models.py file:

class Order(models.Model):
    token = models.UUIDField(null=True, unique=True)
    old_id = models.PositiveIntegerField(unique=True, null=True, blank=True)

And corresponding data migration:

from django.db import migrations, models
import uuid

class Migration(migrations.Migration):

    dependencies = [
        ('order', '0135_alter_order_options'),
    ]

    operations = [
        migrations.AddField(
            model_name='order',
            name='token',
            field=models.UUIDField(null=True, unique=True, blank=True),
        ),
        migrations.AddField(
            model_name='order',
            name='old_id',
            field=models.PositiveIntegerField(blank=True, null=True),
        ),
    ]

Next, besides populating the token field of existing instances with unique UUID values, we'll also copy the current id to the old_id field using a custom migration.

from django.db import migrations
from django.contrib.postgres.functions import RandomUUID

def set_order_token_values(apps, _schema_editor):
    Order = apps.get_model("order", "Order")

    Order.objects.filter(token__isnull=True).update(
        token=RandomUUID()
    )

def set_order_old_id(apps, schema_editor):
    Order = apps.get_model("order", "Order")

    Order.objects.all().update(old_id=F("id"))

class Migration(migrations.Migration):

    dependencies = [
        ('order', '0136_order_token_and_old_id'),
    ]

    operations = [
        migrations.RunPython(
            set_order_token_values,
            reverse_code=migrations.RunPython.noop,
        ),
        migrations.RunPython(
            set_order_old_id,
            reverse_code=migrations.RunPython.noop
        ),
    ]

Handling database relations

Now, we can move to the question: what is the easiest and safest way to update the model relations?

We need to handle all relations: many to one, many to many and one to one. In all cases, we can split the changes into two parts: before model id migration to UUID, and after.

Now, let's examine each step for each relation type in detail.

Few tips at the beginning:

Make sure that at each stage of the migration, you hold the identifier of the related objects that will allow to recreate the relationships.
Always create a full backup and test the code before running the migrations. If something goes wrong, it might be challenging or even impossible to undo.
Be patient. If the model you're migrating has numerous relations, preparing everything might take some time, but don’t give up it’s doable!

💡 Our goal in this data migration is to preserve the references between objects.

Before `UUID` migration

This phase comprises two steps:

Redirect each existing relation to the old_id field.
For each relation model, create and populate a new field (order_token) that will store the new UUID values of the related order instances.

Let’s see how to apply those steps to both many-to-one, one-to-one, and many-to-many relations.

Many-to-one and one-to-one relationship

The many-to-one and one-to-one relations are similar. The only difference is that the one-to-one relation has an additional unique constraint. Therefore, the method for handling these relations is the same.
In those cases, we need to prepare migrations on the model where the relation is defined. Let’s see the process on an example of Invoice that has Many-to-one relation with Order model:

The first step is to define the UUID field that will hold the new UUID values of related objects. In the example below, we have the Invoice model that is related to Order. We're adding a new field, order_token, which will be filled with the new token value of the corresponding Order instances.

class Invoice(models.Model):
    order = models.ForeignKey(
        Order,
        related_name="invoices",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
    )
    order_token = models.UUIDField(null=True)

The migration as follows:

from django.db import migrations, models

class Migration(migrations.Migration):

    dependencies = [
        ("invoice", "0006_invoiceevent_app"),
    ]

    operations = [
        migrations.AddField(
            model_name="invoice",
            name="order_token",
            field=models.UUIDField(null=True),
        ),
    ]

The next step is to populate this new field with corresponding token values. We could write a Python function for this, but it could be challenging to write an efficient one for a large dataset. The quickest solution is to write a simple SQL operation:
```
from django.db import migrations

class Migration(migrations.Migration):

    dependencies = [
        ("invoice", "0007_invoice_order_token"),
                ("order", "0137_fulfil_order_token_and_old_id"),
    ]

    operations = [
        migrations.RunSQL(
            """
            UPDATE invoice_invoice
            SET order_token = (
                SELECT token
                FROM order_order
                WHERE invoice_invoice.order_id = order_order.id
            )
            WHERE order_id IS NOT NULL;
            """,
            reverse_sql=migrations.RunSQL.noop,
        ),
    ]
```
So, what's going on here? We're updating the order_token column in the invoice_invoice table, which corresponds to the Invoice model. For all instances where the Order relation exists, we populate the new order_token field with the token value from the corresponding Order instance. This token value is sourced from the order_order table, where the id matches the order_id from invoice_invoice table.

Also, note that the dependencies list is extended with the order migration. We need to ensure that this migration is applied after the migration that populates the new token field in the order model.

💡 To write an SQL operation, it's essential to know the table and column names. In Django, the table name is formed by joining the app name and model name with an underscore. If you are unsure about your table name, you can always check it in your database shell.

The final step is to change the current relation field to point to the old_id field. This action will drop the existing foreign key constraint that relies on the primary key constraint, and create a new one for the old_id field. You can see this change in the models.py file:

class Invoice(models.Model):
    order = models.ForeignKey(
        Order,
        related_name="invoices",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        to_field="old_id",
    )
    order_token = models.UUIDField(null=True)

And corresponding migration:

from django.db import migrations, models
import django.db.models.deletion

class Migration(migrations.Migration):

    dependencies = [
        ("invoice", "0008_fulfill_invoice_order_token"),
    ]

    operations = [
        migrations.AlterField(
            model_name="invoice",
            name="order",
            field=models.ForeignKey(
                null=True,
                on_delete=django.db.models.deletion.SET_NULL,
                related_name="invoices",
                to="order.order",
                to_field="old_id",
            ),
        ),
    ]

Be sure to prepare these migrations for all models that depend on a changing model.

Many-to-many relations

For many_to_many relations, we need to perform similar steps but operate on the cross-reference table created for this relation. This involves writing an SQL operation to execute the changes.

We’ll analyze the steps in the example of the relation between GiftCard and Order.

class Order(models.Model):
    gift_cards = models.ManyToManyField(
        GiftCard,
        blank=True,
        related_name="orders"
    )

Similar to the previous steps, firstly we will add a new column to store the new token values.
```
ALTER TABLE order_order_gift_cards
ADD COLUMN order_token uuid;
```
Next, we aim to fill the newly added column with corresponding values. In this case, we don't need to check if the column is empty since all instances of cross-reference table must have a value.
```
UPDATE order_order_gift_cards
SET order_token = (
    SELECT token
    FROM order_order
    WHERE order_order_gift_cards.order_id = order_order.id
);
```

Now, we can set the condition that the new column order_token must not be null:

ALTER TABLE order_order_gift_cards
ALTER COLUMN order_token SET NOT NULL;

The next step is to remove the old foreign constraint for the column that points to the current id field. You need to find the name of this constraint. As before, you can check it in the psql command line or the administration platform - pgAdmin.
```
ALTER TABLE order_order_gift_cards
DROP CONSTRAINT order_order_gift_cards_order_id_ce5608c4_fk_order_order_id;
```

The final step involves creating a new foreign key constraint for our column that stores token values.

ALTER TABLE order_order_gift_cards
ADD CONSTRAINT order_order_gift_cards_order_id_fk_order_order_old_id
FOREIGN KEY (order_id) REFERENCES order_order (old_id);

Now, let's consolidate everything into the migration:

from django.db import migrations

class Migration(migrations.Migration):

    dependencies = [
        ("order", "0137_fulfil_order_token_and_old_id"),
    ]

    operations = [
    migrations.RunSQL(
            """
            ALTER TABLE order_order_gift_cards
            ADD COLUMN order_token uuid;

            UPDATE order_order_gift_cards
            SET order_token = (
                SELECT token
                FROM order_order
                WHERE order_order_gift_cards.order_id = order_order.id
            );

            ALTER TABLE order_order_gift_cards
            ALTER COLUMN order_token SET NOT NULL;

            ALTER TABLE order_order_gift_cards
            DROP CONSTRAINT
                    order_order_gift_cards_order_id_ce5608c4_fk_order_order_id;

            ALTER TABLE order_order_gift_cards
            ADD CONSTRAINT order_order_gift_cards_order_id_fk_order_order_old_id
                FOREIGN KEY (order_id) REFERENCES order_order (old_id);

            """,
            reverse_sql=migrations.RunSQL.noop,
        ),
    ]

As before, remember to create corresponding migrations for all many-to-many relationships linked to the model you're modifying.

Afterward, we are prepared to change the primary key to the UUID value.

Set `UUID` column as the primary key

Modifying the model pk also involves two steps, but both can be executed within a single migration.

First, we aim to convert our token value into a primary key. Django will automatically eliminate the old id field along with the primary key constraint. The modifications in the models.py file will appear as follows:

class Order(models.Model):
    token = models.UUIDField(
        primary_key=True,
        editable=False,
        unique=True,
        default=uuid4
    )
    old_id = models.PositiveIntegerField(
        unique=True,
        null=True,
        blank=True
    )

Next, we will rename the token to id to achieve the target state:

class Order(models.Model):
    id = models.UUIDField(
       primary_key=True,
       editable=False,
       unique=True,
       default=uuid4
    )
    old_id = models.PositiveIntegerField(
       unique=True,
       null=True,
       blank=True
    )

Here is the migration that will combine both changes:

from django.db import migrations, models
import uuid

class Migration(migrations.Migration):

    dependencies = [
        ("order", "0138_alter_order_gift_cards"),
        ("invoice", "0008_fulfill_invoice_order_token"),
    ]

    operations = [
        migrations.RemoveField(
            model_name="order",
            name="id",
        ),
        migrations.AlterField(
            model_name="order",
            name="token",
            field=models.UUIDField(
                default=uuid.uuid4,
                editable=False,
                primary_key=True,
                serialize=False,
                unique=True,
            ),
        ),
        migrations.RenameField(
            model_name="order",
            old_name="token",
            new_name="id",
        ),
    ]

What’s important, the migration's dependencies list must include all migrations that set token values on new temporary fields and redirect relation to old_id. In this context, the required migration to include in the dependencies list is 0008_fulfill_invoice_order_token from the invoice app.

After `UUID` migration

Now we are almost done. The last step is to rewrite the relations to point at the new primary key field instead of old_id.

The steps for this phase applied to the relation models are:

Change the field that keeps new UUID values (order_token) into the relation field -ForeginKey
Remove the old relation field
Rename the new relation field to the initial name

Let’s analyze those in our example.

Many-to-one and one-to-one relationship

The steps for rewriting the many-to-one and one-to-one relationships can be combined into one migration. Each step will be explained separately, and then we'll consolidate them into a single migration.

Firstly, our goal is to convert all temporary fields storing instances' token values into relational fields. Specifically, we will convert the Invoice.order_token UUID field into a ForeignKey, as follows:

class Invoice(models.Model):
    order = models.ForeignKey(
        Order,
        related_name="invoices",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        to_field="old_id",
    )
    order_token = models.ForeignKey(
        Order,
        null=False,
        blank=False,
        on_delete=models.CASCADE,
    )

Migration operation:

migrations.AlterField(
    model_name="invoice",
    name="order_token",
    field=models.ForeignKey(
        on_delete=django.db.models.deletion.CASCADE, to="order.order"
    ),
)

The next step is to delete the previous relation field which was pointing to old_id. It's no longer needed since we now have a field pointing to the new Order primary key. As a result, the Invoice model will only retain the order_token field.

class Invoice(models.Model):
    order_token = models.ForeignKey(
        Order,
        null=False,
        blank=False,
        on_delete=models.CASCADE,
    )

Migration operation:

migrations.RemoveField(
    model_name="invoice",
    name="order",
)

Next, we will rename the order_token field to match the name of the field we previously removed. So we are changing order_token to order field.

class Invoice(models.Model):
    order = models.ForeignKey(
        Order,
        null=False,
        blank=False,
        on_delete=models.CASCADE,
    )

Migration operation:

migrations.RenameField(
    model_name="invoice",
    old_name="order_token",
    new_name="order",
)

The final step involves modifying our new relational field to match the original one. In our case, the only change is to set the proper related_name value.

class Invoice(models.Model):
    order = models.ForeignKey(
        Order,
        null=False,
        blank=False,
        on_delete=models.CASCADE,
        related_name="invoices",
    )

Migration operation:

migrations.AlterField(
    model_name="invoice",
    name="order",
    field=models.ForeignKey(
        on_delete=django.db.models.deletion.CASCADE,
        related_name="invoices",
        to="order.order",
    ),
)

Bringing it all together, the migration will look as follows:

from django.db import migrations, models
import django.db.models.deletion

class Migration(migrations.Migration):

    dependencies = [
        ("order", "0139_update_order_pk"),
        ("invoice", "0009_alter_invoice_order"),
    ]

    operations = [
        migrations.AlterField(
            model_name="invoice",
            name="order_token",
            field=models.ForeignKey(
                on_delete=django.db.models.deletion.CASCADE, to="order.order"
            ),
        ),
        migrations.RemoveField(
            model_name="invoice",
            name="order",
        ),
        migrations.RenameField(
            model_name="invoice",
            old_name="order_token",
            new_name="order",
        ),
        migrations.AlterField(
            model_name="invoice",
            name="order",
            field=models.ForeignKey(
                on_delete=django.db.models.deletion.CASCADE,
                related_name="invoices",
                to="order.order",
            ),
        ),
   ]

Naturally, our migration must depend on the migration from the order module that changes id to UUID. If not, we will encounter an error during the migration process.

💡 Remember to apply the changes to all corresponding models.

Many-to-many relations

Changes to many-to-many relationships, as before, are more complex. We need to perform the same changes as for many-to-one relationships, but in the proxy table using SQL operations.

First, we will add the ForeignKey constraint to our field that stores the token value of corresponding order instances. Since the id has already been migrated to UUID, we will point to the id field of the Order model:
```
ALTER TABLE order_order_gift_cards
ADD CONSTRAINT order_order_gift_cards_order_token_fk_order_order_id
FOREIGN KEY (order_token) REFERENCES order_order (id);
```

The next step is to remove the constraint that we previously created, which points to the old_id field.

ALTER TABLE order_order_gift_cards
DROP CONSTRAINT order_order_gift_cards_order_id_fk_order_order_old_id;

Now, we can delete the column that holds the old ID values. We wouldn't be able to do this without the previous step.
```
ALTER TABLE order_order_gift_cards
DROP COLUMN order_id;
```

Afterward, rename the column that points to the UUID values to the initial name.

ALTER TABLE order_order_gift_cards
RENAME COLUMN order_token TO order_id;

The final step involves renaming the constraint that was created in step 1 to match the new column name:

ALTER TABLE order_order_gift_cards
RENAME CONSTRAINT order_order_gift_cards_order_token_fk_order_order_id
TO order_order_gift_cards_order_id_ce5608c4_fk_order_order_id;

Bringing it all together, the migration will look as follows:

class Migration(migrations.Migration):

    dependencies = [
        ("order", "0139_update_order_pk"),
    ]

    operations = [
        # rewrite order - gift cards relation - all operations are performed on
        # order_order_gift_cards table which is responsible for order-gift cards
        # many to many relation
        #   - add fk constraint to order id
        #   - delete constraint to order old_id
        #   - delete order_id column
        #   - rename order_token to order_id
        #   - rename newly added constraint
        migrations.RunSQL(
            """
            ALTER TABLE order_order_gift_cards
            ADD CONSTRAINT order_order_gift_cards_order_token_fk_order_order_id
                FOREIGN KEY (order_token) REFERENCES order_order (id);

            ALTER TABLE order_order_gift_cards
            DROP CONSTRAINT order_order_gift_cards_order_id_fk_order_order_old_id;

            ALTER TABLE order_order_gift_cards
            DROP COLUMN order_id;

            ALTER TABLE order_order_gift_cards
            RENAME COLUMN order_token TO order_id;

            ALTER TABLE order_order_gift_cards
            RENAME CONSTRAINT order_order_gift_cards_order_token_fk_order_order_id
            TO order_order_gift_cards_order_id_ce5608c4_fk_order_order_id;
            """,
            reverse_sql=migrations.RunSQL.noop,
        )
    ]

Again, remember to include the migrations responsible for changing the primary key in your dependencies list.

And that's it. We have returned to the primary stage with all the relations intact, but with the model id changed to UUID. ✨

At the end

At the end, you can discard old_id if it's not needed. Also, reconsider the default ordering. If your default ordering uses pk, it will no longer work as before, since the instances won't be sorted in the creation order due to the random value of UUID. If you wish to maintain the order of instance creation, consider adding a creation date to your model, if one doesn't exist, and sort by this value.

The field responsible for the creation date can be added in the same step where token and old_id are added. To preserve the old order, fill the instances with the current date and time, replacing the seconds with the old id value.

Conclusion

As you can see, there are lots of steps to do, but I hope that this tutorial helps you go smoothly through this process with an understanding of each step.

You can also check our https://github.com/saleor/saleor repository for real-life examples. We performed such operations on Order, OrderLine, and CheckoutLine models.

DynamoDB access modeling for multi-tenant services

Krzysztof Żuraw — Fri, 14 Feb 2025 10:11:00 +0000

Recently at Saleor we encountered the challenge of implementing multi-tenancy in Saleor apps. In this blog post, I'll share my experience with access modelling when using DynamoDB for multi-tenant services.

Problem

When developing a Saleor app that can be installed for multiple tenants, we faced several requirements:

Ensure data isolation between tenants
Provide quick access times for serverless functions (which are main components of Saleor apps)
Achieve good scalability

Given these requirements, we chose DynamoDB as our database solution. Its flexible schema, low latency, and ability to scale horizontally made it an ideal fit for our multi-tenant Saleor app.

Modelling Approach

Before diving into implementation, it's crucial to model our data and access patterns. Let's take the example of storing app configurations for multiple tenants.

Access Patterns

We identified two main access patterns:

Read operations:
- API routes: Retrieve API keys for third-party services from saved configuration
- UI: Display current configuration values to end-users (via tRPC)
Write operations:
- UI: Update app configuration (via tRPC)

Data Structure

Our app configuration typically consists of:

Encrypted fields (e.g., API keys for third-party services)
Mappings between Saleor channels and app configuration

DynamoDB Table Design

Following recommendations from The DynamoDB Book we decided to store all data for each app in a single DynamoDB table. Here's how we structured our table:

Primary Key (PK)

We use a composite primary key in the format:

{saleorApiUrl}#{saleorAppId}

This structure ensures that:

Each tenant's data is isolated
New app installations don't access data from previous installations
App can fetch multiple entities from DynamoDB in one request

Sort Key (SK)

Our sort key follows the format:

APP_CONFIG#{configKey}

Where configKey represents the configuration version. This approach allows for easy future migrations to new configuration versions.

Benefits of This Design

Multi-tenancy: The saleorApiUrl in the PK enables multi-tenancy by separating data for different Saleor instances.
Versioning: The configKey in the SK allows for multiple versions of configurations.
Flexibility: We can easily add other entity types by using different SK prefixes (e.g., TRANSACTION#{transactionId} for storing webhook-related information).

Implementation Example

Here's a TypeScript example of how we might query our DynamoDB table:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

async function getAppConfig(saleorApiUrl: string, saleorAppId: string, configKey: string) {
  const command = new GetCommand({
    TableName: "AppTable",
    Key: {
      PK: `${saleorApiUrl}#${saleorAppId}`,
      SK: `APP_CONFIG#${configKey}`,
    },
  });

  const response = await docClient.send(command);
  return response.Item;
}

Summary

When modelling DynamoDB access for multi-tenant services:

Identify access patterns: Understand how your data will be read and written.
Define data structure: Determine what needs to be stored in DynamoDB.
Design table structure: Choose appropriate primary and sort keys to enable efficient querying and ensure data isolation between tenants.

By following these steps, we've created a scalable and efficient DynamoDB structure for our multi-tenant Saleor app. This approach allows us to maintain data isolation, achieve quick access times, and easily adapt to future requirements.

From Cypress to Playwright - Saleor’s Voyage

Michalina Graczyk — Fri, 29 Nov 2024 11:05:23 +0000

This is the story of our path from our early days of automated testing, to adapting to new tools, and finally to where we stand today with a more robust and efficient testing framework.

Saleor recently migrated our end-to-end test suite from Cypress to Playwright. In this article we share our journey, the challenges we encountered, and how the transition unfolded.

The decision to make the switch from one tool to another is never taken lightly. It needs to be carefully weighed up as it can impact the entire workflow and stability of our projects.

How it started

Let’s take a trip back to 2020. It’s the beginning of the pandemic and I’m diving into adding the first storefront end-to-end tests written in Cypress. Back then, we didn't have a CI/CD setup - GitHub history shows that our deployment workflow was established in 2021.

Why we decided to use Cypress in 2020

Well, one thing was certain, we needed automation. There weren’t many tools to choose between on the market, so the decision was straightforward. Selenium’s ongoing problems with drivers and debugging made it a no-go for us. Cypress was more user-friendly and was on top at the time - the future seemed bright for end-to-end automation.

As the years passed, our QA team grew and we had more and more tests. Around 2022 we decided to upgrade to the paid version of Cypress to use the dashboard (now Cloud). It was a significant improvement for us, finally we could run tests in parallel!

Test results were visible, we did some automation with Github. We are still using bots that tell us if the release has some failed tests or not.

Playwright was on the horizon

As with every successful tech company, we keep an eye on ‘new-tech’ news. Playwright was gaining some attention and I became intrigued by this new tool. I was also a bit hesitant - with PlayWright being a new tool, the community was only just starting to grow. In comparison, Cypress was more mature and well-documented, the community was more established, and we had experience with it.

Even though we had encountered slowdowns and issues with Cypress, I was wary of making a rushed decision to switch test frameworks. Also, who would find the time to rewrite all our Cypress tests to Playwright?!

Day by day, article by article, it became clear that we would eventually need to make the move. We were running tests so frequently and across so many versions that the cost of Cypress Cloud was becoming prohibitive. We tasked one of our QA team members to experiment with PW in their project. Tests ran faster, and a lot of the issues we experienced with Cypress seemed to vanish.

Cypress vs Playwright

Let’s take a look at a comparison between the two:

Test structures

Let’s compare the test structures in Playwright and Cypress.

At first, you can notice that PW uses test to define the test case and expect from its testing library for assertions.

Cypress uses it to define the test case and Chai (expect) for assertions.

As you can see, the test code looks different. Playwright uses a way of writing code called async/await, which is built into JavaScript. Cypress, on the other hand, has its own method for dealing with tasks that happen at different times, so you don't always need async/await. Assertions with PW uses Jest’s library, whereas Cypress uses its built-in assertion library, powered by Chai.

Additionally, Playwright features a built-in auto-wait strategy. If the anticipated checks fail to materialize within the designated timeout, the action is flagged with a TimeoutError, mitigating flakiness. In contrast, Cypress is engineered to wait automatically for elements to be present in the Document Object Model (DOM) prior to executing actions such as clicking or form submission. However, this can extend the test duration.

One of the advantages of PW is iFrame support, Cypress has problems with that which leads to having to do workarounds.

These examples give you an idea of how Cypress and Playwright differ, but there's much more to explore.

Decision and struggling

So, in the middle of 2023, I began discussing the transition to PW with the QA team. We prioritized rewriting the most critical paths first and then tackled less critical but still important tests. During this refactor, we also cleaned up our tests, reducing the number of end-to-end tests in favor of more integration tests.

As of 2024, we're still grappling with some configuration and workflow issues.

Our first challenge was adding new workflows for running Playwright on the main branch, on pull requests and keeping workflows for Cypress since we still support older versions of Saleor. We want to keep posting test results on Slack and receive concise information about whether tests pass or fail on the release pull request.

Currently each pull request trigger the PlayWright tests in parallel. This ensure us that only the most recent changes are tested.

We also created a workflow for a nightly tests which are running three times per week.

Last but no least, we have possibility of running tests via Github Actions. It is possible to run it on selected branch or tag.

We needed to add a Slack notification. We wanted to receive concise information about whether tests pass or fail on the release pull request.

Therefore, when a release pull request is ready, tests are triggered automatically, and the results are sent to TestMo (the tool for test cases and test results that we are using). In case some tests fail, we receive a Slack notification and comments on the release pull request. If all tests pass, then auto-merge should occur.

There is still some work to be done, and we still support Cypress tests for older versions of Saleor.

Summarizing

Saleor's journey from Cypress to Playwright highlights the evolution of our automated testing framework. Starting with Cypress in 2020, we upgraded to the paid version to support parallel testing. However, rising costs and performance issues led us to explore Playwright, which offered faster execution, broader browser support, and finer control over browser interactions.

Despite initial hesitations, we began switching to Playwright in mid-2023. We faced configuration and workflow challenges but implemented new workflows for parallel testing, nightly tests, and GitHub Actions integration. Especially, developers found it easier to dive into Playwright tests compared to Cypress. While initially challenging for our QA team, our tests are now faster, more stable, and better organized.

As of 2024, we still support Cypress for older versions but continue to refine our Playwright-based testing framework for greater efficiency and stability in our CI/CD pipeline. I'm proud of our team for making the switch!

DEV Community: Saleor Commerce

Building Reliable Software: The Trap of Convenience

Productivity Through Convenience

A Litany of Failure Modes

Failing Fast

Resisting Abuse

Final Thoughts

Building Reliable Software: Planning for Things to Break

Embracing the Failure

The CAP Theorem

It's Systems All the Way Down

Better Fault Tolerance

Self-Healing Systems

Remain Vigilant

Cleaning up large frontend codebase

Diagnosis

Invalid module refactor

Stale feature flags

Unused queries

Techniques

Static analysis

Tests

Dropping default export and barrel files

Small PRs

AI codemods instead of direct changes

Keep flags clean

Upgrading React 17 to 18 in a large codebase using AI

Scope of Changes

Trying an Agent

Precise Prompt

Focus on Type-Checked Files

Working in Batches

Saving State

Picking up by another agent

Live Editing vs Codegen

Branded Types in TypeScript: techniques

1. Using a Type Wrapper

2. Using JavaScript Classes / Objects

3. Using Zod’s brand() Method

Summary

TypeScript type inference - the dark side

Code first or design first

Interface vs inference

Impact on the maintenance

Summary

Error modelling

Intro

Role of errors

Abstraction is the problem

Errors chaining

Summary

Dynamic Configuration for MCP Servers Using Environment Variables

Problem

Solution

Using the Script in MCP Clients

Summary

UUID migration in Django with PostgreSQL

What is UUID?

Why it’s so useful?

How to migrate my data from ID to UUID while ensuring both the wolves are satisfied and the sheep remain unharmed

Happy scenario

How the relations are defined in your database?

So what is the problem?

The solution in a nutshell

Preparation

Handling database relations

Few tips at the beginning:

Before UUID migration

Set UUID column as the primary key

After UUID migration

At the end

Conclusion

DynamoDB access modeling for multi-tenant services

Problem

Modelling Approach

Access Patterns

Data Structure

DynamoDB Table Design

Primary Key (PK)

Sort Key (SK)

Dropping `default export` and barrel files

3. Using Zod’s `brand()` Method

Before `UUID` migration

Set `UUID` column as the primary key

After `UUID` migration