DEV Community: Mark Saward

Cloud SQL is not great

Mark Saward — Tue, 03 May 2022 13:48:07 +0000

I've finally finished migrating our 9.6 PostgreSQL database from Google Cloud SQL to 14 running on a VM under our control. This may not be its final home, but at least it has been liberated from the tyranny of the managed database.

I have less experience with AWS, and no experience with any other managed database solutions. However, based on my experience of Cloud SQL, I think that self managing a database like PostgreSQL will be my default, with managed databases being the exception rather than the rule.

There are some criticisms I have that are specific to GCP (Google Cloud Platform), and some that apply to any managed solution. Without further ado, here are the things I have disliked like about managed solutions, and Google Cloud SQL in particular.

Things to dislike

Accidental deletion

A major point of having a backup is that it enables you to recover in the case of a disaster. One of the most far reaching/thorough disaster is your database is deleted, perhaps by accident or maliciously.

No problem, you might assume. A managed database solution provides backups, so just restore from backups -- you did enable backups, right?

Well, as it turns out, Cloud SQL deletes backups along with the instance. That is insane behaviour, and the bold red warning in the documentation does not do it justice:

Warning: All data on an instance, including backups, is permanently lost when that instance is deleted. To preserve your data, export it to Cloud Storage before you delete it. The Cloud SQL Admin role includes the permission to delete the instance. To prevent accidental deletion, grant this role only as needed.

And what if your database is actually accidentally deleted? You scramble against the clock and hope you can find it hidden away.

It is possible to do exports as described above. I'd strongly recommend automating such an export if you can, to ensure you have a dump in case of a disaster of this magnitude. However, these are full dumps of the database, and so hard to do regularly enought to reduce the amount of data lost.

This wouldn't be so bad if you could better manage backups...

Backup options

Backups are limited. These days, pgbackrest is the go-to backup solution for PostgreSQL, and having used it I am very impressed so far. It provides full backups, differential, and incremental, as well as archiving of WAL segments for point in time recovery. It allows great flexibility in schedules and destinations for backups, how long to keep backups for, how many full backups. For example, you can have backups made to a local disk, and other backups to an external S3-compatible bucket, each with their own settings and schedules (e.g., scheduled via cron).

In Cloud SQL, you can enable point in time recovery, you can run ad-hoc backups, and you can schedule them with limited scheduling options. But if you ever delete your instance, those are all gone. Your scheduled backups and point in time recovery options are, it seems, linked to that instance that are promised to be wiped if you delete it.

If you want to have some external backups, well, as I described above, you're looking at a full dump each time

Want to run backups to an external location, like your own server or backups? Then you're back to the export option, where it does a full dump of the database each time. It's not great, but it's better than having all your eggs in a basket that can get deleted all at once.

There might be options around replicating to a database under your control, so that you can run better backups on that replica. I had troubles, which I describe in part below. Perhaps the story is better with more recent versions of Cloud SQL, but I won't be testing -- logical replication wasn't built into PostgreSQL until version 10, so I was relying on Google's support for pglogical.

If you could pull off a logical replica to a database you manage yourself, then you could arrange solid backups from that replica. However, if you get to the point where you're using replicas in order to better manage backups, then it might be worth considering where the value of a managed solution is for you.

Upgrades

We've been stuck on 9.6 for a while, watching major releases tick by. Our database wasn't particularly large, maybe 200GB at peak, which is by no means a large database compared to the scale that some operate at. However, even at that size, it's still problematic to do upgrades.

The problem is that the managed database offers no way to perform upgrades. The officially recommended method:

To upgrade to a later version, consider using the Database Migration Service or exporting and then importing your database to a new Cloud SQL instance.

The Database Migration Service worked, with some effort, when I tried to use it. It used logical rather than physical replication, allowing us to have the replica on a newer version -- specifically, the pglogical extension because we were on 9.6. The replica was set up and streaming changes, and running on the latest version, working well enough. However, I couldn't cut over immediately, and waiting a few days seemed to be a foolish decision. The sync stopped working, and I could not find any error messages or information to debug why. Re-creating the migration from scratch did not work.

Contacting support was of no help. When attempting to purchase support, the support button wouldn't work. I then attempted to contact support to get support in helping me to purchase support, whereupon I was unhelpfully directed back to the page that wasn't working.

That put us back to option 2: export then import database. The problem with this is that it involves significant downtime. The time to export the database, and then import, took hours.

Needless to say, we've been through that process, after significantly cutting down the database in size, to reduce the downtime. It was the perfect opportunity to move off Cloud SQL permanently, so that we won't be at the mercy of inscrutable cloud tools and restricted backup options.

Extensions

Now we move to some of the other reasons why I lean away from managed databases overall. The first (but not most important) on the list is extensions. As part of my recent efforts to master my craft, including databases, I've become interested in the possibilities of extending the database. That includes using third party extensions, as well as developing my own. This is a theoretical criticism for now, as I have not yet had a need for this, but I can definitely foresee it as a possibility.

Managed databases do support a collection of extensions out of the box, but you cannot use any that are not on their list, including your own.

Tuning settings

Since the database is not controlled by you, you have limited options for tuning its settings. By managing the database yourself, you have the option to change whichever settings you wish to match your operational needs.

Newer versions

If you are fortunate enough that your cloud provider makes upgrades easier, you are still limited to upgrading to only versions that they support. When you manage the database yourself, upgrades are in your control, and you can jump to a new version early if you need.

Super user access

With Cloud SQL, you do not have access to the super user, and so your ability to manage the database is limited. With a self-managed database, you have full control.

Downsides to self management

Of course, by running a self managed database, there are absolutely downsides. If you want a new database, then spinning it up with a manged solution is very quick and easy to do. Managing it yourself, you'll have to do things like:

Set up the VM and install the software
Run OS updates
Set up and test backups
Set up replication yourself
Clones for testing may be more difficult to make
PostgreSQL out of the box settings are not great, and you'll need to tune these yourself

There are absolutely downsides to self management, but for projects of a certain significance, I believe the benefits become worth the effort. If for no other reason, when considering Cloud SQL, better control over backups, and easier upgrades, are hard to pass up.

Generic integer functions in Go and Rust

Mark Saward — Sun, 01 May 2022 08:14:22 +0000

