YesSql: A Document Database Interface for Relational Databases

YesSql's Relational Foundation for CLR Documents

YesSql addresses a specific architectural tension: some .NET applications want to model and query documents as plain old CLR objects, while their organizations still depend on relational database servers. The project presents itself as a document database interface, not as a separate database server. It stores its data in an RDBMS and uses SQL underneath. The intended audience includes developers who need document access through the .NET ecosystem but also require database features such as transactions, replication, and reporting. The README also identifies organizations that have invested in SQL and have internal SQL expertise as a possible audience.

That boundary matters when evaluating YesSql. It should not be compared with MongoDB or RavenDB as though every document database has the same deployment model. YesSql changes how a .NET application defines, stores, and accesses documents. It does not replace the relational database underneath those operations. An application can therefore retain an RDBMS-centered operational environment while exposing document-shaped objects to application code.

The repository includes samples for full-text search, a web application, map/reduce usage, benchmarking, and a larger sample named `YesSql.Samples.Full`. Based on this layout, the examples cover more than a single minimal persistence path. However, the README does not provide enough detail to claim that the samples are exhaustive or suitable as production templates.

Documents, Index Tables, and Dapper Data Access

The storage model is based on a global `Document` table. Application document types are represented through plain CLR objects, while indexes are explicitly defined as custom classes. Each index receives its own relational table. A reduce index adds a bridge table so that one document can be related to multiple documents.

This design makes index persistence visible rather than leaving it entirely behind a database-specific abstraction. It also means that index declarations have a direct schema consequence. A change to an index class is not merely an in-memory query change; the documentation associates every index with a custom table. Teams adopting YesSql should therefore inspect how those tables are created and managed in the example applications and their target environments.

For database communication, the README identifies Dapper as the internal data access library. YesSql is consequently not only an object serializer over an opaque key-value store. Its architecture retains a relational boundary represented by SQL tables, custom index types, bridge tables for reduce operations, and Dapper-based communication with the database server.

The README states that map/reduce is supported and directs readers to `YesSql.Samples.Hi` and the tests. That confirms the capability, but the available project documentation does not describe the query API, serialization settings, batching behavior, schema migration policy, or exact table naming rules. Those omissions prevent a firm judgement about operational complexity.

Getting Started Through the Wiki and Samples

The README does not provide installation commands or a complete first-use code example. It directs new users to the YesSql wiki and to the repository's `samples` and `samples/YesSql.Samples.Hi` directories. Since no command is documented here, this review does not invent a package installation command, configuration file, connection string, or application bootstrap sequence.

A sensible first-use path based on the documented resources is to open the wiki for setup guidance, select the sample closest to the intended application type, and trace how that sample constructs YesSql access and stores CLR objects. The `YesSql.Samples.Web` entry is the most relevant starting point when the goal is a conventional ASP.NET application. Readers interested in full-text behavior can inspect `YesSql.Samples.FullText`. Readers evaluating the documented map/reduce support should begin with `YesSql.Samples.Hi`, since the README explicitly identifies it as the relevant example.

The expected result of this first inspection is an understanding of the required configuration, document registration path, index definitions, and RDBMS connection. The README says that builds and pull requests are tested against SQLite, PostgreSQL, SQL Server, and MySQL. That list indicates intended RDBMS coverage, but the document does not identify a current setup command or explain whether every sample supports every provider.

When RDBMS Storage Is the Right Trade-Off

YesSql makes the most sense when the application model and the operational database have conflicting requirements. Developers may prefer CLR documents and custom indexes for application-facing access, while the server team wants transactions, replication, reporting, established SQL practices, and existing relational expertise. The README presents this combination as the central reason to use the project.

The phrase "there is no magic involved, it's pure SQL" reflects a deliberate preference for visible relational behavior. The documented schema contains ordinary tables, including a global document table and one table per index. Reduce operations introduce another table as a bridge. This can make database inspection and reporting more approachable than with a storage engine whose internal structures are not described as application-level tables. It can also simplify alignment with an organization whose database tooling is built around RDBMS administration.

That advantage has a corresponding constraint. YesSql is useful precisely when the team values the RDBMS. If transactional operations, SQL reporting, replication, or existing SQL infrastructure do not matter, the additional abstraction offers little clear benefit. The README itself makes that boundary unusually clear, saying that developers who do not care about these restrictions will not benefit from YesSql. This is a useful warning against choosing a document interface merely because the word "document" appears in its description.

YesSql and Conventional Document Databases

The most relevant alternatives are not interchangeable at every layer. MongoDB and RavenDB are document databases in their own right, as the README acknowledges. YesSql instead defines a document database interface over an RDBMS and communicates with that server through Dapper. The difference is therefore architectural, not merely branding.

The README contrasts MongoDB by discussing applications that require transactional guarantees with a relational database interface. It contrasts RavenDB by stating that RavenDB is not free for most usages. The document does not discuss MongoDB or RavenDB deployment, query, indexing, licensing, or operational features beyond those points. Accordingly, this comparison should not be read as a comprehensive product evaluation.

A developer choosing between YesSql and a conventional document database should ask whether application data must remain inside a relational platform that the organization already operates. If that requirement is central, YesSql's custom index tables and global `Document` table provide a specific reason to evaluate it. If a standalone document database is the actual goal, the README offers no direct migration guide or compatibility details. That missing documentation makes YesSql harder to treat as a drop-in substitute.

Release History, Compatibility Checks, and Licensing

The repository is not archived, and its last push was on 2026-10-13. The release list includes `v6.0.0` from 2026-06-23, `v5.4.7` from 2025-10-07, and `v5.4.6` from 2025-08-07. The repository states that development and pull requests use the `main` branch, that the latest NuGet release is tagged on the releases page, and that `main` is also published automatically to MyGet.

YesSql therefore has visible recent repository activity and a major release available, but the README does not document a formal compatibility policy, supported .NET version matrix, provider-specific breaking changes, or an upgrade procedure. The presence of a major version is not enough to infer migration cost. Engineers should compare the release notes and package metadata for the versions used by their application. The documentation also does not explain how application databases should be upgraded when index definitions change.

The project is licensed under the MIT License. That is the only licensing fact established here. The license permits broad use subject to its terms, but this review does not provide legal advice or infer how the license interacts with a particular commercial service, database product, or organizational policy. License compatibility is simpler to assess at the file and release level than deployment compatibility, which still requires checking the RDBMS provider and schema management process.

Editorial conclusion

YesSql is appropriate for .NET teams that want document-oriented application models without giving up their relational database, transactions, replication, or reporting infrastructure. It is a poor fit for developers who do not need RDBMS-backed storage or who expect a turnkey standalone document database. Before adoption, check the wiki and sample apps for current configuration instructions, verify the generated schema and index behavior against the intended RDBMS, and confirm that the project's licensing and release history meet the application's requirements.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sebastienros/yessql on GitHub