Booknotes: Writing portable code

A Saturday in January 2025

Booknotes 1.

I’m writing a guide to building your own database server. Here’s what I’ve been doing:

Progress - My aim is to get the first part of the guide in a releasable state by April. I’ve written 6 of the 10ish chapters so far and have a rough outline for the rest.
Portable code - The book comes with tests to help guide your implementation. So that the tests are as easy to run as possible for most people I’ve chosen to write the test runner in python. Python is widely used, is included with many Linux distributions by default and has an installer for OSX. By having zero dependencies and by targeting a broad range of python 3 versions I hope to reduce any faff that people will have to go through to run the tests. I considered writing the tests in JavaScript/TypeScript and using Bun to make a distributable executable but think I prefer to keep the test runner code more visible and easily editable by people. I’ve spent some time over the last weeks adding to the test runner so that it formats failures better and can run individual test cases.
Diagrams - I’ve been deciding what tool to draw the diagrams for the guide in. I’d like the tool to be able to export SVGs with a transparent background so that the diagrams look good at different sizes and can work on light and dark backgrounds. The top two contenders are tldraw and FigJam. Both make it easy to create diagrams with arrows that snap to boxes. I like the ‘sketchy’ look that diagrams from tldraw have but it’s very restrictive on customization such as with colours and font sizes. FigJam is a little more customizable, but has to be pasted into Figma before it can be exported as an SVG. Here’s an example that shows how to structure a parser that can work with statements such as SELECT 1, TRUE, FALSE; made in tldraw and FigJam. Let me know if you prefer the look of one over the other or have a suggestion for another tool I should try.
Typing - The last chapter I wrote was about catching errors and typing statements. In each chapter I call out any interesting differences and implementation choices in different database engines. I learned that SQLite has chosen to be much more flexible when it comes to types compared to other databases, for example "23dogs" / "5" will happily evaluate to 4. SQLite is the JavaScript of databases - it’s everywhere and will do whatever it can to coerce types rather than give an error.

⸺