{"id":51162962,"url":"https://github.com/socigy-org/socigy.opensource.db","last_synced_at":"2026-06-26T16:00:33.403Z","repository":{"id":350963198,"uuid":"1113978717","full_name":"Socigy-org/Socigy.OpenSource.DB","owner":"Socigy-org","description":"Roslyn source-generator–powered ORM for Databases","archived":false,"fork":false,"pushed_at":"2026-06-26T10:24:02.000Z","size":749,"stargazers_count":5,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-26T12:10:52.949Z","etag":null,"topics":["csharp-library","database","database-helper","database-library","migration-tool","migrations","orm-library"],"latest_commit_sha":null,"homepage":"https://docs.socigy.com/database","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Socigy-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T18:18:57.000Z","updated_at":"2026-06-26T11:27:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Socigy-org/Socigy.OpenSource.DB","commit_stats":null,"previous_names":["wailedparsley36/socigy.opensource.db"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Socigy-org/Socigy.OpenSource.DB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Socigy-org%2FSocigy.OpenSource.DB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Socigy-org%2FSocigy.OpenSource.DB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Socigy-org%2FSocigy.OpenSource.DB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Socigy-org%2FSocigy.OpenSource.DB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Socigy-org","download_url":"https://codeload.github.com/Socigy-org/Socigy.OpenSource.DB/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Socigy-org%2FSocigy.OpenSource.DB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34823788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["csharp-library","database","database-helper","database-library","migration-tool","migrations","orm-library"],"created_at":"2026-06-26T16:00:19.295Z","updated_at":"2026-06-26T16:00:33.398Z","avatar_url":"https://github.com/Socigy-org.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Socigy.OpenSource.DB\n\n**A compile-time, AOT-friendly, multi-engine SQL data layer for .NET - zero boilerplate, fully typed.**\n\nA Roslyn incremental source generator that reads your annotated C# classes at build time and emits a fully typed data layer - INSERT, SELECT, UPDATE, DELETE, JOINs, set operations, and migrations - without a single line of boilerplate. The engine is pluggable; **PostgreSQL** is the currently supported target, with other engines on the way.\n\n[![NuGet](https://img.shields.io/nuget/v/Socigy.OpenSource.DB?logo=nuget\u0026label=NuGet)](https://nuget.org/packages/Socigy.OpenSource.DB)\n[![Downloads](https://img.shields.io/nuget/dt/Socigy.OpenSource.DB?logo=nuget\u0026label=Downloads)](https://nuget.org/packages/Socigy.OpenSource.DB)\n[![CI](https://img.shields.io/github/actions/workflow/status/Socigy-org/Socigy.OpenSource.DB/ci.yml?branch=master\u0026logo=github\u0026label=CI)](https://github.com/Socigy-org/Socigy.OpenSource.DB/actions/workflows/ci.yml)\n[![Stars](https://img.shields.io/github/stars/Socigy-org/Socigy.OpenSource.DB?logo=github)](https://github.com/Socigy-org/Socigy.OpenSource.DB)\n\u003cbr/\u003e\n[![.NET](https://img.shields.io/badge/.NET-10.0-512BD4?logo=dotnet\u0026logoColor=white)](https://dotnet.microsoft.com/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-supported-336791?logo=postgresql\u0026logoColor=white)](https://www.postgresql.org/)\n[![AOT](https://img.shields.io/badge/Native%20AOT-compatible-success)](https://learn.microsoft.com/dotnet/core/deploying/native-aot/)\n[![License](https://img.shields.io/badge/license-MPL--2.0-blue)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-socigy.com%2Fdatabase-2ea44f)](https://docs.socigy.com/database/)\n\n**[Full documentation → docs.socigy.com/database](https://docs.socigy.com/database/)**\n\n\u003c/div\u003e\n\n---\n\n## Installation\n\n```bash\ndotnet add package Socigy.OpenSource.DB\n```\n\nA single package reference installs the Core runtime, the Roslyn source generator, and the CLI migration tool.\n\n### Packages\n\n| Package                                                                                                                                                                                            | Description                                                                         |\n| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| [![Socigy.OpenSource.DB](https://img.shields.io/nuget/v/Socigy.OpenSource.DB?label=Socigy.OpenSource.DB)](https://nuget.org/packages/Socigy.OpenSource.DB)                                         | Core runtime, source generator, and CLI migration tool                              |\n| [![Socigy.OpenSource.DB.HashiCorp](https://img.shields.io/nuget/v/Socigy.OpenSource.DB.HashiCorp?label=Socigy.OpenSource.DB.HashiCorp)](https://nuget.org/packages/Socigy.OpenSource.DB.HashiCorp) | Optional HashiCorp Vault / OpenBao integration - field encryption and rotating DB credentials |\n\n```bash\n# Optional Vault integration\ndotnet add package Socigy.OpenSource.DB.HashiCorp\n```\n\n---\n\n## Quick start\n\n**1. Annotate a class**\n\n```csharp\nusing Socigy.OpenSource.DB.Attributes;\n\n[Table(\"users\")]\npublic partial class User\n{\n    [PrimaryKey, Default(DbDefaults.Guid.Random)]\n    public Guid Id { get; set; }\n\n    [StringLength(3, 50), Unique]\n    public string Username { get; set; }\n\n    [StringLength(5, 254), Unique]\n    public string Email { get; set; }\n\n    public string Status { get; set; } = \"active\";   // → DEFAULT 'active'\n\n    [Default(DbDefaults.Time.Now)]\n    public DateTime CreatedAt { get; set; }\n}\n```\n\n**2. Build - the generator emits all query methods**\n\n```bash\ndotnet build\n```\n\n**3. Use the generated methods**\n\n```csharp\n// INSERT\nvar user = new User { Username = \"alice\", Email = \"alice@example.com\" };\nawait user.Insert()\n    .WithConnection(conn)\n    .ExcludeAutoFields()        // let the DB fill Id and CreatedAt\n    .WithValuePropagation()     // write DB-generated values back to the object\n    .ExecuteAsync();\n\n// SELECT\nawait foreach (var u in User.Query(x =\u003e x.Status == \"active\")\n    .OrderBy(x =\u003e new object[] { x.CreatedAt })\n    .Limit(20)\n    .WithConnection(conn)\n    .ExecuteAsync())\n{\n    Console.WriteLine(u.Username);\n}\n\n// UPDATE\nuser.Email = \"newalice@example.com\";\nawait user.Update()\n    .WithConnection(conn)\n    .WithFields(x =\u003e new object[] { x.Email })\n    .ExecuteAsync();\n\n// DELETE\nawait user.Delete().WithConnection(conn).ExecuteAsync();\n```\n\n---\n\n## Features\n\n- **Zero boilerplate** - annotate once, every CRUD method is generated at build time\n- **Fully typed** - WHERE clauses, ORDER BY, and field selectors use C# expressions; no raw strings\n- **Migrations** - CLI tool analyses your compiled assembly and generates PostgreSQL DDL; a tracking table handles incremental applies\n- **JOINs** - `Join`, `LeftJoin`, `RightJoin`, `FullOuterJoin`, `NaturalJoin`, `CrossJoin`\n- **Set operations** - `Union`, `UnionAll`, `Intersect`, `IntersectAll`, `Except`, `ExceptAll`\n- **Flagged enums** - `[FlaggedEnum]` generates a junction table and typed flag helpers\n- **JSON columns** - `[JsonColumn]` and `[RawJsonColumn]` for JSONB with optional AOT-safe typed serialisation\n- **Procedure mapping** - write SQL in `.sql` files, get strongly-typed async wrappers at compile time\n- **Value convertors** - custom per-column read/write transformation via `IDbValueConvertor\u003cT\u003e`\n- **Field encryption** - `[Encrypted]` columns with pluggable encryptors, including optional [HashiCorp Vault](https://www.vaultproject.io/) / [OpenBao](https://openbao.org/) (KV-v2 keyring, Transit/envelope encryption) and rotating DB credentials\n- **Observability** - built-in OpenTelemetry instrumentation (`SocigyDbInstrumentation`) for queries and Vault token lifecycle\n- **AOT compatible** - no runtime reflection; safe to publish with `PublishAot=true`\n\n---\n\n## DI setup\n\nAdd `socigy.json` to your DB class library project root:\n\n```json\n{\n  \"database\": {\n    \"platform\": \"postgresql\",\n    \"databaseName\": \"MyDb\",\n    \"generateDbConnectionFactory\": true,\n    \"generateWebAppExtensions\": true\n  }\n}\n```\n\n`databaseName` is also the connection-string key and the physical database name. To keep a lowercase,\nPostgres-conventional name (e.g. `\"identity\"`) while generating clean C# identifiers, add an optional\n`\"contextName\": \"IdentityDb\"` — the generated surface becomes `IIdentityDb` / `AddIdentityDb()` while the\nconnection-string key and physical database stay `identity`.\n\nThe build generates `AddMyDb()` extension methods and registers `IDbConnectionFactory` and `IMigrationManager` in DI:\n\n```csharp\n// Program.cs\nbuilder.AddMyDb();\n\nvar app = builder.Build();\nawait app.EnsureLatestMyDbMigration();   // apply pending migrations on startup\n```\n\nConnection strings are read from `appsettings.json`:\n\n```json\n{\n  \"ConnectionStrings\": {\n    \"MyDb\": {\n      \"Default\": \"Host=localhost;Port=5432;Username=postgres;Password=secret\"\n    }\n  }\n}\n```\n\n---\n\n## Migrations\n\nRun the migration build configuration to generate DDL from your current model:\n\n```bash\ndotnet build -c DB_Migration\n```\n\nMigration files land in `Socigy/Migrations/`. Apply them at startup with `EnsureLatestMyDbMigration()` or manage them manually via `IMigrationManager.EnsureLatestVersion()`.\n\n---\n\n## Field encryption\n\nMark a column `[Encrypted]` to store it as `bytea`, encrypted on write and decrypted on read by the\nambient `IFieldEncryptor`. The ciphertext is authenticated and bound to its `table:column` context, so a\nvalue cannot be relocated to another column and still decrypt.\n\n```csharp\n[Table(\"users\")]\npublic partial class User\n{\n    [PrimaryKey, Default(DbDefaults.Guid.Random)] public Guid Id { get; set; }\n    [Encrypted] public string Ssn { get; set; }\n}\n```\n\n**Local key** — configure once at startup with a 32-byte key from your secret store:\n\n```csharp\nSocigyFieldEncryption.Configure(new AesFieldEncryptor(key)); // AES-256-CBC + HMAC-SHA256\n```\n\n**HashiCorp Vault / OpenBao** (`Socigy.OpenSource.DB.HashiCorp`) offers three modes. The envelope and\nEaaS modes use the Transit engine — enable it and create a key first:\n\n```bash\nvault secrets enable transit\nvault write -f transit/keys/socigy-db                 # envelope mode (non-derived)\nvault write transit/keys/socigy-eaas derived=true     # EaaS mode (binds the table:column context)\n```\n\n```csharp\n// 1) KV-direct — key lives in a Vault KV-v2 secret, loaded once; crypto is local.\nbuilder.Services.AddSocigyVaultEncryption(o =\u003e { o.Address = \"https://vault:8200\"; o.Token = \"…\"; });\n\n// 2) Data-key envelope (recommended) — a versioned keyring of Transit-wrapped DEKs. Crypto stays\n//    local; old rows stay readable across rotations because each value embeds its key id.\nbuilder.Services.AddSocigyVaultEnvelopeEncryption(o =\u003e\n{\n    o.Address = \"https://vault:8200\"; o.AppRoleId = \"…\"; o.AppRoleSecretId = \"…\";\n    o.TransitKeyName = \"socigy-db\";\n    o.EnableBackgroundRotation = true;          // optional; or call RotateAsync() manually\n});\n\n// 3) EaaS-direct — Vault encrypts/decrypts each field (a round-trip per field). For a few\n//    highly-sensitive columns only. Uses the derived key so the table:column context binds.\nbuilder.Services.AddSocigyVaultTransitEncryption(o =\u003e\n{\n    o.Address = \"https://vault:8200\"; o.Token = \"…\";\n    o.TransitKeyName = \"socigy-eaas\";   // the derived key created above\n    o.Profile = \"transit\";              // route only [Encrypted(Profile = \"transit\")] columns here\n});\n```\n\n\u003e **OpenBao** is supported as a drop-in for HashiCorp Vault — point the same options at your OpenBao\n\u003e address (its KV-v2 and Transit APIs are wire-compatible). The integration test suite passes against both.\n\n**Per-column profiles** — run one mode by default and route specific columns to another:\n\n```csharp\n[Encrypted] public string Email { get; set; }                    // default encryptor (e.g. envelope)\n[Encrypted(Profile = \"transit\")] public string Ssn { get; set; }  // EaaS-direct\n```\n\n**Key rotation** — with envelope mode old rows stay readable after a rotation, and any row your app\nre-saves migrates to the new key automatically. To proactively rewrite old rows (e.g. to retire a key\nversion), use the bulk re-encryptor — it works for generated, dynamic, and `[TableType]` tables:\n\n```csharp\nawait new FieldReencryptor()\n    .Add\u003cUser\u003e()\n    .AddDynamic\u003cEvent\u003e(\"events_2026_06\")     // dynamic / [TableType] tables bound to a runtime name\n    .RunAsync(connection);                    // batched, resumable; DryRun/Force via ReencryptOptions\n```\n\n---\n\n## Documentation\n\nFull reference covering every attribute, builder method, join variant, migration option, and DI pattern:\n\n**[docs.socigy.com/database](https://docs.socigy.com/database/)**\n\n| Section                                                                              | Topics                                                   |\n| ------------------------------------------------------------------------------------ | -------------------------------------------------------- |\n| [Getting started](https://docs.socigy.com/database/0.3.3/getting-started/quickstart) | Installation, project structure, `socigy.json`           |\n| [Defining models](https://docs.socigy.com/database/0.3.3/defining-models/tables)     | All attributes, column types, defaults, constraints      |\n| [Querying](https://docs.socigy.com/database/0.3.3/querying/select)                   | SELECT, INSERT, UPDATE, DELETE, JOINs, set operations    |\n| [Migrations](https://docs.socigy.com/database/0.3.3/migration/cli-tool)              | CLI tool, schema generation, applying, custom migrations |\n| [Advanced](https://docs.socigy.com/database/0.3.3/advanced/procedure-mapping)        | Procedure mapping, value convertors, Check DSL           |\n\n---\n\n## License\n\nMozilla Public License 2.0 (MPL-2.0) - see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocigy-org%2Fsocigy.opensource.db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsocigy-org%2Fsocigy.opensource.db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsocigy-org%2Fsocigy.opensource.db/lists"}