Suppose we want to create a validation function for a struct, to ensure that a number is between two values (for example, for validating a HTML form's submission). However, we'd like to make this function generic over a variety of integer values. With Go's recent introduction of generics, this is very straight forward to implement. We simply create the interface that specifies which types will be permitted, and then make a function that is generic over those types:

package main

import "fmt"

type magnitudal interface {
    int16 | int32 | int64
}

func isBetween[T magnitudal](val T, min T, max T) bool {
    return val >= min && val <= max
}

func main() {
    var input int16 = 5
    fmt.Printf("input %d is between 1 and 10: %t\n", input, isBetween(input, 1, 10))
}

Fortunately (?), Go allows us to use >= and <= in this function, because it's available for every type specified in the magnitudal interface. The same is not true if a field happens to be shared by all types in the interface -- we can't access that field just because all types have a field of the same type and name.

For Rust, let's do it the hard way first, so we can understand better how the easy way works. Let's create a trait called Magnitudal that plays a similar role to the Go magnitudal interface. We listed the types in our 'magnitudal' interface, and because we can use => and <= on all those types, isBetween can be called for a variety of integer types. For Rust, we create a Magnitudal trait and implement it for every type we want to allow into our function. Here is an example:

pub trait Magnitudal {
    fn between(self, a: Self, b: Self) -> bool;
}

impl Magnitudal for i16 {
    fn between(self, a: Self, b: Self) -> bool {
        self >= a && self <= b
    }
}

fn main() {
    let input: i16 = 5;
    println!(
        "input {:?} is between 1 and 10: {:?}\n",
        input,
        input.between(1, 10)
    );
}

This gives us the output:

% cargo run
[...]
input 5 is between 1 and 10: true

Suppose now we wanted to allow this function to be used for more types than just i16. Much like the 'magnitudal' interface in the Go code had to list all the types that are permitted, we need to implement the 'Magnitudal' trait for every type that we want to permit. We could do this by hand. For example, adding i32 and i64:

impl Magnitudal for i32 {
    fn between(self, a: Self, b: Self) -> bool {
        self >= a && self <= b
    }
}

impl Magnitudal for i64 {
    fn between(self, a: Self, b: Self) -> bool {
        self >= a && self <= b
    }
}

However, this could get quite cumbersome and repetitious as we add more types. However, we can mitigate some of this repetitiveness through macros. I adore the idea of macros in Rust, but I've only just started experimenting with them. Even with the introduction of Go's generics, I still find myself reaching for generated code for some things that can't yet be done easily with code alone. For example, as mentioned above, in Go 1.18 you can't call a field that happens to be shared by all types permitted by a type interface. This may arrive in later versions, but isn't possible to do yet. Having something like macros processed by the compiler, to auto generate code, is a great boon.

Let's create a macro that will implement Magnitudal for any type we list, so that adding a new type is just a matter of adding it to the macro call (or calling the macro again):

macro_rules! impl_magnitudal {
    (for $($t:ty),+) => {
        $(impl Magnitudal for $t {
            fn between(self, a: Self, b: Self) -> bool {
                self >= a && self <= b
            }
        })*
    }
}

impl_magnitudal!(for i16, i32, i64);

Without going into details on how this macro works, we can call impl_magnitudal!(for a, b, ...) and list all the types, and it will generate the code automatically for each of those types as defined by the macro. Once the macro is created, adding the implementation for a new type is as easy as passing those types as arguments to the macro. The code produced is the same as the hand-written implementation for each type. Still not as simple as the Go setup, since we still need to implement a function called between, while the Go code was able to use the >= and <= operators directly to create a generic function rather than a function implemented on each type.

We can improve on this. Rust allows us to implement traits on types so that we can make use of operators like + - < > with that type. The operations we need, <= and >=, are implemented via the PartialOrd trait, and have already been implemented for all the integer types we are interested in. For example, see the docs for the i32 implementation of PartialOrd. That means that we can create our between function not as something implemented by a type, but rather as a standalone function, restricting it to all and only types that allow us to use >= and <=!

So let's forget using our own trait and its accompanying macro, and instead create a generic function that allows any PartialOrd types as an input. Here is the entire program:

fn between<N: PartialOrd>(val: N, min: N, max: N) -> bool {
    val >= min && val <= max
}

fn main() {
    let input: i16 = 5;
    println!(
        "input {:?} is between 1 and 10: {:?}\n",
        input,
        between(input, 1, 10)
    );
}

Rather than implmenting our own type, we declare a function generic over any type that implements PartialOrd, and accepts that same type as an input, min, and max value. This is actually more concise than the Go version, but this is because the hard work of implementing all the myriad traits for the myriad types has been done in the Rust standard library for us, and the same could be done for Go. With new types of our own invention, we'd need to go through the process of implementing the trait for all the types we wanted.

If the numeric traits implemented in the standard library are not enough, there is a num package that goes further. For example, if we wanted to only allow integer types for between, we can use the num package's Integer trait to do exactly that:

use num::Integer;

fn between<N: Integer>(val: N, min: N, max: N) -> bool {
    val >= min && val <= max
}

fn main() {
    let input: i16 = 5;
    println!(
        "input {:?} is between 1 and 10: {:?}\n",
        input,
        between(input, 1, 10)
    );
}

And make sure to include the new dependency in your Cargo.toml file:

[dependencies]
num = "0.4"

The num package makes use of macros similar to how we did earlier, to reduce the repetitive implementation of the trait for all the desired types. The Integer trait itself includes PartialOrd, so when restricting types to Integer, we can still call on the <= and >= operators.

Go has 'duck typing', where something fulfills an interface just in case it implements all methods described in the interface. Rust, on the other hand, requires explicitly declaring an implementation of a trait. It's not enough that the type has the method, the method has to be specified as implementing that method for the trait. Ultimately, I lean towards preferring Rust's approach here, because it avoids situations where a type just happens to fulfill an interface by chance with methods that are actually intended to play a completely unrelated role. This gives us more confidence that a type implementing a trait does so because it's intended to be used for that trait.

In Go, we can't implement operators for our own types. The Rust solution here can be expanded to accept any new numeric types we might create, but with Go we can't use the general implementation above on custom types. We would need to resort to using reflection, or implementing methods for each type and then calling those methods instead of using >= and <= directly. I've only started playing with Go generics recently, but as mentioned earlier I'm finding that they are limited in some ways that I would like to use them. Hopefully they improve in their capabilities over time to more gradually eliminate my need for generating code.

Go footguns: Go Defer and Rust Drop

Mark Saward — Fri, 26 Nov 2021 06:30:20 +0000

My extremely slow journey to learn Rust continues, delayed by other projects. My attention in 2021 has been primarily on Go and PostgreSQL. I'm coming to appreciate and respect the database overall (and PostgreSQL specifically) a lot more, and wrote up some of my thoughts in Thick Databases.

One thing that has me very interested in Rust is the tools it gives me to write code that works in exactly the way I expect, to enforce that behaviour on other developers, and help me to avoid situations where I (or others on my team) forget to do something important, such as initialising a value, closing a file, or an http request, or a database transaction.

Forgetting to close things off in Go is one of those places that can potentially come back to bite you in hard to find ways. For a database connection, for example, it's very important that you remember to always rollback or commit a transaction. If you forget to do this, you can run into situations where you've starved yourself of connections, and any further requests fail -- your service grinds to a halt.

There's a handful of ways to do this. The most basic and straightforward method is to call rollback or commit every time you return:

func someWork() error {
    tx, err := db.Begin()

    err := foo(tx)

    if err != nil {
        tx.Rollback()
        return err
    }

    err = bar(tx)

    if err != nil {
        tx.Rollback()
        return err
    }

    return tx.Commit()
}

This runs the risk that we forget to add tx.Rollback() upon returning some error -- something that can happen very easily, especially as we refactor code and move code here from elsewhere that had an error check that didn't previously need to be accompanied with a rollback.

A safer option is to defer the call to rollback, to ensure that it's always called, since it doesn't matter if a deferred rollback call follows a successful commit:

func someWork() error {
    tx, err := db.Begin()
    defer tx.Rollback()

    err := foo(tx)

    if err != nil {
        return err
    }

    err = bar(tx)

    if err != nil {
        return err
    }

    return tx.Commit()
}

This is better, because we now only need to remember to call rollback once, and make sure we commit when everything is in order. However, it's still not perfect, and this is where another footgun can appear. Suppose that we have a loop, and we are creating new transactions on each iteration of the loop.

Here's a loop, where we start a new transaction each time, but for whatever reason we do not want to commit the work we've done (or alternatively, we do want to commit the work from some iterations of the loop but not all -- e.g., with an error, we continue to the next iteration without committing):

func deferInLoop() {
    for i := 0; i < loops; i++ {
        var result bool
        tx, err := db.Begin()
        defer tx.Rollback()

        if err != nil {
            fmt.Println(err.Error())
            continue
        }
        err = tx.QueryRow("SELECT true").Scan(&result)
        if err != nil {
            fmt.Println(err.Error())
            continue
        }
        log.Printf("loop count %d.  Result: %t", i, result)
    }
}

If we try and execute this, we'll find our connections run out and the service panics:

2021/11/10 00:36:08 loop count 92.  Result: true
2021/11/10 00:36:08 loop count 93.  Result: true
2021/11/10 00:36:08 loop count 94.  Result: true
2021/11/10 00:36:08 loop count 95.  Result: true
2021/11/10 00:36:08 loop count 96.  Result: true
2021/11/10 00:36:08 loop count 97.  Result: true
2021/11/10 00:36:08 loop count 98.  Result: true
2021/11/10 00:36:08 loop count 99.  Result: true
pq: sorry, too many clients already
pq: sorry, too many clients already
pq: sorry, too many clients already
pq: sorry, too many clients already
pq: sorry, too many clients already
...
pq: sorry, too many clients already
pq: sorry, too many clients already
panic: runtime error: invalid memory address or nil pointer dereference
panic: runtime error: invalid memory address or nil pointer dereference
panic: runtime error: invalid memory address or nil pointer dereference
panic: runtime error: invalid memory address or nil pointer dereference
panic: runtime error: invalid memory address or nil pointer dereference
...
[signal SIGSEGV: segmentation violation code=0x1 addr=0x40 pc=0x10c3e62]

goroutine 1 [running]:
database/sql.(*Tx).rollback(0xc000028068, 0x0)
        /usr/local/go/src/database/sql/sql.go:2263 +0x22
database/sql.(*Tx).Rollback(0x0)
        /usr/local/go/src/database/sql/sql.go:2295 +0x1b
panic({0x120c840, 0x13e6ec0})

We can find ourselves in a similar situation where we have long-lived functions that begin a transaction, but don't return until much later -- long enough that concurrent calls of that function add up to eventually starving ourselves again, because the deferred rollback hasn't yet been called (Rust doesn't help here either if the transaction variable won't leave scope until the end of the function).

Recapping our earlier lesson, we needed to remember to rollback every time we return. To avoid having to call rollback every time there's an error, we deferred the rollback so that it runs every time the function returns. However, there are some circumstances in which the defer won't be called early enough to let us avoid starving ourselves of connections. What can we do? We can either revert back in these situations to calling rollback each time we return/continue:

func rollbackInLoop() {
    for i := 0; i < loops; i++ {
        var result bool
        tx, err := db.Begin()

        if err != nil {
            fmt.Println(err.Error())
            tx.Rollback()
            continue
        }
        err = tx.QueryRow("SELECT true").Scan(&result)
        if err != nil {
            fmt.Println(err.Error())
            tx.Rollback()
            continue
        }
        log.Printf("loop count %d.  Result: %t", i, result)
        tx.Rollback()
    }
}

Or, we can perform the work for that transaction in a separate function that will return for every iteration of the loop. The defer therefore gets called before the next iteration of the loop begins a transaction:

func deferInFunc() {
    for i := 0; i < loops; i++ {
        err := deferInFuncFetch(db, i)
        if err != nil {
            fmt.Println(err.Error())
            continue
        }
    }
}

func deferInFuncFetch(db *sql.DB, i int) error {
    var result bool
    tx, err := db.Begin()
    defer tx.Rollback()

    if err != nil {
        return err
    }
    err = tx.QueryRow("SELECT true").Scan(&result)
    if err != nil {
        return err
    }
    log.Printf("loop count %d", i)
    err = tx.Commit()

    if err != nil {
        return err
    }
    return nil
}

These solutions work, but they're things we have to remember to be careful about -- it's easy for us to forget these things, as there's nothing that warns us that we've done something that cause problems until the point where we find our production service failing in strange and unpredicable ways. It would be fantastic if we could write our Go code in such a way that you can't forget to do these things. For example, by having rollback be called automatically in good time by default, or by the compiler throwing an error if we missed a case.

This led me to wonder how this would be handled in rust.

Rust drop

Rust provides the Drop trait that you can implement on structs. The drop function will get called much like a destructor in C++, so that you can clean things up. This happens when the owner goes away, so it gives us the chance to perform actions earlier than just the point where the function returns. E.g., drop might be called at the end of every iteration of the loop if the variable falls out of scope then.

This gives a great place for us to ensure that rollback is called if we forget. As a result, we can guarantee, in a way that prevents us from forgetting, that a transaction will eventually rollback. Looking at the postgres library's transaction method, we learn:

The transaction will rollback by default - use the commit method to commit it.

Investigating a little further, we can see that the Transaction struct implements the Drop trait. Specifically:

impl<'a> Drop for Transaction<'a> {
    fn drop(&mut self) {
        if let Some(transaction) = self.transaction.take() {
            let _ = self.connection.block_on(transaction.rollback());
        }
    }
}

Therefore, we don't even need to implement anything ourselves to ensure that a rollback is called -- no need to call rollback, and no need to schedule a deferred rollback. When using this library, if we neglect to commit the transaction, then it will rollback, and in good time. Suppose then we implement a similar loop function to the one we had in Go:

fn loop_() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect("host=localhost user=postgres", NoTls)?;

    for i in 0..200 {
        let mut transaction = client.transaction()?;

        let row = transaction.query_one("SELECT true", &[])?;
        let result: bool = row.get(0);

        println!("loop count {} result: {}", i, result);
    }

    Ok(())
}

This works exactly as we'd hope -- 200 iterations, and no issues. This is because each time the loop iteration ends, the transaction struct gets dropped, and rollback is called, all before the next iteration begins.

Looking at another Rust library, sqlx, we find the same approach with drop is used:

A transaction should end with a call to commit or rollback. If neither are called before the transaction goes out-of-scope, rollback is called. In other words, rollback is called on drop if the transaction is still in-progress.

Thus helping to ensure that connections don't remain around forever when we neglect to rollback. The useful thing about drop is that we don't have to rely on the function returning, or on running the transaction in a separate function. It's enough that a block ends, and the struct is due to be freed, for the default rollback to be called.

When I first started learning Go, I had some disappointment with the tools it gave me to ensure that code could be used exactly and only as intended. A standout example of this is the lack of a way to force users of a library to only get new instances of a struct via a function whose job is to ensure the struct is initialised in the ways it needs to be (e.g., initialising an internal map). Eventually I stopped wishing for those things, and just got on with the work of building things. However, now that I'm exploring Rust, I'm thinking again about the things that I had once hoped to be able to do in Go.

Missing a rollback is a footgun that I've fired off before, and I'll bet plenty of others have as well. I'm pleased to see that Rust gives the tools to prevent these kinds of issues.

