go-surreal/som has 30 GitHub stars and 1 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 17:54 UTC. Last push 2026-11-12.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
A type-safe SurrealDB object mapper & query builder for Go.
DataREADME.md
Original
SOM - A SurrealDB object mapper & query builder for Go
SOM (SurrealDB object mapper) is an ORM and query builder for SurrealDB with built-in model mapping and type-safe query operation generator. It provides an easy and sophisticated database access layer.
What is SurrealDB?
SurrealDB is a cutting-edge database system that offers a SQL-style query language with real-time queries
and efficient related data retrieval. It supports both schema-full and schema-less data handling.
With its full graph database functionality, SurrealDB enables advanced querying and analysis by allowing
records (or vertices) to be connected with edges, each with its own properties and metadata.
This facilitates multi-table, multi-depth document retrieval without complex JOINs, all within the database.
(Information extracted from the official homepage).
Table of contents
Getting started
Please note: This package is currently tested against version 4.0.1 of SurrealDB.
Disclaimer
This library is currently considered HIGHLY EXPERIMENTAL and under heavy development.
Som is in the stage of (very) early development. While the basic functionality should be working as expected, there could be unknown and critical bugs. This could theoretically lead to your database and especially the data within it to get broken. It is not yet recommended for production use, so please be careful!
If you still want to use it for production applications, we do not accept any liability for data loss or other kind of issues. You have been warned!
Furthermore, it may lack specific features and edge cases you might expect from a fully-featured ORM and query builder library. Feel free to submit feature requests or pull requests to add additional functionality to Som. We do ask you to please read our Contributor Guide.
As long as this library is not considered stable, there will likely be significant and breaking changes to its API. So please keep in mind, that any new updates might lead to required (manual) migrations or to take similar actions.
But still, please try it out and give us some feedback. We would highly appreciate it. Thank you! 🙏
Regarding the use of AI in this project:
AI coding assistants are a great help to speed up all the chores around the actual development of this library. However, please note that no code generated by AI tools is used within this project. All code is thoroughly added and reviewed by human developers to ensure quality and maintainability. On the other hand, AI tools are used to generate and maintain documentation files like this one, the GitBook documentation and similar files.
Basic usage
Generate the client code:
go run github.com/go-surreal/som@latest <input_dir> <output_dir>
Example
Let's say we have the following model at <root>/model/user.go:
package model
type User struct {
ID string `som:"id"`
Username string `som:"username"`
Password string `som:"password"`
Email string `som:"email"`
}
In order for it to be considered by the generator, it must embed som.Node[T], where T is the
ID type (som.ULID, som.UUID, som.Rand, som.String or a custom key struct):
package model
import "<root>/gen/som"
type User struct {
som.Node[som.ULID]
// ID string --> provided by som!
Username string
Password string
Email string
}
Now, we can generate the client code:
go run github.com/go-surreal/som@latest -i <in_model_path> -o <out_gen_path>
// e.g.
go run github.com/go-surreal/som@latest -i ./model
With the generated client, we can now perform operations on the database:
package main
import (
"context"
"log"
"<root>/gen/som/filter"
"<root>/gen/som/repo"
"<root>/model"
)
func main() {
ctx := context.Background()
// create a new client
client, err := repo.NewClient(ctx, repo.Config{
Address: "ws://localhost:8000",
Username: "root",
Password: "root",
Namespace: "test",
Database: "test",
})
if err != nil {
log.Fatal(err)
}
defer client.Close()
// apply the generated schema
if err := client.ApplySchema(ctx); err != nil {
log.Fatal(err)
}
// initialize the model
user := &model.User{
Username: "test",
Password: "test",
Email: "[email protected]",
}
// insert the user into the database
err = client.UserRepo().Create(ctx, user)
if err != nil {
log.Fatal(err)
}
// query the user by email
read, err := client.UserRepo().Query().
Where(
filter.User.Email.Equal("[email protected]"),
).
First(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(read)
}
Known limitations
Unsupported native go types
Currently, the native go types uint, uint64 and uintptr are not supported.
Reason for this is that working with very big integers is not yet fully working with the
current version of SurrealDB (as of writing: 1.4.2). This should be fixed in a future release of SurrealDB.
As soon as this is fixed, Som will support these types as well.
Overview
Supported data types
Primitive types
-
string -
int,int8,int16,int32,int64 -
uint,uint8,uint16,uint32,uint64 -
uintptr -
float32,float64 -
complex64,complex128 -
bool -
rune -
byte,[]byte -
time.Time -
time.Duration -
time.Location -
time.Weekday -
time.Month -
big.Int -
big.Float -
url.URL -
net.IP -
regexp.Regexp - Slice types of the above
-
map[string]x(wherexis one of the types listed here oranywith a mix of the listed types)
For all types above, the pointer version is supported as well.
Special types
-
github.com/google/uuid.UUID -
github.com/oklog/ulid.ULID?
Custom types
-
som.Enum -
som.Password -
som.Email -
som.SemVer -
som.HTML(encode, sanitize) -
som.GeometryPoint -
som.GeometryLine -
som.GeometryPolygon -
som.GeometryMultiPoint -
som.GeometryMultiLine -
som.GeometryMultiPolygon -
som.GeometryCollection -
som.JSON?
Features
tbd.
Development
Versioning
In the future this package will follow the semantic versioning specification.
Up until version 1.0 though, breaking changes might be introduced at any time (minor version bumps).
Compatibility
This go project makes heavy use of generics, iterators and generic methods. During this phase of the project, only the latest version of go is supported - currently go 1.27.1. Older versions might still work, but could also break at any time, with any new release and without further notice.
Once the project reaches a stable release, this will be relaxed to the two latest (minor) versions of go - and within those, only the latest patch.
Deprecating an "outdated" go version does not yield a new major version of this library. There will be no support for older versions whatsoever. This rather hard handling is intended, because it is the official handling for the go language itself. For further information, please refer to the official documentation or endoflife.date.
How to contribute
Forking
- to contribute please create a fork within your own namespace
- after making your changes, create a pull request that will merge your state into upstream
Commits & pull requests
- Commit messages follow the Conventional Commits specification.
- During development (within a feature branch) commits may have any naming whatsoever.
- After a PR has been approved, it will be squashed and merged into
main. - The final commit message must adhere to the specification mentioned above.
- A GitHub Workflow will make sure that the PR title and description matches this specification.
Labels
- there are some different labels for issues and pull requests (e.g. bug and fix)
- the labels on pull requests resemble the conventional commits specification
- the "highest" label should then be used for the final commit message (e.g. feat above fix, or fix above refactor)
- TODO: create exhaustive list of label order
FAQ
You can find a separate document for the FAQs here.
Maintainers & Contributors
Please take a look at the MAINTAINERS.md file.