From caa7af3fb549ebd4e449c17dffad8bdd6593ea58 Mon Sep 17 00:00:00 2001 From: Stefan Majewsky Date: Sat, 18 Apr 2026 16:24:52 +0200 Subject: write out a proper README --- README.md | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b40d2b1..5d614cd 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,36 @@ SPDX-License-Identifier: Apache-2.0 # Oblast -My attempt at a minimal ORM library for Go. Inspired by [Gorp](https://pkg.go.dev/gopkg.in/gorp.v3), but without the bits that make Gorp slow. +A small ORM library for Go, focused on type safety and performance. Inspired by [Gorp](https://pkg.go.dev/gopkg.in/gorp.v3), but without the bits that make Gorp slow. You may think that the name refers to the type of administrative division that exists in several Slavic countries, but it's actually just an acronym for what this library does: **Ob**ject **L**oading **A**nd **St**oring. -## Unstructured notes +## How to use -TODO: write out a proper readme +Please refer to the [package documentation](https://pkg.go.dev/go.xyrillian.de/oblast). -- goals: as fast as possible, as little allocs on hot paths as possible -- consequences: no `context.Context` (benchmarking shows up to 50% more allocations and 100% more memory allocated in OLTP usecase, i.e. QueryRow vs. QueryRowContext) +## Design goals and priorities + +The design goals, ordered by priority (most important comes first), are: + +- An intuitive API that encodes type safety through the use of generics. +- A minimal amount of memory allocations in hot paths. +- A minimal amount of CPU usage. + +As a surprising consequence, this meant having to eschew `context.Context` arguments. +Early benchmarking showed that replacing `QueryRow` with `QueryRowContext` increased allocations by up to 50% and memory allocated by up to 100%. +The author of this library is still a fan of `context.Context` for things like HTTP requests to external services. +But this library optimizes for blazing fast OLTP workloads (with maybe a few OLAP queries every once in a while), where not being able to back out of a running query is not that big of a deal because query runtimes should always be short anyway. +If in doubt, the lack of `context.Context` arguments can be counteracted by setting timeouts on your DB transactions. + +Explicit non-goals include: + +- A fully featured API for query construction: + Oblast does not offer methods like `table.Where("created_at < ?", time.Now()).Order("name").Join("products")`; it only deals with mapping between database columns and fields of struct types, nothing else. + This is not just a question of performance. + The author of this library does not believe that it is worthwhile to have an API like this. + Writing SQL queries by hand is significantly simpler, and does not take away any convenience, except for rare edge cases. +- Support for schema generation or manipulation: + Another thing that the author of this library does not believe to be worthwhile in an ORM library. + In real-world applications, you will need to manage the schema using versioned schema migrations. + Schemas generated by ORM libraries from type declarations cannot really offer this, especially once you get into stored functions, triggers and so on. -- cgit v1.2.3