1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
|
<!--
SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
SPDX-License-Identifier: Apache-2.0
-->
# Oblast
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.
## How to use
Please refer to the [package documentation](https://pkg.go.dev/go.xyrillian.de/oblast).
## How to contribute
The primary repository at <https://git.xyrillian.de/go-oblast> is only writable by the maintainer.
To contribute, you may use `git format-patch` in the usual manner and send patches to the maintainer's mail address (which can be found in the copyright notice headers on each file).
Alternatively, if you have a GitHub account, you can submit issues and pull requests at the mirror repository <https://github.com/majewsky/go-oblast>.
## 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 few library dependencies as possible.
As a surprising consequence, this set of priorities forced this library 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, where unpredictable delays make a structured cancellation facility vital.
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 during OLAP workloads.
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.
|
