Ninja.Sharp.OpenSODA.Driver.Sql.Native
1.0.0
dotnet add package Ninja.Sharp.OpenSODA.Driver.Sql.Native --version 1.0.0
NuGet\Install-Package Ninja.Sharp.OpenSODA.Driver.Sql.Native -Version 1.0.0
<PackageReference Include="Ninja.Sharp.OpenSODA.Driver.Sql.Native" Version="1.0.0" />
paket add Ninja.Sharp.OpenSODA.Driver.Sql.Native --version 1.0.0
#r "nuget: Ninja.Sharp.OpenSODA.Driver.Sql.Native, 1.0.0"
// Install Ninja.Sharp.OpenSODA.Driver.Sql.Native as a Cake Addin #addin nuget:?package=Ninja.Sharp.OpenSODA.Driver.Sql.Native&version=1.0.0 // Install Ninja.Sharp.OpenSODA.Driver.Sql.Native as a Cake Tool #tool nuget:?package=Ninja.Sharp.OpenSODA.Driver.Sql.Native&version=1.0.0
OpenSODA - a .Net driver for Oracle SODA
Release Notes
First release has been created!
Packages
Package | NuGet Stable |
---|---|
OpenSODA | |
OpenSODA.Driver.Rest | |
OpenSODA.Driver.Sql.Native | |
OpenSODA.Driver.Sql.Qbe |
Package Purposes:
- OpenSODA
- The core library
- OpenSODA.Driver.Rest
- Extension handlers for SODA Rest APIs
- OpenSODA.Driver.Sql.Native
- Extension handlers for SODA using Oracle Sql providers
- OpenSODA.Driver.Sql.Qbe
- Extension handlers for SODA using Oracle drivers
Features
OpenSODA is a NuGet library that you can use to connect and manage entities provided by Oracle SODA (Simple Oracle Document Access). The library provides simple and efficient methods for saving, retrieveing and filtering your entities, with support for both synchronous and asynchronous data access.
It provides multiple integration to SODA instances:
- via REST APIs: you can use Oracle Rest APIs to query your Oracle SODA installation.
- via QBE: you can filter documents via query-by-example (QBE). This is the most efficient way to connect to SODA. However, it does not natively support serch via textcontains and search in document arrays
- via SQL: you can always query your SODA database through SQL instructions
Configuration
OpenSODA can be configured manually or via appsettings.json. Configuration differs for Rest and Sql implementation.
If you're using Rest APIs, then
{
"Soda": {
"Host": "10.10.10.10",
"Username": "Username",
"Password": "Password",
"Schema": "Schema",
"IsSecured": true,
"Port": 8080,
"ServiceName": "ServiceName"
}
}
otherwise, if you're using SQL (both native or QBE)
{
"Soda": {
"Host": "10.10.10.10",
"Username": "Username",
"Password": "Password",
"Schema": "Schema",
"Port": 1521,
"ServiceName": "ServiceName"
}
}
Choose and add a provider
OpenSODA manages for you a simple implementation (IDocumentDbProvider) you can use to perform your queries. To inject a different implementation, you just have to add to your services the desired one
services
//.AddOracleSodaRestServices(configuration)
//.AddOracleSodaSqlNativeServices(configuration)
.AddOracleSodaSqlQbeServices(configuration)
.BuildServiceProvider();
- AddOracleSodaRestServices: adds an implementation of IDocumentDbProvider that uses Rest APIs. You'll need the OpenSODA.Driver.Rest package to inject this one.
- AddOracleSodaSqlNativeServices: adds an implementation of IDocumentDbProvider that will perform queries in a SQL-like manner. You'll need OpenSODA.Driver.Sql.Native package to inject this one. we suggest adding a global index to your Oracle SODA database prior to using this implementation
- AddOracleSodaSqlQbeServices: adds an implementation of IDocumentDbProvider that will perform queries using Oracle SODA query-by-example (QBE). You'll need the OpenSODA.Driver.Sql.QBE package to inject this one.
Whichever package you choose, the provided methods are the same, so feel free to change the provider and verify which one is the best for your use-case.
Creating a collection
Before adding data to your database, you have to create a collection. A document collection contains documents. A SODA collection is analogous to an Oracle Database table or view.
To create a collection, you have two ways:
- you can provide the collection name
await sodaProvider.CreateCollectionIfNotExistsAsync("myCollection");
- or you can annotate an item with CollectionAttribute. The name provided in the attribute will be the collection name
[Collection("myCollection")]
internal class TestObject
{
public string One { get; set; } = string.Empty;
public string Two { get; set; } = string.Empty;
public string Three { get; set; } = string.Empty;
}
await sodaProvider.CreateCollectionIfNotExistsAsync<TestObject>();
We suggest you use the former method. Items you're going to persist must have the Collection attribute in order to be saved.
Insert an element
To add an element to a collection, first you need to annotate the class item with the Collection attribute
[Collection("myCollection")]
internal class TestObject
{
public string One { get; set; } = string.Empty;
public string Two { get; set; } = string.Empty;
public string Three { get; set; } = string.Empty;
}
If you do not provide a collection name, and you do not annotate your model, the library will use the class name as collection.
Then, you can just
private readonly IDocumentDbProvider sodaProvider = sodaProvider;
public async Task DoStuff()
{
Item<TestObject> item = await sodaProvider.UpsertAsync(new TestObject { One = value });
}
When you add an item, you will get your item back with some additional information added by SODA, such as the ID and the creation date. The retrieve task will use the provided ID.
Retrieve an element
private readonly IDocumentDbProvider sodaProvider = sodaProvider;
public async Task DoStuff()
{
Item<TestObject> item = await sodaProvider.UpsertAsync(new TestObject { One = value });
item = await sodaProvider.RetrieveAsync<TestObject>(item.Id);
}
Retrieve data
private readonly IDocumentDbProvider sodaProvider = sodaProvider;
public async Task DoStuff()
{
var results = await sodaProvider.ListAsync<TestObject>(new Page
{
ItemsPerPage = 10,
PageNumber = 1,
Ordering = Ordering.Descending,
OrderingPath = nameof(TestObject.One),
});
}
Delete data
private readonly IDocumentDbProvider sodaProvider = sodaProvider;
public async Task DoStuff()
{
Item<TestObject> item = await sodaProvider.UpsertAsync(new TestObject { One = value });
await sodaProvider.DeleteAsync<TestObject>(item.Id);
}
Filtering
To query your database, we provide a constructible query system using operands and data types.
private readonly IDocumentDbProvider sodaProvider = sodaProvider;
public async Task DoStuff()
{
Query query = new();
query.With(new And()
.With(new OString(nameof(TestObject.One), item.Value.One))
.With(new OString(nameof(TestObject.Two), item.Value.Two))
);
var results = await sodaProvider.FilterAsync<TestObject>(query);
}
The current available operands are
- and
- not
- or
The current available primitives are
- datetime
- int
- string
- upperString (Oracle SODA is case sensitive)
More operands will be released in the future.
Limitations
Some queries could be highly inefficient: often SODA will perform a full table scan to retrieve some data. We suggest to manually add a global index if you're using Sql.Native provider, and to add partitioning and cluster indexes if you're using Sql.QBE.
Contributing
Thank you for considering to help out with the source code! If you'd like to contribute, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base.
Getting started with Git and GitHub
- Setting up Git for Windows and connecting to GitHub
- Forking a GitHub repository
- The simple guide to GIT guide
- Open an issue if you encounter a bug or have a suggestion for improvements/features
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Microsoft.Extensions.Configuration.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Configuration.Binder (>= 8.0.2)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.1)
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.1)
- Ninja.Sharp.OpenSODA (>= 1.0.0)
- Oracle.ManagedDataAccess.Core (>= 23.5.1)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Ninja.Sharp.OpenSODA.Driver.Sql.Native:
Package | Downloads |
---|---|
Ninja.Sharp.OpenSODA.Driver.Sql.Qbe
Sql QBE driver for OpenSODA |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
1.0.0 | 125 | 8/22/2024 |
0.0.1-alpha | 143 | 4/17/2024 |