{"id":34231047,"url":"https://github.com/go-surreal/som","last_synced_at":"2026-03-10T00:06:09.820Z","repository":{"id":195373577,"uuid":"556963975","full_name":"go-surreal/som","owner":"go-surreal","description":"A type-safe SurrealDB object mapper \u0026 query builder for Go.","archived":false,"fork":false,"pushed_at":"2026-02-20T21:00:06.000Z","size":3310,"stargazers_count":28,"open_issues_count":27,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-21T02:19:43.878Z","etag":null,"topics":["codegen","database","generator","golang","graph","lib","library","orm","package","pkg","query-builder","sql","surrealdb"],"latest_commit_sha":null,"homepage":"https://go-surreal.gitbook.io/som","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-surreal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-10-24T21:05:12.000Z","updated_at":"2026-02-12T19:52:41.000Z","dependencies_parsed_at":"2023-10-16T11:23:38.235Z","dependency_job_id":"d6e73346-cb25-4099-bf49-674ee5ec1101","html_url":"https://github.com/go-surreal/som","commit_stats":null,"previous_names":["go-surreal/som","marcbinz/som","marcbinz/sdb"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/go-surreal/som","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-surreal%2Fsom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-surreal%2Fsom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-surreal%2Fsom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-surreal%2Fsom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-surreal","download_url":"https://codeload.github.com/go-surreal/som/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-surreal%2Fsom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29762181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-23T21:02:23.375Z","status":"ssl_error","status_checked_at":"2026-02-23T20:58:31.539Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codegen","database","generator","golang","graph","lib","library","orm","package","pkg","query-builder","sql","surrealdb"],"created_at":"2025-12-16T01:06:41.402Z","updated_at":"2026-03-10T00:06:09.815Z","avatar_url":"https://github.com/go-surreal.png","language":"Go","readme":"\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg width=\"400px\" src=\".github/branding/logo.png\" alt=\"logo\"\u003e\n    \u003ch3\u003eSOM - A SurrealDB object mapper \u0026 query builder for Go\u003c/h3\u003e\n\u003c/div\u003e\n\n\u003chr /\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://go.dev/doc/devel/release\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-1.25.7-informational\" alt=\"Go 1.25.7\"\u003e\u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://goreportcard.com/report/github.com/go-surreal/som\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/go-surreal/som\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://github.com/go-surreal/som/actions/workflows/main.yml\"\u003e\u003cimg src=\"https://github.com/go-surreal/som/actions/workflows/main.yml/badge.svg\" alt=\"Main\"\u003e\u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://github.com/go-surreal/som/actions/workflows/codeql.yml\"\u003e\u003cimg src=\"https://github.com/go-surreal/som/actions/workflows/codeql.yml/badge.svg\" alt=\"CodeQL\"\u003e\u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://codecov.io/gh/go-surreal/som\"\u003e\u003cimg src=\"https://codecov.io/gh/go-surreal/som/graph/badge.svg?token=FHSP3ZAKRC\" alt=\"Codecov\"/\u003e\u003c/a\u003e\n    \u0026nbsp;\n    \u003ca href=\"https://discord.gg/surrealdb\"\u003e\u003cimg src=\"https://img.shields.io/discord/902568124350599239?label=discord\u0026color=5a66f6\" alt=\"Discord\"\u003e\u003c/a\u003e\n    \u0026nbsp;\n    \u003cimg src=\"https://img.shields.io/github/contributors/marcbinz/som\" alt=\"Contributors\"\u003e\n\u003c/p\u003e\n\nSOM (SurrealDB object mapper) is an ORM and query builder for [SurrealDB](https://surrealdb.com/) with built-in model\nmapping and type-safe query operation generator. It provides an easy and sophisticated database access layer.\n\n## What is SurrealDB?\n\nSurrealDB is a cutting-edge database system that offers a SQL-style query language with real-time queries  \nand efficient related data retrieval. It supports both schema-full and schema-less data handling.\nWith its full graph database functionality, SurrealDB enables advanced querying and analysis by allowing\nrecords (or vertices) to be connected with edges, each with its own properties and metadata.\nThis facilitates multi-table, multi-depth document retrieval without complex JOINs, all within the database.\n\n*(Information extracted from the [official homepage](https://surrealdb.com))*.\n\n## Table of contents\n\n* [Getting started](#getting-started)\n  * [Disclaimer](#disclaimer)\n  * [Basic usage](#basic-usage)\n  * [Known limitations](#known-limitations)\n* [Development](#development)\n  * [Versioning](#versioning)\n  * [Compatibility](#compatibility)\n  * [Features](#features)\n* [How to contribute](#how-to-contribute)\n* [FAQ](#faq)\n* [Maintainers \u0026 Contributors](#maintainers--contributors)\n* [References](#references)\n\n## Getting started\n\n*Please note: This package is currently tested against version \n[3.0.2](https://surrealdb.com/releases#v3-0-2)\nof SurrealDB.*\n\n### Disclaimer\n\nThis library is currently considered **HIGHLY EXPERIMENTAL** and under heavy development.\n\nSom is in the stage of (very) early development. While the basic functionality should be working as expected,\nthere could be unknown and critical bugs. This could theoretically lead to your database and especially \nthe data within it to get broken. It is not yet recommended for production use, so please be careful!\n\nIf you still want to use it for production applications, we do not accept any liability for data loss \nor other kind of issues. You have been warned!\n\nFurthermore, it may lack specific features and edge cases you might expect from a fully-featured ORM and \nquery builder library. Feel free to submit feature requests or pull requests to add additional functionality\nto Som. We do ask you to please read our [Contributor Guide](CONTRIBUTING.md).\n\nAs long as this library is not considered stable, there will likely be significant and breaking changes to its API.\nSo please keep in mind, that any new updates might lead to required (manual) migrations or to take similar actions.\n\nBut still, please try it out and give us some feedback. We would highly appreciate it. Thank you! 🙏\n\n\u003e **Regarding the use of AI in this project:**\n\u003e\n\u003e AI coding assistants are a great help to speed up all the chores around the actual development of this library.\n\u003e However, please note that no code generated by AI tools is used within this project.\n\u003e All code is thoroughly added and reviewed by human developers to ensure quality and maintainability.\n\u003e On the other hand, AI tools are used to generate and maintain documentation files like this one, the GitBook documentation and similar files.\n\n### Basic usage\n\nGenerate the client code:\n\n```\ngo run github.com/go-surreal/som@latest \u003cinput_dir\u003e \u003coutput_dir\u003e\n```\n\n#### Example\n\nLet's say we have the following model at `\u003croot\u003e/model/user.go`:\n\n```go\npackage model\n\ntype User struct {\n    ID       string `som:\"id\"`\n    Username string `som:\"username\"`\n    Password string `som:\"password\"`\n    Email    string `som:\"email\"`\n}\n```\n\nIn order for it to be considered by the generator, it must embed `som.Node`:\n\n```go\npackage model\n\nimport \"github.com/go-surreal/som\"\n\ntype User struct {\n    som.Node\n    \n    // ID string `som:\"id\"` --\u003e provided by som!\n    \n    Username string `som:\"username\"`\n    Password string `som:\"password\"`\n    Email    string `som:\"email\"`\n}\n```\n\nNow, we can generate the client code:\n\n```\ngo run github.com/go-surreal/som/cmd/som@latest gen \u003cin_model_path\u003e \u003cout_gen_path\u003e\n\n// e.g.\n\ngo run github.com/go-surreal/som/cmd/som@latest gen \u003croot\u003e/model \u003croot\u003e/gen/som\n```\n\nWith the generated client, we can now perform operations on the database:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \n    \"\u003croot\u003e/gen/som\"\n    \"\u003croot\u003e/gen/som/filter\"\n    \"\u003croot\u003e/model\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    // create a new client\n    client, err := som.NewClient(ctx, som.Config{\n        Address:   \"ws://localhost:8000\",\n        Username:  \"root\",\n        Password:  \"root\",\n        Namespace: \"test\",\n        Database:  \"test\",\n    })\n    \n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    // initialize the model\n    user := \u0026model.User{\n        Username: \"test\",\n        Password: \"test\",\n        Email:    \"test@example.com\",\n    }\n    \n    // insert the user into the database\n    err = client.UserRepo().Create(ctx, user)\n    if err != nil {\n        log.Fatal(err)\n    }\n\t\t\n    // query the user by email\n    read, err := client.UserRepo().Query().\n        Where(\n            filter.User.Email.Equal(\"test@example.com\"),\n        ).\n        First(ctx)\n\n    if err != nil {\n        log.Fatal(err)\n    }\n\t\t\n    fmt.Println(read)\n}\n```\n\n### Known limitations\n\n### Unsupported native go types\n\nCurrently, the native go types `uint`, `uint64` and `uintptr` are not supported.\nReason for this is that working with very big integers is not yet fully working with the \ncurrent version of SurrealDB (as of writing: 1.4.2). This should be fixed in a future release of SurrealDB.\nAs soon as this is fixed, Som will support these types as well.\n\n## Overview\n\n### Supported data types\n\n#### Primitive types\n\n- [x] `string`\n- [x] `int`, `int8`, `int16`, `int32`, `int64`\n- [x] `uint`, `uint8`, `uint16`, `uint32`, `uint64`\n- [ ] `uintptr`\n- [x] `float32`, `float64`\n- [ ] `complex64`, `complex128`\n- [x] `bool`\n- [x] `rune`\n- [x] `byte`, `[]byte`\n- [x] `time.Time`\n- [x] `time.Duration`\n- [ ] `time.Location`\n- [x] `time.Weekday`\n- [x] `time.Month`\n- [ ] `big.Int`\n- [ ] `big.Float`\n- [x] `url.URL`\n- [ ] `net.IP`\n- [ ] `regexp.Regexp`\n- [x] Slice types of the above\n- [ ] `map[string]x` (where `x` is one of the types listed here or `any` with a mix of the listed types)\n\n\nFor all types above, the pointer version is supported as well.\n\n#### Special types\n\n- [x] `github.com/google/uuid.UUID`\n- [ ] `github.com/oklog/ulid.ULID`?\n\n#### Custom types\n\n- [x] `som.Enum`\n- [ ] `som.Password`\n- [ ] `som.Email`\n- [ ] `som.SemVer`\n- [ ] `som.HTML` (encode, sanitize)\n- [ ] `som.GeometryPoint`\n- [ ] `som.GeometryLine`\n- [ ] `som.GeometryPolygon`\n- [ ] `som.GeometryMultiPoint`\n- [ ] `som.GeometryMultiLine`\n- [ ] `som.GeometryMultiPolygon`\n- [ ] `som.GeometryCollection`\n- [ ] `som.JSON`?\n\n### Features\n\ntbd.\n\n## Development\n\n### Versioning\n\nIn the future this package will follow the [semantic versioning](https://semver.org) specification.\n\nUp until version 1.0 though, breaking changes might be introduced at any time (minor version bumps).\n\n### Compatibility\n\nThis go project makes heavy use of generics. As this feature has been introduced with go 1.18, that version is the \nearliest to be supported by this library.\n\nIn general, the two latest (minor) versions of go - and within those, only the latest patch - will be supported \nofficially. This means that older versions might still work, but could also break at any time, with any new \nrelease and without further notice.\n\nDeprecating an \"outdated\" go version does not yield a new major version of this library. There will be no support for \nolder versions whatsoever. This rather hard handling is intended, because it is the official handling for the go \nlanguage itself. For further information, please refer to the\n[official documentation](https://go.dev/doc/devel/release#policy) or [endoflife.date](https://endoflife.date/go).\n\n## How to contribute\n\n### Forking\n\n- to contribute please create a fork within your own namespace\n- after making your changes, create a pull request that will merge your state into upstream\n\n### Commits \u0026 pull requests\n\n- Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org) specification.\n- During development (within a feature branch) commits may have any naming whatsoever.\n- After a PR has been approved, it will be squashed and merged into `main`.\n- The final commit message must adhere to the specification mentioned above.\n- A GitHub Workflow will make sure that the PR title and description matches this specification.\n\n### Labels\n\n- there are some different labels for issues and pull requests (e.g. bug and fix)\n- the labels on pull requests resemble the conventional commits specification\n- the \"highest\" label should then be used for the final commit message (e.g. feat above fix, or fix above refactor)\n  - TODO: create exhaustive list of label order\n\n## FAQ\n\nYou can find a separate document for the FAQs [here](FAQ.md).\n\n## Maintainers \u0026 Contributors\n\nPlease take a look at the [MAINTAINERS.md](MAINTAINERS.md) file.\n\n## References\n\n- [Official SurrealDB documentation](https://surrealdb.com/docs)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-surreal%2Fsom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-surreal%2Fsom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-surreal%2Fsom/lists"}