1 files changed, 41 insertions, 0 deletions
diff --git a/oblast/README.md b/oblast/README.md
new file mode 100644
index 0000000..d4e3b73
--- /dev/null
+++ b/oblast/README.md
@@ -0,0 +1,41 @@
+<!--
+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/gg/oblast).
+
+## How to contribute
+
+Please refer to the [README on module level](https://pkg.go.dev/go.xyrillian.de/gg).
+
+## 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.
+
+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.
+
+The author realizes that this means that Oblast is technically only an OM library, not an ORM library. Sometimes, optimization means getting rid of on of th lttrs.