If you'd like to explore more, I've uploaded the code I used to play around with this to github.com/saward/footgun-defer.

Thick Databases

Mark Saward — Fri, 03 Sep 2021 06:00:41 +0000

It doesn't matter how much you learn, there's still a tremendous amount you don't know, significant blindspots. I've been coding on and off since my high school days some 20+ years ago. After working for a while, I took time off to pursue a PhD in Philosophy, and now I'm back to programming full time. All of this is to highlight that I've been programming for a bit over two decades, though not full time for all of that period. I've learned a lot, but I still marvel at how much I just don't know.

In this instance, I'm now exploring the idea that I've been giving databases too little credit, at least for the kinds of applications we write at Episub -- applications that see daily full-time use by employees, but aren't companies that are going to face the kinds of scaling challenges that come from thousands or millions of daily active users. Perhaps the ideas here are good even for very high traffic applications, but I am not considering this from that angle. Up until now, I've held the view that you should keep business logic out of the database. I didn't realise I held this view overtly, but it came out in other ways. Notably, I'd seen solutions like the original Prisma (which I'm still not inclined towards using, but for other reasons), Hasura, and PostGraphile -- automatic API's built on top of databases. Automatic anything sounds great, but I had concerns -- though when I say concerns, what I really thought was that these were deal-breakers that make such automatic API's useless for anything other than toy projects. Here's some of the "deal-breaking" concerns I had.

Objections

Objection 1: Database and API model often differ

For the projects I work on, very often the way we structure the database is not the way we want to present it to the end user. This can happen for a variety of reasons. Sometimes, to have a nicely normalised database, we model the data in a way that doesn't make sense for the end user.

Let's use an example for our discussion. Suppose that we have a 'person' table with a separate 'address' table. We did it this way because we're going to re-use the concept of an address in other places -- attached to a 'job' table, or an 'organisation' table, etc. We don't anticipate that a person will have more than one address (e.g., no separate shipping and billing addresses), but maybe one day we'll need that. So, to simplify the API for our users, we decide we want a 'person' endpoint that shows the person details combined with their address:

{
    person_id
    name
    address_1
    address_2
    state
...
}

So here's the problem as I saw it for an automatic API: it's going to give me an API structure that requires the consumer to fetch two objects. Maybe the API is smart enough to still make one call to the database, but either way you're exposing the underlying structure of the database in ways that don't make sense for this API. E.g., you have a result like:

{
    person_id,
    name,
    address {
        address_1
        address_2
        state
        ...
    }
}

Or do two separate calls fetching first the person...

{
    person_id,
    name,
    address_id,
}

and then their linked address:

{
    address_id
    address_1
    address_2
    state
    ...
}

We wanted to use the flattened result in our API, but because it's presenting the data in the same way as it's modelled in the database, we are limited. How often does a well designed API match the structure of the database? In my experience, despite significant overlap between the API model and the database model, they frequently diverge. I don't want my API to be locked into matching my database model.

Objection 2: Requires business logic in the database

A lesson many of us have been taught is that we should separate the business logic and the data. Using an automatic API requires us to put business logic in the database. Suppose that we want to allow orders to be cancelled, but only if none of the items have yet shipped, and if cancelled, create a notification entry in another table to alert staff to the cancellation.

We have a few options.

Option one: Since the API doesn't automatically implement such rules, we tell consumers of the API to check for lines that have shipped, and don't cancel if so. If you do cancel, make sure you call another endpoint to create the notification entry. Obviously a terrible implementation when we require the consumers to follow our business rules.

Option 2: Create one or more triggers on the table that prohibit updating the 'cancelled' field (or a trigger on delete) when a shipped item exists. The same trigger, or another, creates an entry in the notification table.

That works, but it's still not a neat interface for the user, since they're just doing a CRUD style update to change the 'cancelled' field. Since it's just toggling a field (or deleting a record), it's not as obvious to the API consumer that it has side effects.

Option 3: Create a function called 'cancel_order' that performs all the steps required, exposed via the automatically generated API. We prevent our users from being able to update the 'cancelled' field directly.

That works, but we've now very clearly put our business logic into the database, something (so I thought before) to be avoided.

Objection 3: Some API tasks won't be possible in a database

There are things we might want an API to do that a database cannot handle. Here are a couple of examples:

Endpoints that don't involve working with our data at all. E.g., returning the latest weather, or stock prices, or whatever else, from independent API's. We simply want to unpack the request, send our own request off to the appropriate service (whether those be our own or third party), and then return the reply.
Endpoints that trigger tasks (such as sending emails) or slow-to-calculate tasks (such as building a PDF). The database doesn't know how to send an email or create a PDF, and moreover, tasks like these can sometimes be slow -- even if we could do them in the database, we wouldn't want to slow it down from doing the important work that only it can do.

An automated API is bound to turn otherwise straightforward features into unwieldy messes.

Where to next

If my objections were on point, then automatic API solutions should be unusable or burdensome nightmares for any serious project. Clearly, however, people do use them, and such popularity is evidence that my objections must not be so serious as I suppose. Having spent some time now looking into them, that has turned out right -- in which circumstances a thick database is the best option I'm still undecided, but I'm certainly more open to leaning more heavily on the database. The catalyst for my change in attitude towards the maxim "no business logic in the database" came from looking at PostgREST and asking myself, "if it's such a bad idea to do things this way, what do people find appealing about solutions like PostgREST?" As I often do, I like to read hackernews posts on technology to see what people with (often deep) experience have to say. On there, I saw many of the same concerns I held myself repeated by others, as well as responses I hadn't previously considered.

I'm not a fan of ORM's, and have certainly read the often recmomended Object-Relational Mapping is the Vietnam of Computer Science. It's really great to have some helpers for simple things, but anything complex and I just want to write the SQL that does, and returns, exactly what I want. Tied to this is the fact that I'm happy to give up on the ability to easily swap my database (say, PostgreSQL) for another (say, MySQL/MariaDB). I don't want an ORM to abstract away the database. Rather, I want to enjoy the advanced features it brings, particularly with a database like PostgreSQL. Given that I've already given up on the idea of treating my database as a commodity, I'm more open to diving in and exploring what it can do, and that includes having the database be 'thick', implementing some key parts of business logic in there instead of in code, on the understanding that I won't be replacing the database. Sure, if I ever found myself with a project that had massive scaling requirements, I might split parts of it off into a database more suited for that role. But for the projects I work on, and any that I can foresee, I'm happy to lock the core into something like PostgreSQL.

And so here I am, exploring PostgREST as a way to generate an API off the back of my database. Here's a few thoughts on thick databases. I'll start by explaining how each of the objections I had above no longer seem so serious, followed by some further remarks on other aspects of this approach.

Objections answered

Resolution 1: Database and API model often differ

It is true that database and API models often differ. In my experience it's very rare to have a situation where they do not differ in at least some places. Of course, there is often significant overlap, but very rarely is that overlap complete. An automated API therefore should support API models that differ from the shape that the underlying data is stored in.

Speaking with respect to PostgreSQL+PostgREST, the solution is to have a separate schema. Inside that schema, you configure all the views to look exactly like you want them to appear to a consumer of the API. For example, we could create a 'persons' view that combines the 'person' record with its associated 'address' record. Then, anyone who pulls data from our API will get the person with their address details just as we wanted in the original example:

{
    person_id
    name
    address_1
    address_2
    state
...
}

We can then create triggers on that view to define what is to be done for insert and update actions. Again, these triggers can enforce business rules that go beyond just "insert and update details in the appropriate 'person' and 'address' tables". This could be things such as adding a new entry in some 'person_entity' joining table, or creating an alert, or triggering an email (see below for a discussion on handling emails).

We might also restrict access for fields like 'cancelled' on an order, or prohibit deleting an order. Through an api schema, we can prevent the 'cancelled' field from being updated directly through the view. Instead, we create a 'cancel_order' function that performs this action. That function implements the logic like ensuring that there are no line items that have shipped, for example.

With this approach, the API schema can differ as dramatically as we like from the original data. We are free to combine underlying tables into one view, or split underlying tables into multiple views, or mix and match them as we please.

Of course, this is not so automatic. We probably shouldn't just point an automated API like PostgREST to our underlying database and restrict things. Instead, we control all access through the 'api' schema, so that we can define the shape of the API and more carefully control the permissions.

Resolution 2: Requires business logic in the database

Should we really keep business logic out of the database? Let's consider another claim, one that might at first glance look the same:

Data and business logic should be kept separate

Suppose that this is true (and we'll discuss this a bit more soon). Does putting business logic in the database entail that we are mixing data and business logic? The answer is 'no'. Suppose we keep data in one schema, and the API's structure in another, as proposed above. We have our application schema which stores all the data and, allegedly, no business logic. We have our api schema which does not hold any data, but contains our business logic. All access to the underlying application schema is through the api schema, so that business logic can be enforced at the database level, without existing at the data level.

In this way, our data and business logic are separate -- they're both in the database, but they are not mixed together. We have followed the rule above, and it looks to me like it's not so bad to keep business logic in the database, particularly when we can still take care to keep business logic out of the data.

But let's ask the next question -- should we keep business logic out of the data? Here the answer is, I think, a murkier 'no', for the simple reason that most of us that work with databases already put business logic in the database and consider it best practice.

For example, consider our 'person' table with its name column. How long should a name be? Many of us will enforce a maximum length for fields like this in the database, but this is clearly a business logic decision. Can a name be null? If we know the rule in this case, that a name should always be provided, we can enforce this in the database by requiring it to be not null, or even having a check constraint to ensure that it's at least one character long. What about usernames -- do we allow upper and lower case characters to be different usernames? That is business logic. Does every person have to belong to an organisation? That's business logic, enforced through a not null foreign key on the person table. And so on.

The data in our database arguably always includes business logic, just as a matter of fact about the way we software engineers tend to build systems, but in ways that we consider not just acceptable, but good. Suppose we want to require that a name be not just not null, but at least one character long, so we enforce that in the database. This gives us the benefit that when our application code (say, a front-end, or another service consuming our API) fails to set the name, we get an error back. Having received the error, we know that we need to improve our application to ensure that it always sets that value according to rules enforced in the database. Being able to enforce that rule in the database makes it much more likely we'll catch errors and keep our data in a valid state.

Having said all this, should we just ignore the maxim and now put business logic in the database with reckless abandon? My intuition is that we should not, but that we're going to have to be less rigid and evaluate our situation carefully. In short, we'll have to take to heart a different and also popular maxim when considering what to do:

It depends on your situation

Some business logic can and should go into the database, but some should stay outside. In the case of a project using something like PostgREST, that means storing the bulk of the logic in our api schema, or some similar 'gateway'. Doing so has another advantage, which I'll outline below under 'Rebuilding the API'.

Why have business logic in the database?

Before moving on, I want to state one significant advantage of having the business logic insider the database, rather than inside the application -- where by 'application' I mean the code/services we write that sit outside the database. If our applications access the database solely through the api schema, then our code (outside of the database) becomes much more replaceable. We might write a service in Go, and then realise we want to write a specific service in Python to take advantage of a particular library. Both applications need the ability to cancel orders. If our business logic was all in our Go libraries, then we'd need to either re-implement them in Python, or find a way for the Python service to work through a Go service (perhaps calling a Go based API, such as a gRPC service, and call the 'cancel_order' endpoint). On the other hand, if all the business logic is in the database, the Python service can simply work with its own SQL libraries, pulling data from the API schema, and calling functions that we've created on the api schema to perform certain actions.

We have moved our business logic from the application to the database, and as a results we're much freer to change between programming languages, using whichever works best. But now we've dived into the database with both feet, and swapping PostgreSQL out for, say, SQL Server, will be so much more difficult.

Which is the better option? To be locked more into a language, but freer to move our database, or locked into a database but freer to move our code? Speaking from my experience, with the projects I tend to be involved with, changing databases for an application virtually never happens, but we do with enough regularity find ourselves using different languages for different tasks, utilising the same underlying database. Just as we like to take advantage of the various features of a language, and the libraries available in its wider ecosystem, so would I like to be able to take advantage of the various features of a particular database. Instead of trying to abstract away the database through an ORM, as though it's a fungible commodity to be replaced with some regularity, we lock ourselves into our choice and take advantage of its full capabilities.

Apart from this, there may also be performance benefits, where we can perform all the queries we need in the database at once. In many cases, applications will make multiple trips to the database for a single task. In some instances, this can be improved significantly by improving the application code, but in some cases it will just be faster to do it all on the database side, and less work in total for the database as well.

Resolution 3: Some API tasks won't be possible in a database

Hopefully now you can see how we might have an API with a different model to that of the database, control access carefully, while still keeping our data separated enough from our business logic. How about more complicated features, like sending emails or building PDF's? Or endpoints that don't even need to touch the database, but instead, say, call another service and return its result?

A database like PostgreSQL cannot send emails or build PDF's out of the box. But we do know how to do these things in other languages. PostgreSQL does allow you to write scripts in languages that do support doing things like sending emails or creating pdf's, but I have not explored the benefits and limitations of doing so. My suspicion is that doing this directly in the database is not the best choice (more discussion in How to send mail from database? at depesz.com).

A good option for situations like this is to set up your own message or work queue in the database, and have external services connect to the database, which are responsible for doing tasks like sending emails or building PDF's. These services regularly pull tasks out of your message queue table and process them. PostgreSQL introduced SKIP LOCKED in 9.5, which makes this even easier to use in situations where multiple instances of the same service are trying to pull tasks from the same message queue. You can use SKIP LOCKED to make sure that they don't pull the same task, and that if a service dies or restarts then the task becomes available again. For an example of this, check out What is SKIP LOCKED for in PostgreSQL 9.5? by 2ndQuadrant, and Do You Really Need Redis? How to Get Away with Just PostgreSQL by Atomic Object. Where possible (although 'it depends on your situation'), keep your infrastructure simple and boring.

Now we've opened up our capabilities to use any language we want to perform tasks. Moreover, it should not be so difficult to replace one of these worker services with another written in a new language should we want, even running them side by side.

What about cases where we need to bypass the automated API entirely? In such cases, we can use a proxy to redirect requests to a sidecar API, written in a language (or languages) of our choosing. This gives us more direct control in those cases where we need it. Many proxies will fill the task, such as OpenResty, which is used by subzero. When a request comes in, our proxy decides whether to forward it to our PostgREST API, or to our sidecar API. There are some downsides to this, as it won't appear in PostgREST's description of available endpoints, but it will work (I discuss an untested way to get it to appear in PostgREST's description).

Let us return to the PDF example, where we want the user to submit a payload and get a generated PDF in response. Sometimes you may want to return a response immediately. E.g., an endpoint that submits a request for a PDF, and receive a reply. Without having implemented such a solution myself, I suspect that this will be another instance where we would use a proxy to bypass PostgREST. The sidecar API will receive this request, create a task in the message queue, and then monitor for and return the result (pdf or failure). With PostgREST, we would need a function that can create an entry in the task view, commit that write, and then monitor for and return the result. At the time of this writing, it looks like this would need autonomous transactions, not (yet?) supported by PostgreSQL. However, you can approximate them using a db worker (see Autonomous transaction support in PostgreSQL by dalibo.com). I have not tested it, but this may work as a solution for creating a new task in the task queue, and waiting to return the result, all as part of the one PostgREST API request.

Another option is to use something like OpenResty to create the PDF and return the response.

Or, we can design our API so that consumers submit in one action then poll for and download the result via another when it's ready.

Other remarks

The above answers the main parts of my objections, but beyond my initial objections I've had some additional thoughts experimenting with this approach, which I now present.

A different abstraction

As developers, we try to walk a line between abstraction and raw access. We prefer abstraction when, among other reasons, it allows us to build significantly more with less effort (e.g., generating html surveys from a json specification). We dislike abstraction when it prevents us from using features of the underlying technology (e.g., utilising features of html that the html form generator we're using hasn't exposed, when we know how to write the feature using html but we don't know how to get our generator to write that html).

Automated API's fall into the same category -- an abstraction that we hope can work for most situations, but sometimes it will get in the way when it doesn't support implementing something that we need. The thing we want is an API with a particular structure, and so we build a PostgreSQL schema with the goal of having our automated API produce the API we want. To put it another way: we want a particular API, but we are not building that directly -- we are building a schema that will define the API. When we cannot write the schema in just the right way for the automated API to produce the structure we want, we may find ourselves frustrated with the tool.

In such cases, we can bypass an automated API such as PostgREST using a proxy like nginx, such as described earlier, implementing whatever we can't handle through the automated API. If we find ourselves doing that too frequently, we may start to regret using an automated API and wish to return to building such things more directly.

Suppose that we did decide that an automated API was more trouble than benefit, because we have too many special cases. Does this imply that we should go back to keeping the bulk of business logic in the application and out of the database? I think it does not. We can still benefit from the powerful features of the database, while writing our own custom API that utilises our API schema, rather than using an automated API. It gives us that same flexibility in which language we can use in exchange for inflexibility in which database we use. An automated API is nice when it works, but without it there may still be reasons to desire keeping business logic in the database.

Taking care when writing code -- the developer experience

In my experimentations with this new (old?) way of building systems, there are ways in which our database business logic could become an unmanageable nightmare if we don't take care. Here are some of my new-to-the-process thoughts.

Tracking changes and rebuilding schema

Managing migrations can be troublesome. As a simple setup, we might just write scripts that transform the database in the way required, so it's easy to see what changes were made and apply them. For our projects, this is often enough.

However, when building something like an API, even an automated API, it would be much nicer to be able to track changes in the schema/functions via git, just like we do for application code.

When building an application, if you want to change one line in a function, you simply change the line and commit the code. The exact change is tracked, so it's easy to see what was done.

Contrast this with a simple migration setup like described above. The process here to modify a function involves copying the old function in its entirety, changing the single line, and committing the full new function in a new sequential file. The exact change is not tracked, and if you look at the git history you'll see the full function with no insight into what's changed.

When it comes to the api schema, there is an alternative. If we can avoid storing any data in the api schema, then we always have the option of recreating the whole schema from scratch. PostgreSQL supports Transactional DDL, which means we can make most changes to the structure of a database inside a transaction. If there's an error during the dropping and re-creating of the api schema, then the transaction will fail and we can roll back to how it was before the upgrade. If it succeeds, we replace the new schema with the old.

Now, the advantage here is that instead of having migrations describing how to transform the database from an earlier state to a later state, we simply have a script, or set of scripts, that describe how the API should be. If we want to change one line in a function, we change just that one line, and commit. Now in our commit history we can see exactly which line changed, just as we could for typical application code outside of the database. When we want to apply this change to production, we re-run all of the scripts inside a transaction, which will effectively replace the old schema with the new. Since we don't store data in the API schema, we are not concerned with losing any.

Without some way of tracking changes nicely, I could foresee that writing an api schema in a thick database could become unmanageable. I am interested to see if the same principles here could be applied to business logic that needs to go in the data layer. For example, we may have row level security policies and functions inside the main data database. Ideally, these are (re)created as part of the schema updates above, so we can easily track changes. Because these modify the data schema, much more care needs to be taken. One option might be to use DROP IF EXISTS syntax to drop any and all policies that were ever used, followed by their (re)creation, all inside a transaction. As a result, most changes to the schema can be tracked through git easily.

I am also aware that there are other tools, such as sqitch, available for helping manage database changes in a way that makes it easier to track the history of changes. I have not tried such tools myself, but may look into them in the future. It may be preferable to use tools like this if recreating the schema completely is too slow, or there are changes for which you can't just simply recreate the schema entirely.

Writing tests

Tests are always important, and here is no exception. Ideally we have tests both as part of our SQL statements, as well as integration tests that make requests from our API (whether custom built or automatically generated).

For running unit-style tests against the database, pgtap is a popular choice. Such tests could be built into a CI/CD test, and ideally locally whenever rebuilding the schema. When it comes to integration tests, any tools you like that allow for testing API's could be used.

Extensions in the database

Among its many features, PostgreSQL supports the creation of extensions. (note: many cloud provider managed PostgreSQL instances limit which extensions can be used -- using some extensions may require you to manage your own installation). These allow you to expand the functionality of the database.

Having started my own journey towards learning Rust, I am particularly interested in pgx which allows you to write extensions and background workers in Rust. Writing extensions opens up a lot of possibilites.

Authentication

While you can roll your own, if you use an open source product like Keycloak, or a commercial one like Auth0, it should be fairly straight forward to set up. Keycloak can produce the JWT's that PostgREST can consume.

Without going into detail, I have successfully followed a guide on setting up Auth0 with Flutter but using Keycloak instead of Auth0, which generates tokens at login which can be used directly with a PostgREST API.

In short, there should be a few options available for handling authentication.

Authorisation

PostgREST provides information on how to handle authorisation, including a tutorial called The Golden Key.

PostgreSQL provides support for row level security policies (performance improved in PostgreSQL 10). Using such policies, we can restrict what records a user has access to, and an automatic API like PostgREST will only display the records that user has a right to access. Of course, there is going to be a performance hit from using such policies. That cost needs to be paid somewhere, though -- we need to determine whether a user is authorised for some action or not, and authorisation will involve fetching rows from the database whether we do the authorisation step itself in the database or in the application.

Re-using code

In my limited experience writing functions inside PostgreSQL so far, I'm hitting situations where two functions are remarkably similar, but differ in a small way -- e.g., with regards to the columns they return. This is still an area of exploration for me on how to manage these in a maintainable way, but I'm considering two options:

Dynamically create queries in SQL. Using features such as 'EXECUTE format' I may be able to achieve the result I want. See Executing Dynamic Commands
Compiled templates. As is popular with Go, I could create the generic templates along with the configuration required to generate the final SQL statements needed. Might be more powerful, but could be harder to work with.

Pure SQL functions used inside other queries can in some cases be inlined, so they could be used as an efficient way to encapsulate some repeated code.

Proxy and API spec

If we follow the path of using a proxy to implement endpoints that bypass PostgREST, we'll find that the description of the API provided by PostgREST will diverge further and further. To bypass this, perhaps we can implement mock functions in the API schema so that PostgREST includes them in its description.

Final remarks

The above is a deeper dive into the thoughts of someone who is new to this way of building systems. When I started looking into it, I was hoping to find a guide of 'best practices' for both keeping business logic in the database, as well as using an automated API backed by that database. If I continue to use this approach and find it suitable as a go-to approach, I may write such a document to help others identify good practice and pitfalls, once I work out what those good practices and pitfalls are! For now, hopefully this will serve as some kind of basic introduction for someone else looking into thick databases.

SQL query builders

Mark Saward — Wed, 28 Jul 2021 10:37:15 +0000

My latest attitude towards the database has been to respect it more, by taking advantage of more of the powerful features it has available. That means taking advantage of features specific to my go-to database, PostgreSQL, and locking myself in. I have a pending blog post about my thoughts on that, but for now I wanted to make a quick note on something that seems so simple and obvious, yet I'd never considered before.

Quite often in our application we'll want to customise our WHERE clauses for filtering results. A common example of this is implementing filters for a table of results. To do this, we might loop over a list of filters that come to us from the client (e.g., query parameters in a GET request), and include all and only the filter values which have a value set. If we have one filter requested, then we should add a 'WHERE' clause, and if we have more than one, we should join all the options by 'AND'. It's a small thing to do, but in building up our SQL out of joining strings together, we need to be a little careful to construct it right.

Alternatively, when we're using an ORM or query builder (for Go, I like to use squirrel), adding the correct 'WHERE' and 'AND' terms is handled automatically. A small convenience that we could do ourselves, but then we'll find ourselves building our own in-house micro-query-builder.

The nice thing about not using a query builder or ORM is that you can work directly with the SQL, a great advantage when you're familiar with it and know just what you want to write. You don't run into situations where you think, "I know what the SQL query needs to be, but I don't know how to get this ORM/Query Builder to write that SQL". The problem is you end up composing your SQL queries using your own equivalent of a querybuilder anyway, and then the details of your queries are split all over the place. You can't easily look in one place, and see the query as a whole to understand it. Instead, it's scattered in piecemeal strings throughout your function or wider code.

I've been playing around with Rust some more, and looking at sqlx as an option that lets me stay close to the SQL, with some additional compile time checks. sqlx sends queries to the database at compile time to check that they are valid, which sounds great -- compile time checks for validity save time.

This, of course, won't work when you're constructing your clauses from parts and therefore don't have the whole query written anywhere at compile time that can be checked against the database. For example (written in Go), you might have:

package main

import (
    "fmt"
    "strings"
)

var filters = []struct {
    Name  string
    Value interface{}
}{
    {
        Name:  "name",
        Value: "Homer",
    },
    {
        Name:  "city",
        Value: "Springfield",
    },
}

func main() {
    query := "SELECT * FROM person"

    var where []string
    var args []interface{}
    index := 0

    // Make sure 'filters' are not provided by the client, or are checked against a list of allowed values, so that you don't give an opening for a SQL injection attack:
    for _, filter := range filters {
        index++

        where = append(where, fmt.Sprintf("%s = $%d", filter.Name, index))
        args = append(args, filter.Value)
    }

    if len(where) > 0 {
        query = query + " WHERE " + strings.Join(where, " AND ")
    }

    fmt.Println(query)

    // db.Query(query, args...)
    _ = args
}

We've built our own home brewed SQL building solution, and this example doesn't even deal with ranges -- for example, finding everyone with a date of birth between two dates (or just after a particular date). Those have a different syntax that also needs to be dealt with, complicating our 'quick' homebrewed query builder. Note also that the full query is scattered across parts throughout this function. The query it generates In this case would be:

SELECT * FROM person WHERE name = $1 AND city = $2

But it's very hard to see that at a glance, and it can't be checked in advance. How do we get compile time checks for these runtime constructed queries? I've been thinking about options where we inspect the database to understand what tables and fields there are, and inside Rust we use a macro where we can use simple tags inside our query string that the compiler uses to check are valid values. We could use this to check that we're at least using correct table and field names.

However, I saw another solution for this in an issue for the sqlx project. And that solution is just to have the query itself handle the optional cases! Instead of including them only if they're set, you always list them in the query inside your code, so you don't need to do any kind of runtime building up of the conditions. If the filter is not provided then the query won't filter on that value. Simple, but effective, and should still let sqlx check the query at compile time! And the query is fully expressed, so it's easy to read all in one place, and therefore easy to understand.

Here's an updated version of the above using this method:

package main

import (
    "database/sql"
)

type filter struct {
    Name      sql.NullString
    City      sql.NullString
    DOBBefore sql.NullTime
    DOBAfter  sql.NullTime
}

func main() {
    var f filter
    f.Name = sql.NullString{String: "Homer", Valid: true}
    f.City = sql.NullString{String: "Springfield", Valid: true}

    query := `
SELECT * FROM person
WHERE 
    ($1 IS NULL OR name = $1) AND
    ($2 IS NULL OR city = $2) AND
    ($3 IS NULL OR dob < $3) AND
    ($4 IS NULL OR dob > $4)
`

    rows, err := db.Query(query, f.Name, f.City, f.DOBBefore, f.DOBAfter)

    [...]
}

This is both shorter and much clearer about what's going on. Morever, that query can be checked at compile time with the database, and is easily portable. It even handles date range filters without needing to enhance our quickly built in-house query builder to consider such filters. Also, since we've hard-coded our filter options, we don't run the risk of accidentally allowing any SQL injection attacks because we forgot to properly check our filter names.

It's such a simple and obvious way to handle these things, but it never occurred to me before. I'll be interested to see if this kind of solution can work in most situations, or if it will have common limitations I haven't yet considered.

A simple blog in Go

Mark Saward — Sat, 20 Mar 2021 10:52:05 +0000

It has been a hectic two months. My plans to learn rust have been shelved for now, due to far too much work. However, that hasn't stopped me from doing what I originally tried to wisely avoid: building my own blogging platform from scratch. The reason? I wanted a simple blogging platform that would allow me to play around with and demonstrate new interactive features.

In the last four months I've been doing a lot of reflecting and re-evaluating the ways that we build websites at Episub. I'll likely go into these ideas in future posts, but will give a very short overview here. The sorts of websites we tend to build are ones that are useful as tools for our clients and their staff and/or customers. This means very interactive sites, often involving building tools that automate processes that were previously manual. In recent years, we've moved from traditional ways of building websites (server side rendering, minimal javascript) to modern SPA solutions. In our case, this means a GraphQL API on the back-end, and a React frontend that fetches data from the API to render.

I took some time to step back from this, and reflect on what we have gained from transitioning to such ways of building websites, and what we have lost. And it's become clear to me that these SPA type sites impose significant burdens on development that we just don't need. A (what I think is) clear example of this are how many layers/abstractions we have. In the SPA with GraphQL+React way of building sites, data flows like so:

Database -> Code to translate between database model and API model -> API (GraphQL) -> Front-end fetch -> Render

In the traditional server-side rendered approach, for simple sites, we only need:

Database -> Application fetch from DB -> Render

In this simple case, we can just fetch data directly from the database in whatever shape we please, and skip the whole API translation work. Of course, we can't remove the need for some translation work entirely, unless our application (e.g., a website) is quite simple. Typically that means we still need code that implements our business logic so that we can have a consistent layer no matter which application is connecting. However, there is a significant impedance that comes from working through an API as opposed to calling on the database more directly. Related to this, I've also been exploring 'thick databases', a notion I previously considered anathema (for no good reason). This involves putting business logic in a separate schema in the database, that acts as a window to the underlying database, so that the database model can still differ from the model that we present the world. In this way, every application, regardless of language, can connect to the database and automatically be adhering to our business rules.

I'm optimistic that this will be a simpler setup. It may still involve the same steps for the data flow, but in a much simpler way. Our websites will work much closer to the way the web was build, without trying to replace it as an entire javascript based application. We don't entirely cut out the translation layer, but we do simplify it. I still build the database schema as I always would, and then build a separate API schema on top, inside the database, that uses views to provide the model that makes sense for applications. This 'api' schema implements the business logic, and then we connect to it as we would an ordinary database. Server side rendering websites can talk to the database directly using SQL (a highly valuable ability). And in the case where we need to provide an API, we can use a project like PostgREST, which serves up the api schema we built which implements all the business rules.

What about the interactivity we get from using something like React? Again, a story for another post, but the short of it is I can get most if not all of what I need from a small library like htmx. There are two particularly exciting things about using something like htmx. First, is that for most functionality the site will still function if javascript is disabled. The second is that websites are super quick to load. With Tailwind, htmx, and a splash of other projects where needed, pages can be super slim and the first (as well as all subsequent) load time can be very fast.

Back to my blog. Inspired by returning to this simpler way of building websites, I created a very simple Go server for my blog, less than 200 lines in code (not including html templates), and no longer use Hugo. In addition, I have a very simple postgres schema for now. Using Tailwind CSS and slimming it down to just the classes I need, prism.js for syntax highlighting, and soon htmx for some interactivity, the pages are still <100KB. I now am in a good position to add live demonstrations of things I write about, add some simple interactivity, and expand as I please. Given the simple nature of this blog project, I haven't created a separate api schema and will just work with the database directly for now.

So that's where I am now. A new foundation for my blog, and an optimism about further honing my craft. Still some rough edges (summaries don't mix right with markdown yet, pagination when I have too many posts), but these are minor issues that will be quick to resolve. Here's the code for the blog as it is at this point of time (MIT licence, use it if you please):

package main

import (
    "database/sql"
    "html/template"
    "log"
    "net/http"
    "time"

    "github.com/caarlos0/env/v6"
    "github.com/gofrs/uuid"
    "github.com/gomarkdown/markdown"
    "github.com/jmoiron/sqlx"
    "github.com/labstack/echo/v4"
    "github.com/labstack/echo/v4/middleware"
    _ "github.com/lib/pq"
)

var dbx *sqlx.DB
// cfg Do not change after initial load, as it may be accessed on multiple threads
var cfg Cfg

var sqlPostFields = "post_id, title, link_name, content, left(content, 200) || '...' AS summary, is_published, published_at"

// Cfg Env config
type Cfg struct {
    DatabaseURL string `env:"DATABASE_URL,required"`
    Debug       bool   `env:"DEBUG" envDefault:"false"`
}

func main() {
    err := env.Parse(&cfg)
    if err != nil {
        log.Fatal(err)
    }

    initDB()
    initRouter()
}

func initDB() {
    var err error
    dbx, err = sqlx.Open("postgres", cfg.DatabaseURL)
    if err != nil {
        log.Panic(err)
    }
}

var csrfSkipRoutes = []string{}

var csrfSkipper = func(c echo.Context) bool {
    for _, v := range csrfSkipRoutes {
        if v == c.Path() {
            return true
        }
    }
    return false
}

func initRouter() {
    fmap := template.FuncMap{
        "markdown": Markdown,
    }
    t := &Template{
        templates: template.Must(template.New("").Funcs(fmap).ParseGlob("web/template/*.html")),
    }
    // Echo instance
    e := echo.New()
    e.Renderer = t
    e.Static("/static", "web/static")

    // Middleware
    e.Use(middleware.Logger())
    e.Use(middleware.Recover())
    e.Pre(middleware.RemoveTrailingSlash())

    e.Use(middleware.CSRFWithConfig(middleware.CSRFConfig{
        CookiePath:  "/",
        Skipper:     csrfSkipper,
        TokenLookup: "form:csrf",
    }))

    // Routes
    e.GET("/", indexHandler)
    e.GET("/posts/:name", postViewHandler)

    // Start server
    e.Logger.Fatal(e.Start(":1323"))
}

// templatePayload Returns the provided data under the 'data' tag, along with
// a standard payload of data that may be needed on every page
func templatePayload(c echo.Context, data map[string]interface{}) map[string]interface{} {
    input := make(map[string]interface{})

    if data != nil {
        input["data"] = data
    }

    if csrf, ok := c.Get(middleware.DefaultCSRFConfig.ContextKey).(string); ok {
        input["CSRF"] = csrf
    }
    input["referer"] = c.Request().Referer()
    input["url"] = c.Request().URL

    return input
}

func Markdown(str string) template.HTML {
    md := []byte(str)
    output := markdown.ToHTML(md, nil, nil)

    return template.HTML(output)
}

// post A blog post entry
type post struct {
    PostID      uuid.UUID `db:"post_id"`
    Title       string    `db:"title"`
    LinkName    string    `db:"link_name"`
    Content     string    `db:"content"`
    Summary     string    `db:"summary"`
    IsPublished bool      `db:"is_published"`
    PublishedAt time.Time `db:"published_at"`
}

func indexHandler(c echo.Context) error {
    posts, err := postList()
    if err != nil {
        return err
    }

    data := map[string]interface{}{
        "posts": posts,
    }

    return c.Render(http.StatusOK, "index.html", templatePayload(c, data))
}

func postViewHandler(c echo.Context) error {
    name := c.Param("name")
    p, err := postByName(name)
    if err != nil {
        if err == sql.ErrNoRows {
            return echo.NewHTTPError(http.StatusNotFound)
        }
        return err
    }

    data := map[string]interface{}{
        "post": p,
    }

    return c.Render(http.StatusOK, "post_view.html", templatePayload(c, data))
}

func postList() ([]post, error) {
    var pl []post
    qry := "SELECT " + sqlPostFields + " FROM manse.post"

    if !cfg.Debug {
        qry = qry + " WHERE is_published = true"
    }

    qry = qry + " ORDER BY published_at DESC"

    err := dbx.Select(&pl, qry)
    return pl, err
}

func postByName(name string) (post, error) {
    var p post
    qry := "SELECT " + sqlPostFields + " FROM manse.post WHERE link_name = $1"

    if !cfg.Debug {
        qry = qry + " AND is_published = true"
    }

    qry = qry + " ORDER BY published_at DESC"

    err := dbx.Get(&p, qry, name)
    return p, err
}

Rust and Go department directories

Mark Saward — Mon, 25 Jan 2021 10:19:06 +0000

Continuing my journey with Rust, I recently completed a suggested exercise from "The Book":

Using a hash map and vectors, create a text interface to allow a user to add employee names to a department in a company. For example, “Add Sally to Engineering” or “Add Amir to Sales.” Then let the user retrieve a list of all people in a department or all people in the company by department, sorted alphabetically.

Having completed the exercise in Rust, I wondered what differences I would note if I implemented the same thing in Go, a language that I am much more comfortable with. In order to compare more easily, I wrote a similar implementation (with a similar code structure) in Go. Code for both the Rust and the Go versions are at the bottom of this article.

Lines of code

The first observation is that the Rust code comes in at 131 lines, and the Go code at 158. While the Rust code is a little shorter, I suspect that more knowledge of and experience with Rust would enable further simplifications. Rust seems to have a lot more language features than Go. While language features can be helpful, they do have a cost: there's a lot more you need to know and keep in your head in order to read other people's code (and sometimes your own). There's some advantages to a smaller feature set, even if it means you sometimes write a handful of extra lines when implementing certain things. It can be easier to read and interpret a few extra lines of code that make explicit the behaviour, than read code using some clever features of convenience that I only see once every few months. I think Go could do with a small number of extra language features, but I worry that Rust has too many. It seems like there is a lot to learn and keep in one's head, but it remains to be seen by me if Rust has too much, or whether with practice the burden will seem light.

Control over use

Another thing I experienced when writing the Rust code is how it can afford me a much greater ability to define exactly how my code is to be used. One problem that exists with Go code is that you can misuse packages in ways that break things. For example, in the Go implementation for this task, nothing stops a developer from declaring org := Organisation{} and then having the program crash when you try to add someone to a department because the map was not initialised. In the Rust version, the same code would fail to compile unless you initialise the HashMap when you instantiate the struct. Furthermore, it seems that if we wanted in Rust to stop people from initialising the struct themselves at all -- e.g., to ensure struct is filled out with some default data -- then we could separate it into a module with appropriate members being private so that external consumers cannot construct the struct directly.

You can have private members in Go, but there's more hoops to jump through. To achieve something similar to Rust, likewise we would put 'Organisation' into its own package, and keep the departments field private. Unfortunately, developers can still instantiate the struct without first initialising the map. For example, suppose we created the following package to import:

package company

type Organisation struct {
    departments map[string][]string
}

func (o *Organisation) Add(department string, name string) {
    if o.departments[department] == nil {
        o.departments[department] = make([]string, 0)
    }

    o.departments[department] = append(o.departments[department], name)
}

...

func NewOrganisation() Organisation {
    return Organisation{departments: make(map[string][]string)}
}

Anyone who uses the NewOrganisation constructor will have a properly initialised Organisation struct. However, a programmer could still avoid the constructor like so:

org := company.Organisation{}

And then any call to org.Add() will panic because the departments map is not initialised. We can work around this in a couple of ways. The most direct way is to have a check inside EVERY function call that makes use of departments, which ensure that the field has been initialised. This means the creator of the package needs to be vigilant to ensure that they check all required fields are initialised as they should be in every function that accesses those fields.

Another option is to use an interface. We can define a new interface that specifies the kinds of methods we want to be able to call. We then make the Organisation struct private, so that the only way for an external package to obtain an instance is via the constructor. E.g.:

package main

type companyOrganisation interface {
  Add(string, string)
  ...
}

package company

type organisation struct {
    departments map[string][]string
}

func (o *organisation) Add(department string, name string) {
    if o.departments[department] == nil {
        o.departments[department] = make([]string, 0)
    }

    o.departments[department] = append(o.departments[department], name)
}

...

func NewOrganisation() organisation {
    return Organisation{departments: make(map[string][]string)}
}

The main package cannot access organisation to directly initialise it, and all calls are made through the interface. If we made the struct private without then declaring an interface, we couldn't then write functions in our main package that have organisation listed in the function signature. The interface allows us to still do so, and also makes it easier to trade one implementation of an organisation with another. You can read more detail about this in Bypassing Golang's lack of constructors.

Of course, these enhancements still don't protect the programmer in the company package from creating a new organisation struct without initialising it. In Rust, this doesn't happen because the HashMap is not declared as an Option, and so the compiler complains if you create a new instance of the struct without initialising the HashMap.

We can achieve a great deal of the safety Rust has in this case in Go, but not fully, and with a bit more effort. I don't mind necessarily if my code is more verbose, but even using interfaces in Go doesn't give you the same compiler time safety as Rust does in this instance.

Referencing a HashMap entry

One of the things that Rust seems to be praised for is that it helps programmers avoid many common mistakes. I was therefore a little surprised to see that the following code will compile:

use std::collections::HashMap;

fn main() {
    let hm: HashMap<String, String> = HashMap::new();

    let msg = &hm[&String::from("does not exist")];
    println!("{}", msg);
}

Since does not exist does not exist as a key, it panics:

    Finished dev [unoptimized + debuginfo] target(s) in 0.54s
     Running `target/debug/play`
thread 'main' panicked at 'no entry found for key', src/main.rs:6:16
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This happens because fetching a value by its key using [key] either returns the value, or panics. What I thought might happen in such an instance is that the HashMap would return an Option as a way to either provide the value, or tell us that there is None. Rust does let you fetch a value via the get method which returns an option that needs to be then checked for Some or None. Using get will help you avoid requesting a value for a key that does not exist. The implementation for the index, that is, fetching by [key], appears to just be a call itself to get, returning the value wrapped by Some, or panicking if not:

    fn index(&self, key: &Q) -> &V {
        self.get(key).expect("no entry found for key")
    }

To avoid making mistakes like this, we can just avoid fetching by index, and instead use get every time. If there's cases where we want to panic if the key doesn't exist, then we can explicitly use get(key).expect("no entry found for key") to make it clearer that we want to panic.

In short, it seems a little odd to me at the moment that the default behaviour for fetching a value by index in the way you do in many other language leads you to missing out on valuable compile time checks. A potential trap for newer programmers coming from other languages?

No redundant return values

One of the nice features about Go is that you can return multiple values without having to define a new object or struct that can carry all the values you want to return. In Go code, we frequently return both the value that is desired, as well as an error value that may or may not be nil.

For most functions, when we receive an error, we discard any returned value as possibly incorrect, or corrupt, or nil, or just the default value. That means we typically only care about two cases: the value when error is nil, or the error when error is not nil. In Go, however, four possible combinations of values are returned (a similar point is made in Aiming for correctness with types):

Value is provided, error is nil
Value is provided, error is not nil
Value is not provided, error is nil
Value is not provided, error is not nil

In Rust, with the Result enum we can cover exactly the two cases we care about: Ok with the value provided, or Err with an error, and thereby avoid redundant returned values. In the particular programming exercise that this blog post was inspired by, I made use of enums to describe the possible return values from executions of various commands:

enum Action {
    Failure(String),
    Done,
    Quit,
}

For Done and Quit, no value needs to be returned from the function, but for Failure we want to know what the returned message is so we can do something about it -- in this case, print the failure message for the user.

In Go, I used a similar pattern, in the form of a new type:

type Action string

var (
    ActionQuit    Action = "quit"
    ActionDone    Action = "done"
    ActionFailure Action = "failure"
)

However, unlike in Rust, I can't send a message alongside with returning ActionFailure. So in this case, ActionFailure despite being returned, is never checked, since I always accompany it with an error. It would be good if I could force the requirement that every ActionFailure be accompanied by a message of some sort. In Rust, it's nice that I can make enums be so useful, and moreover, the compiler will throw errors if I have enum values that are never used in match statements. Compare that to Go where missing type values in a switch statement will not throw any kind of warning.

Moreover, while I haven't tested, I assume in Rust that if I were to put this into a separate module that it wouldn't be possible for consumers of the module to invent their own enum entries. In Go, while we have this type as public, any programmer can create their own entries and use them to return meaningless actions, since the type is public. If I make the type private, then it can't be put in function signatures by external consumers of the package.

The code

That's the end of my observations for now. Regarding the exercise itself, I did not follow the instructions for this quite exactly. Among other tweaks, I added 'help' and 'quit' commands, while also assuming everything is entered in lower case.

Rust

As mentioned before, I am in the process of learning Rust and its myriad of features. I have no doubt there will be better ways to write this. If I was to take this further, I would also implement handling of both upper and lower case for the commands, as well as splitting 'Organisation' into its own module to control its usage better.

use std::io;
use std::io::Write;
use std::collections::HashMap;

enum Action {
    Failure(String),
    Done,
    Quit,
}

struct Organisation {
    departments: HashMap<String, Vec<String>>,
}

impl Organisation {
    fn new() -> Organisation {
        return Organisation{
            departments: HashMap::new(),
        }
    }

    fn add(&mut self, department: String, name: String) {
        self.departments.entry(department)
        .or_insert_with(Vec::new)
        .push(name);
    }

    fn print(&self) {
        let mut keys: Vec<String> = self.departments.keys().cloned().collect();
        keys.sort();
        for key in keys {
            println!("{}:", key);
            self.print_department(key);
        }
    }

    fn print_department(&self, name: String) {
        let dep_op = self.departments.get(&name);
        let mut dep = match dep_op {
            None => {
                println!("No department named '{}' found", name);
                return
            },
            Some(x) => x.clone(),
        };

        dep.sort();
        for name in dep {
            println!("* {}", name);
        }
    }
}

fn main() {
    let mut org = Organisation::new();

    println!("Hi!  Enter 'help' for information on available commands.");

    loop {
        let mut cmd = String::new();
        print!("> ");

        let _ = io::stdout().flush();
        io::stdin().read_line(&mut cmd).expect("Did not enter a correct string");

        let action = parse_command(&mut cmd, &mut org);

        match action {
            Action::Failure(s) => println!("{}", s),
            Action::Quit => break,
            Action::Done => continue,
        }
    }
}

fn parse_command(cmd: &mut String, org: &mut Organisation) -> Action {
    let parts: Vec<&str> = cmd.split_whitespace().collect();
    if parts.len() == 0 {
        return Action::Failure(String::from("No commands found"));
    }

    match parts[0] {
        "add" => return add_command(parts, org),
        "help" => return help_command(),
        "list" => return list_command(parts, org),
        "quit" => return Action::Quit,
        _ => return Action::Failure(format!("Unknown command {}", parts[0])),
    }
}

fn help_command() -> Action {
    let help_msg = r#"
add: add <person> to <department>
help: print this message
list: view all people and departmnets
quit: exit program
"#;

    println!("{}", help_msg);

    return Action::Done;
}

fn add_command(parts: Vec<&str>, org: &mut Organisation) -> Action {
    let expected = String::from("Expect command of form: add <name> to <department>");
    if parts.len() != 4 {
        return Action::Failure(expected);
    }

    if parts[2] != "to" {
        return Action::Failure(expected);
    }

    org.add(String::from(parts[3]), String::from(parts[1]));

    return Action::Done;
}

fn list_command(parts: Vec<&str>, org: &mut Organisation) -> Action {
    if parts.len() == 1 {
        org.print();
        return Action::Done;
    }

    if parts.len() == 2 {
        org.print_department(String::from(parts[1]));
        return Action::Done;
    }

    return Action::Failure(String::from("Unexpected usage.  Expect 0 or 1 parameters for list"));
}

Go

Like with the Rust code, and as discussed before, there are enhancements we could make such as switching the Organisation struct into a separate package, and using interfaces to control access.

package main

import (
    "bufio"
    "fmt"
    "os"
    "sort"
    "strings"
)

type Action string

var (
    ActionQuit    Action = "quit"
    ActionDone    Action = "done"
    ActionFailure Action = "failure"
)

type Organisation struct {
    departments map[string][]string
}

func (o *Organisation) Add(department string, name string) {
    if o.departments[department] == nil {
        o.departments[department] = make([]string, 0)
    }

    o.departments[department] = append(o.departments[department], name)
}

func (o *Organisation) Print() {
    keys := make([]string, 0)
    for k := range o.departments {
        keys = append(keys, k)
    }

    sort.Strings(keys)

    for _, k := range keys {
        fmt.Println(k + ":")
        o.PrintDepartment(k)
    }
}

func (o *Organisation) PrintDepartment(department string) {
    dep, ok := o.departments[department]
    if !ok {
        fmt.Printf("No department named '%s' found\n", department)
        return
    }

    sort.Strings(dep)

    for _, name := range dep {
        fmt.Println("* " + name)
    }
}

func NewOrganisation() Organisation {
    return Organisation{departments: make(map[string][]string)}
}

func main() {
    // org := NewOrganisation()
    org := NewOrganisation()

    reader := bufio.NewReader(os.Stdin)
    fmt.Println("Hi!  Enter 'help' for information on available commands.")

    done := false
    for !done {
        fmt.Print("> ")
        text, err := reader.ReadString('\n')
        if err != nil {
            panic(err)
        }

        text = strings.TrimSpace(text)

        action, err := parseCommand(text, org)
        if err != nil {
            fmt.Println(err.Error())
            continue
        }

        switch action {
        case ActionQuit:
            done = true
            break
        case ActionDone:
            continue
        }
    }

}

func parseCommand(cmd string, org Organisation) (Action, error) {
    parts := strings.Split(cmd, " ")
    if len(parts) == 0 {
        return ActionFailure, fmt.Errorf("No commands found")
    }

    switch parts[0] {
    case "add":
        return addCommand(parts, org)
    case "help":
        return helpCommand()
    case "list":
        return listCommand(parts, org)
    case "quit":
        return ActionQuit, nil
    default:
        return ActionFailure, fmt.Errorf("Unknown command %s", parts[0])
    }
}

func helpCommand() (Action, error) {
    msg := `
add: add <person> to <department>
help: print this message
list: view all people and departmnets
quit: exit program
`

    fmt.Println(msg)

    return ActionDone, nil
}

func addCommand(parts []string, org Organisation) (Action, error) {
    errExp := fmt.Errorf("Expect command of form: add <name> to <department>")

    if len(parts) != 4 {
        return ActionFailure, errExp
    }

    if parts[2] != "to" {
        return ActionFailure, errExp
    }

    org.Add(parts[3], parts[1])

    return ActionDone, nil
}

func listCommand(parts []string, org Organisation) (Action, error) {
    if len(parts) == 1 {
        org.Print()
        return ActionDone, nil
    }

    if len(parts) == 2 {
        org.PrintDepartment(parts[1])
        return ActionDone, nil
    }

    return ActionFailure, fmt.Errorf("Unexpected usage.  Expect 0 or 1 parameters for list")
}

Caddy vs Traefik

Mark Saward — Tue, 19 Jan 2021 12:36:16 +0000

This post will be a relatively short account of my preference for Caddy over Traefik.

A fair few months ago, enough that the details have been lost and all that remains is the lesson I drew, I tried to use Traefik for a new very simple deployment. I had previously successfully used Traefik for a toy project on my raspberry pi, with it automatically registering Let's Encrypt certificates with docker containers. That sounded nice, and with a little effort, it worked (and continues to work to this day).

As a result, I tried duplicating this same simple setup for another deployment that didn't need anything as remotely advanced as Kubernetes which I sometimes use. It was a simple project, since I was pretty much duplicating the configuration I already had. It didn't work. I spent many hours that day looking at the documentation trying different things, carefully looking over the spelling of names in my configurations, and could not see anything in the documentation that would suggest I had misconfigured, nor any notable point of difference with my working setup.

In the end, I was too frustrated with the experience of it not working when it should work, and started to feel like it was too 'magic'. I instead tried Caddy which I've used for other projects as well. Within about 10 minutes I had my complete setup working! It was night and day. Caddy is just simple, obvious, easy to set up, and simply works. I can't see myself using Traefik again.

While there are some success stories, the stories that resonate with me are the failure stories like these from Hacker News:

I wish I could like Traefik, but it really isn't easy.

The use case in our Hackerspace was to dispatch different Docker containers through our wild-card subdomains. Traefik is supposed to also automatically create TLS certificates. I had numerous problems with the Let's Encrypt functionality.

Debugging information is quite cryptic, the documentation seems all over to me, which is even more problematic given the number of breaking changes between 1.x and 2.x versions. The way you automatically configure things through Docker labels means that a simple typo can render your configuration ignored.

by d33.

I worked on a project last year where we tried using Traefik on Kubernetes together with Let's Encrypt certs. It worked... sometimes.

We had significant issues with Traefik not allocating or renewing certs, resulting in some painful outages. The worst part was that there was no workaround; when adding a new domain to an ingress, it was completely incomprehensible why Traefik wasn't requesting a cert, or indeed why it wasn't renewing older ones that were close to expiration. We filed GitHub issues with concrete errors, but they were never addressed. At the time, I tried to debug Traefik to understand how it worked and maybe chase down some of those bugs. I don't like to speak ill of other people's code — let's just say that peeking under the covers made me realize perfectly why Traefik was so brittle and buggy.

by atombender.

I tried, really tried to use traefik for a year. It worked sometimes, the setup was complicated and the community support is very poor.

I eventually moved to caddy (https://caddyserver.com/) and it is fantastic. Works seamlessly and I got all my obvious and not so obvious questions answered.

by BrandoElFollito.

In short, I do not recommend Traefik, and highly recommend Caddy over similar projects for deployments that are within its wheelhouse.

Rust match guards and exhaustive conditions

Mark Saward — Sun, 03 Jan 2021 13:52:14 +0000

I have started learning the Rust language, to see what people find attractive about it, and to understand cases where I may want to use it. A post on correctness with types by Amos (fasterthanlime) seemed to offer some tantalising benefits. It reminded me of some of the struggles I had with Go when I first started learning it years ago -- things like my inability to control exactly how my types are used to prevent programmers from making mistakes, and my inabilty to create types that could do certain things that the core language types can do (e.g., telling Go how to handle len or range with my own structs). Once I learned these things were not possible in Go, I proceeded with my learning and still used the language productively, ignoring or working around these defecits.

Anyway, this post is not about my reasons for learning Rust, but instead to point out something interesting I found that I can't find in the documentation yet. One of the promises in Amos' post is about how Rust should enable me to write correct code, to avoid common errors. One thing that seems promising is that Rust is clever enough to tell me when my match doesn't cover all possible conditions. For example, consider the following code:

fn main() {
    let number: u8 = 4;

    match number {
        0 => println!("Zero"),
    }
}

The compiler will throw an error, because I've missed cases -- for example, when number == 4:

error[E0004]: non-exhaustive patterns: `1_u8..=u8::MAX` not covered
 --> src/main.rs:4:11
  |
4 |     match number {
  |           ^^^^^^ pattern `1_u8..=u8::MAX` not covered
  |
  = help: ensure that all possible cases are being handled, possibly by adding wildcards or mor
e match arms
  = note: the matched value is of type `u8`

error: aborting due to previous error

It even lets you know which patterns haven't been covered. We can fix this by adding a new condition that covers the remaining possible cases:

fn main() {
    let number: u8 = 4;

    match number {
        0 => println!("Zero"),
        1..=u8::MAX => println!("Greater than zero"),
    }
}

And then it compiles without issue. I thought this is very nice to have, forcing us to consider all possible cases, and reminding us when we miss them (and when we miss them). As The Book says:

Rust knows that we didn’t cover every possible case and even knows which pattern we forgot!
...
Rust also has a pattern we can use when we don’t want to list all possible values.

(emphasis added)

I wanted to know what happens if I tried my own custom expressions using match guards, because that would be very impressive if the compiler could evaluate those for missing conditions:

fn main() {
    let number: u8 = 4;

    match number {
        i if i == 0 => println!("Zero"),
        i if i > 0 => println!("Greater than zero"),
    }
}

Completely understandable, this code does not compile, even though it covers the same cases as the original:

error[E0004]: non-exhaustive patterns: `_` not covered
 --> src/main.rs:4:11
  |
4 |     match number {
  |           ^^^^^^ pattern `_` not covered
  |
  = help: ensure that all possible cases are being handled, possibly by adding wildcards or mor
e match arms
  = note: the matched value is of type `u8`

It turns out in fact that the compiler does not look into arbitrary expressions like these to determine whether the cases included are exhaustive or not. Not surprising, but I haven't been able to find this documented anywhere yet, which led me to checking for myself. The solution in this case is to simply include a case for the _ pattern when using match guards:

fn main() {
    let number: u8 = 4;

    match number {
        i if i == 0 => println!("Zero"),
        i if i > 0 => println!("Greater than zero"),
        _ => println!("Fell through"), // This should not be possible to reach
    }
}

Easy updates for your Hugo blog using Caddy

Mark Saward — Thu, 14 May 2020 12:46:17 +0000

Previously I wrote about my initial plan for creating my blog using Hugo. This is a brief post on how to make it super easy to deploy updates to your blog. In fact, as easy as a git commit! All it takes is pushing your latest changes for your blog to your git repository, and it shows up automatically on your live site. Please note, this post assumes familiarity with Docker.

I'm currently running Hugo on my Raspberry Pi, using traefik (which I do not recommend -- use Caddy instead if you can) as a load balancer and reverse proxy, along with docker-compose files for easily starting and stopping my services. For this setup, it's necessary to use Caddy 1 (in my case sitting behind traefik), since we make use of the http.git directive that doesn't (as of this moment) have a built-in analog in Caddy 2. I'll look to move to Caddy 2 at some point in the future.

To run Caddy on my RPI, I need an ARM build of Caddy. There's one available via the elswork/arm-caddy image. Once Caddy is configured correctly, it will regularly check the git repository for updates, and, upon finding them, will run Hugo within the container to build the newest version. We aren't pushing a pre-built version of the blog to our repo, but rather the raw files through which our Docker container can subsequently build the latest version for us. Here is an example Dockerfile that uses the ARM Caddy image, and downloads a specified version of Hugo to use:

FROM elswork/arm-caddy:1.0.0

ARG hugo_version=0.64.0

RUN apk add --no-cache openssh-client git tar curl

RUN curl --silent --show-error --fail --location \
  --header "Accept: application/tar+gzip, application/x-gzip, application/octet-stream" -o - \
  "https://github.com/spf13/hugo/releases/download/v${hugo_version}/hugo_${hugo_version}_Linux-64bit.tar.gz" \
  | tar --no-same-owner -C /tmp -xz \
  && mv /tmp/hugo /usr/bin/hugo \
  && chmod 0755 /usr/bin/hugo \
  && git config --global fetch.recurseSubmodules true \
  && mkdir -p /www/public

This should install everything you need to run Caddy in a docker container with git support to pull our latest changes, and Hugo to build the site. You can create this as a public project on Github or your preferred place, and then configure Dockerhub to create builds for you. That image can then be used in a docker-compose.yml file to start your service. E.g.:

version: "3.3"
networks:
  web:
    external: true
services:
  caddy:
    image: "saward/caddy-hugo-arm:1.0.0-0.64.0"
    container_name: "caddy"
    restart: always
    networks:
      - web
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./Caddyfile:/etc/Caddyfile"
      - "./certificates:/root/.caddy"
      - "/home/pi/.ssh:/home/pi/.ssh"
      - "/home/pi/caddylogs:/caddylogs"

This simply starts a docker container using our new image (built via Dockerhub). Some notes on the volumes:

The Caddyfile is stored on our filesystem, and we mount it from the host system.
We store certificates from Let's Encrypt to avoid spamming their service whenever we restart.
SSH key is used so that if your repository is private, the git command can read the contents. I recommend using a read-only deploy key to minimise the damage if your server is ever compromised.
Logs are taken and mounted externally for analytics (a subject for another blog post).

Finally, we need a Caddy file (again, this is v1 of Caddy), where the magic happens. Using the http.git directive, we can instruct Caddy to clone our blog repository when it starts, and to check for updates every 5 minutes. Whenever there is a change, it will run the Hugo command to build our final version. The version of the site built within the container is what Caddy serves whenever someone hits the server at the manse.cloud domain!

manse.cloud {
        log / /caddylogs/manse.cloud/access.log {combined}
        root /home/pi/www
        git {
                repo     git@github.com:saward/mansecloud
                path     /home/mansecloud
                branch   master
                clone_args --recurse-submodules -j8
                key      /home/yourhome/.ssh/id_rsa
                interval 300
                then     hugo -s /home/mansecloud/blog --destination /home/pi/www
        }
}

And that's it. Every time you have a new post ready (not a draft), and you push, you should see it show up live within 5 minutes. Easy.

Hosting my new blog with Hugo

Mark Saward — Wed, 13 May 2020 04:49:27 +0000

In the last few days I've decided it's time to start my own blog, so here we are! This blog is intended to contain a mix of topics such as programming/technology, philosophy, and other random thoughts, with an emphasis in that order (primarily technology). In making this decision, I found myself asking the question, "Do I really want to use Wordpress?". For my work, I run a small but growing software development company, where we focus mostly on integrating systems and creating internal tools (usually in the form of web-apps). I have a good understanding of the lifecycle of not just running CMS's like Wordpress, but also how to create them. And so the question is: do I go for the simple solution of setting up WordPress, or do I give in to temptation and minimise my chances of success by over-engineer a solution for this brand new project?

In the end, I've decided on a compromise: a static site generator. I won't be taking the easy path of using WordPress, but I also won't be doing something enormously difficult. A static site generator lets you create your content and then build the raw html files based on templates and content you provide it. If you then edit a page, or add new content, you rebuild the site and upload a new version. There's no fancy JavaScript behind the scenes (though you could add that if you wanted), just the plain old html files.

There's a few reasons why a static site generator appeals to me over a full CMS platform like WordPress:

Fast! Since we're just serving raw html files, once the site is deployed there's no processing for the server to do beyond reading the file off the filesystem and sending it back to the client. Furthermore, if we keep our templates clean, these files can be very small. With some generators, no JavaScript is required for rendering the site. Unlike a React site, we aren't providing the equivalent of an application for download, just the final rendered HTML. Furthermore, given that the content is all static, such sites are very friendly for hiding behind a CDN like Cloudflare, and can be served very fast around the world with ease.
Ease of deploy. To run this system, all we need is a server capable of serving up static files. That means I could throw this site onto a Raspberry Pi behind a Caddy server instance (caddy), throw them into a Google Cloud Bucket, or any other simple hosting mechanism I like. There's no database required. A static site opens up hosting opportunities unavailable to sites like WordPress.
Low system resources. I plan to run this on my own Raspberry Pi 4, a relatively beastly machine. With plain HTML files, no server side rendering, this thing is super easy to host on a low cost machine like the RPi.
Security. Since there are no moving parts, your security risks are much more limited to things like the server you're running it on, and the service that serves the files (Caddy, Apache, etc). It significantly reduces the surface area for possible attacks.
Control. There's a great simplicity to running a site like this, and with that simplicity comes control. While I can modify the internals of WordPress, there's a great deal to learn to do so in a competent way in line with the way WordPress has been designed. With straight HTML templates, it's much simpler for me to make changes and understand the consequences. Of course, with WordPress comes the significant advantage that there are a ton of plugins pre-made to do what you want, so I don't want to oversell the case here -- but there is an appeal to the control that comes from simplicity.
Markdown. Out of the box, many static site generators let me write content in a simple way using Markdown, which I'm keen on.

There's no question that a static site generator involves more fiddling than paying a nominal hosting fee, choosing a template, and starting your blogging WordPress. However, the reasons above on balance have weighed in favour of me going the static file path.

And for that task, I'll be beginning this journey with Hugo. I did look into fancier JavaScript generators like Gatsby, but as someone who is not a fan of JavaScript (and excited about the prospects of WebAssembly enabling challenges to its hegemony), and being keen to retain control and simplicity, it's my preference to go with something like Hugo. Also, while I'm not a boomer myself, I'm old enough to have started learning about web technology when PHP was young, and so this boomer's sentiments resonated with me (and while I note he has since managed to win his fight with Gatsby, as someone who uses React I lack the same motivation to use something like Gatsby for the purposes of improving my JS/React skills).

Next steps

With the site up and running, some things I'll be looking at next include:

Personalise the layout and details (word counts, name, image(s), social media accounts, etc)
Supporting RSS feeds (which I still use!)
Cloudflare for caching, particularly of images
Something for monitoring that avoids Google Analytics, perhaps GoAccess
Possibly my own dummy JS file so that even if a file is cached by CDN, there's still a hit to my server that I can log
Newsletter or similar signup option
Commenting system that respects privacy (no tracking)
Tags/categories