Skip to content

Commit f6afd55

Browse files
author
MPCoreDeveloper
committed
fix: Add NuGet-compatible README without HTML tags
- Created README_NUGET.md without div/center HTML tags - Updated SharpCoreDB.csproj to use README_NUGET.md for NuGet package - Preserved original README.md for GitHub with HTML styling - NuGet.org will now render package README correctly - Added docs/README_NUGET_COMPATIBILITY_FIX.md with full explanation Fixes: NuGet.org display issues with HTML tags
1 parent a0fa9cd commit f6afd55

File tree

3 files changed

+402
-4
lines changed

3 files changed

+402
-4
lines changed

‎docs/README_NUGET_COMPATIBILITY_FIX.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# README NuGet Compatibility Fix - v1.1.1
2+
3+
## ✅ Probleem Opgelost
4+
5+
NuGet.org heeft beperkte HTML support en kan problemen hebben met `<div>` tags, `<center>` tags en andere HTML elementen. Deze zijn nu verwijderd voor de NuGet package.
6+
7+
## 📋 Uitgevoerde Wijzigingen
8+
9+
### 1. **Nieuw Bestand: `src/SharpCoreDB/README_NUGET.md`**
10+
- ✅ Geen HTML tags (`<div>`, `<center>`, etc.)
11+
- ✅ Clickable badges vervangen door display-only badges
12+
- ✅ Alle content behouden, alleen opmaak aangepast
13+
- ✅ Pure Markdown syntax die NuGet.org goed rendert
14+
15+
### 2. **`src/SharpCoreDB/SharpCoreDB.csproj`**
16+
- ✅ `<PackageReadmeFile>` gewijzigd van `README.md` naar `README_NUGET.md`
17+
- ✅ `<ItemGroup>` updated om `README_NUGET.md` te packagen
18+
19+
### 3. **Root `README.md`**
20+
- ✅ Blijft ongewijzigd met alle HTML/CSS voor mooie GitHub weergave
21+
- ✅ Behouden voor GitHub repository
22+
23+
## 🔍 Verschillen tussen Versies
24+
25+
### GitHub Version (`README.md`)
26+
```markdown
27+
<div align="center">
28+
<img src="..." width="200"/>
29+
# SharpCoreDB
30+
[![Badge](url)](link) <!-- Clickable -->
31+
</div>
32+
```
33+
34+
### NuGet Version (`README_NUGET.md`)
35+
```markdown
36+
# SharpCoreDB
37+
38+
**High-Performance Embedded Database for .NET 10**
39+
40+
![Badge](url) <!-- Display only, niet clickable -->
41+
```
42+
43+
## 📦 Package Verificatie
44+
45+
### Test Package Gemaakt
46+
```
47+
✅ SharpCoreDB.1.1.1.nupkg
48+
Location: ./test-package/
49+
```
50+
51+
### Inhoud Verificatie
52+
- ✅ `README_NUGET.md` is opgenomen in package
53+
- ✅ NuGet.org zal de README correct renderen
54+
- ✅ Geen HTML parsing errors meer
55+
56+
## 🎯 Voordelen
57+
58+
### Voor NuGet.org
59+
1. ✅ **Correcte Rendering**: Geen rare `<div>` tags meer zichtbaar
60+
2. ✅ **Clean Layout**: Professionele weergave zonder HTML artifacts
61+
3. ✅ **Compatibility**: Werkt met alle NuGet.org markdown engines
62+
63+
### Voor GitHub
64+
1. ✅ **Mooie Badges**: Centered logo, clickable badges behouden
65+
2. ✅ **HTML Styling**: Alle visuele verbeteringen blijven werken
66+
3. ✅ **Geen Impact**: Repository README blijft ongewijzigd
67+
68+
## 📝 Belangrijke Markdown Syntax Verschillen
69+
70+
### ✅ NuGet Compatible
71+
```markdown
72+
# Heading
73+
**Bold Text**
74+
![Badge](url) # Display badge
75+
[Link](url) # Regular link
76+
| Table | Header | # Tables
77+
```
78+
79+
### ❌ NuGet Incompatible (vermeden in README_NUGET.md)
80+
```html
81+
<div align="center"> <!-- HTML tags -->
82+
<center> <!-- Deprecated HTML -->
83+
[![Badge](img)](link) <!-- Clickable badge images -->
84+
<style> <!-- CSS -->
85+
```
86+
87+
## 🚀 Publicatie Workflow
88+
89+
### Build Package
90+
```bash
91+
dotnet pack src/SharpCoreDB/SharpCoreDB.csproj -c Release -o ./artifacts
92+
```
93+
94+
### Verify Contents
95+
```bash
96+
# Extract .nupkg (it's a zip file)
97+
Expand-Archive artifacts/SharpCoreDB.1.1.1.nupkg -DestinationPath temp
98+
# Check README_NUGET.md is present
99+
Get-Content temp/README_NUGET.md
100+
```
101+
102+
### Publish to NuGet
103+
```bash
104+
dotnet nuget push artifacts/SharpCoreDB.1.1.1.nupkg \
105+
--api-key YOUR_KEY \
106+
--source https://api.nuget.org/v3/index.json
107+
```
108+
109+
## 🔗 Links
110+
111+
- **NuGet Package**: https://www.nuget.org/packages/SharpCoreDB/1.1.1
112+
- **GitHub Repo**: https://github.com/MPCoreDeveloper/SharpCoreDB
113+
- **Package README**: Gebruikt nu `README_NUGET.md`
114+
- **Repo README**: Gebruikt `README.md` (met HTML)
115+
116+
## ✅ Checklist voor Toekomstige Updates
117+
118+
Bij het updaten van README content:
119+
120+
- [ ] Update `README.md` (GitHub version) met HTML/badges
121+
- [ ] Update `README_NUGET.md` (NuGet version) zonder HTML
122+
- [ ] Controleer dat beide versies dezelfde informatie bevatten
123+
- [ ] Test NuGet package rendering op https://www.nuget.org/packages/SharpCoreDB/
124+
125+
## 🎓 Best Practices
126+
127+
### Voor GitHub README
128+
- ✅ Gebruik HTML voor betere styling
129+
- ✅ Clickable badge links
130+
- ✅ Centered content met `<div align="center">`
131+
- ✅ Custom CSS als nodig
132+
133+
### Voor NuGet README
134+
- ✅ Pure Markdown syntax only
135+
- ✅ No HTML tags (behalve `<img>` voor badges)
136+
- ✅ Simple badge displays (niet clickable)
137+
- ✅ Focus op functionaliteit, niet styling
138+
139+
## 📊 Impact Analyse
140+
141+
### Geen Breaking Changes
142+
- ✅ Bestaande gebruikers zien geen verschil
143+
- ✅ GitHub repository ongewijzigd
144+
- ✅ NuGet package heeft nu correcte README
145+
- ✅ Alle links blijven werken
146+
147+
### Verbeteringen
148+
- ✅ **NuGet.org**: Professionele, clean weergave
149+
- ✅ **User Experience**: Geen rare HTML tags meer
150+
- ✅ **Maintainability**: Twee duidelijk gescheiden versies
151+
152+
---
153+
154+
**Datum**: February 8, 2026
155+
**Versie**: 1.1.1
156+
**Status**: ✅ Geïmplementeerd en geverifieerd

‎src/SharpCoreDB/README_NUGET.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
# SharpCoreDB
2+
3+
**High-Performance Embedded Database for .NET 10**
4+
5+
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) ![.NET](https://img.shields.io/badge/.NET-10.0-blue.svg) ![NuGet](https://img.shields.io/badge/NuGet-1.1.1-blue.svg) ![Build](https://img.shields.io/badge/Build-✅_Passing-brightgreen.svg) ![Tests](https://img.shields.io/badge/Tests-772_Passing-brightgreen.svg)
6+
7+
---
8+
9+
## 📌 Current Status (February 2026)
10+
11+
### ✅ Version 1.1.1 Released - Localization Fix + API Cleanup
12+
13+
**Latest Release**: v1.1.1 (February 2026)
14+
15+
#### 🐛 Bug Fixes
16+
- **Critical**: Fixed localization bug affecting date/time formatting in non-English cultures
17+
- **Compatibility**: Resolved culture-dependent parsing issues (decimal separators, date formats)
18+
- **Portability**: Database files now fully portable across different regional settings
19+
20+
#### 🔄 API Improvements
21+
- **Deprecated Methods**: Added `[Obsolete]` attributes to legacy sync methods
22+
- **Migration Path**: Clear upgrade guidance to async patterns (see Quickstart below)
23+
- **Breaking Changes**: None - full backward compatibility maintained
24+
25+
#### 📦 Quick Install
26+
```bash
27+
dotnet add package SharpCoreDB --version 1.1.1
28+
```
29+
30+
---
31+
32+
### ✅ All Phases Complete — Phases 1-8 + DDL Extensions
33+
34+
| Area | Status |
35+
|------|--------|
36+
| **Phases 1-7** (Core → Query Optimization) | ✅ Complete |
37+
| **Phase 8** (Time-Series: compression, buckets, downsampling) | ✅ Complete |
38+
| **Phase 1.3** (Stored Procedures, Views) | ✅ Complete |
39+
| **Phase 1.4** (Triggers) | ✅ Complete |
40+
| **Build** | ✅ 0 errors |
41+
| **Tests** | ✅ 772 passing, 0 failures |
42+
| **Production LOC** | ~77,700 |
43+
44+
**Full documentation**: [https://github.com/MPCoreDeveloper/SharpCoreDB](https://github.com/MPCoreDeveloper/SharpCoreDB)
45+
46+
---
47+
48+
A high-performance, encrypted, embedded database engine for .NET 10 with **B-tree indexes**, **SIMD-accelerated analytics**, and **unlimited row storage**. Pure .NET implementation with enterprise-grade encryption and world-class analytics performance. **Beats SQLite AND LiteDB on INSERT!** 🏆
49+
50+
- **License**: MIT
51+
- **Platform**: .NET 10, C# 14
52+
- **Status**: ✅ **Production Ready — All Phases (1-8) + DDL Extensions Complete**
53+
- **Encryption**: AES-256-GCM at rest (**0% overhead, sometimes faster!** ✅)
54+
- **Analytics**: **28,660x faster** than LiteDB with SIMD vectorization ✅
55+
- **Analytics**: **682x faster** than SQLite with SIMD vectorization ✅
56+
- **INSERT**: **43% faster** than SQLite, **44% faster** than LiteDB! ✅
57+
- **SELECT**: **2.3x faster** than LiteDB for full table scans ✅
58+
- **UPDATE**: **5.4x faster** Single-File mode with batch coalescing ✅
59+
- **B-tree Indexes**: O(log n + k) range scans, ORDER BY, BETWEEN support ✅
60+
61+
---
62+
63+
## 🚀 Quickstart
64+
65+
Install the latest version:
66+
67+
```bash
68+
# Install SharpCoreDB v1.1.1
69+
dotnet add package SharpCoreDB --version 1.1.1
70+
71+
# Or use wildcard for latest
72+
dotnet add package SharpCoreDB
73+
```
74+
75+
Use (Async API - Recommended):
76+
77+
```csharp
78+
using Microsoft.Extensions.DependencyInjection;
79+
using SharpCoreDB;
80+
81+
var services = new ServiceCollection();
82+
services.AddSharpCoreDB();
83+
var provider = services.BuildServiceProvider();
84+
var factory = provider.GetRequiredService<DatabaseFactory>();
85+
86+
using var db = factory.Create("./app_db", "StrongPassword!");
87+
88+
// Create table with B-tree index
89+
await db.ExecuteSQLAsync("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)");
90+
await db.ExecuteSQLAsync("CREATE INDEX idx_age ON users(age) USING BTREE");
91+
92+
// Fast inserts with async API (recommended)
93+
await db.ExecuteSQLAsync("INSERT INTO users VALUES (1, 'Alice', 30)");
94+
95+
// Fast queries with async batch API
96+
var rows = await db.ExecuteQueryAsync("SELECT * FROM users WHERE age > 25");
97+
98+
// Support for large data (>256KB)
99+
var largeData = new byte[10_000_000]; // 10MB
100+
await db.ExecuteSQLAsync("INSERT INTO files VALUES (1, @data)");
101+
```
102+
103+
> ⚠️ **API Migration Notice (v1.1.1)**: Legacy synchronous methods (`ExecuteSQL`, `ExecuteQuery`, `Flush`, `ForceSave`) are marked as `[Obsolete]`. Please migrate to async methods (`ExecuteSQLAsync`, `ExecuteQueryAsync`, `FlushAsync`, `ForceSaveAsync`) for better performance, cancellation support, and culture-independent behavior.
104+
105+
---
106+
107+
## ⭐ Key Features
108+
109+
### ⚡ Performance Excellence - Beats SQLite AND LiteDB! 🏆
110+
111+
- **SIMD Analytics**: **28,660x faster** aggregations than LiteDB (1.08µs vs 30.9ms)
112+
- **SIMD Analytics**: **682x faster** than SQLite (1.08µs vs 737µs)
113+
- **INSERT Operations**: **43% faster** than SQLite (3.68ms vs 5.70ms) ✅
114+
- **INSERT Operations**: **44% faster** than LiteDB (3.68ms vs 6.51ms) ✅
115+
- **SELECT Queries**: **2.3x faster** than LiteDB for full table scans
116+
- **UPDATE Operations**: **5.4x faster** Single-File mode (60ms vs 325ms) ✅
117+
- **UPDATE Memory**: **280x less** allocations (1.9MB vs 540MB) ✅
118+
- **AVX-512/AVX2/SSE2**: Hardware-accelerated analytics with SIMD vectorization
119+
- **NativeAOT-Ready**: Zero reflection, zero dynamic dispatch, aggressive inlining
120+
- **Memory Efficient**: **52x less memory** than LiteDB for SELECT operations
121+
122+
### 🔒 Enterprise Security
123+
124+
- **Native AES-256-GCM**: Hardware-accelerated encryption with **0% overhead (or faster!)**
125+
- **At-Rest Encryption**: All data encrypted on disk
126+
- **Zero Configuration**: Automatic key management
127+
- **GDPR/HIPAA Compliant**: Enterprise-grade security
128+
129+
### 🗄️ Row Overflow Storage
130+
131+
- ✅ **SCDB Phase 6 Complete**: No arbitrary size limits (256TB NTFS)
132+
- **3-tier auto-selection**: Inline (4KB) / Overflow (256KB) / FileStream (∞)
133+
- **Orphan detection** and cleanup tooling
134+
- **Production quality** - SHA-256 checksums, atomic operations ✅
135+
136+
### 🏗️ Modern Architecture
137+
138+
- **Pure .NET**: No P/Invoke dependencies, fully managed code
139+
- **Multiple Storage Engines**: PageBased (OLTP), Columnar (Analytics), AppendOnly (Logging), SCDB (Block-based)
140+
- **Dual Index Types**: Hash indexes (O(1) point lookups), B-tree indexes (O(log n) range queries)
141+
- **Crash Recovery**: REDO-only recovery with WAL
142+
- **Async/Await**: First-class async support throughout
143+
- **DI Integration**: Native Dependency Injection
144+
145+
### 🗃️ SQL Support
146+
147+
- **DDL**: CREATE TABLE, DROP TABLE, ALTER TABLE, CREATE INDEX, DROP INDEX
148+
- **DDL**: CREATE/DROP PROCEDURE, CREATE/DROP VIEW, CREATE/DROP TRIGGER
149+
- **DML**: INSERT, SELECT, UPDATE, DELETE, INSERT BATCH, EXEC
150+
- **Queries**: WHERE, ORDER BY, LIMIT, OFFSET, BETWEEN
151+
- **Aggregates**: COUNT, SUM, AVG, MIN, MAX, GROUP BY, HAVING
152+
- **JOINs**: ✅ **INNER, LEFT, RIGHT, FULL OUTER, CROSS**
153+
- **Subqueries**: ✅ **WHERE, FROM, SELECT, IN, EXISTS, Correlated**
154+
- **Stored Procedures**: ✅ **CREATE PROCEDURE, EXEC with IN/OUT/INOUT parameters**
155+
- **Views**: ✅ **CREATE VIEW, CREATE MATERIALIZED VIEW**
156+
- **Triggers**: ✅ **BEFORE/AFTER INSERT/UPDATE/DELETE with NEW/OLD binding**
157+
- **Advanced**: Complex expressions, multi-table queries, query plan caching
158+
159+
## 🧭 RDBMS Feature Status
160+
161+
| Feature | Status | Details |
162+
|---------|--------|---------|
163+
| Stored Procedures | ✅ Complete | CREATE/DROP PROCEDURE, EXEC with IN/OUT/INOUT parameters |
164+
| Views | ✅ Complete | CREATE VIEW, CREATE MATERIALIZED VIEW, DROP VIEW |
165+
| Triggers | ✅ Complete | BEFORE/AFTER INSERT/UPDATE/DELETE, NEW/OLD binding |
166+
| Time-Series | ✅ Complete | Gorilla, Delta-of-Delta, XOR codecs, Buckets & Downsampling |
167+
| B-tree Indexes | ✅ Complete | Range queries, ORDER BY, BETWEEN, composite indexes |
168+
| JOINs | ✅ Complete | INNER, LEFT, RIGHT, FULL OUTER, CROSS joins |
169+
| Subqueries | ✅ Complete | Correlated, IN, EXISTS, scalar subqueries |
170+
| Aggregates | ✅ Complete | COUNT, SUM, AVG, MIN, MAX, GROUP BY, HAVING |
171+
172+
---
173+
174+
## ⏱️ Time-Series (Phase 8) Features
175+
176+
SharpCoreDB includes **production-grade time-series support** with industry-standard compression:
177+
178+
### Compression Codecs
179+
- **Gorilla Codec**: XOR-based floating-point compression (~80% space savings)
180+
- **Delta-of-Delta Codec**: Integer timestamp compression with second-order deltas
181+
- **XOR Float Codec**: Specialized IEEE 754 compression for measurements
182+
183+
### Capabilities
184+
- **Automatic Bucketing**: Time-range partitioning for fast queries
185+
- **Downsampling**: Aggregate high-frequency data into lower-resolution series
186+
- **Retention Policies**: Automatic archival and cleanup of old data
187+
- **Time-Range Indexes**: BRIN-style indexes for fast temporal lookups
188+
- **Bloom Filters**: Efficient time-range filtering
189+
190+
### Example Usage
191+
```csharp
192+
// Create time-series table
193+
await db.ExecuteSQLAsync(@"
194+
CREATE TABLE metrics (
195+
timestamp BIGINT,
196+
value REAL,
197+
tag TEXT,
198+
PRIMARY KEY (timestamp, tag)
199+
) WITH TIMESERIES
200+
");
201+
202+
// Insert compressed time-series data
203+
await db.ExecuteSQLAsync("INSERT INTO metrics VALUES (@ts, @val, @tag)");
204+
205+
// Query with time-range filtering (automatic codec decompression)
206+
var rows = await db.ExecuteQueryAsync(
207+
"SELECT * FROM metrics WHERE timestamp BETWEEN @start AND @end"
208+
);
209+
210+
// Downsample to 1-minute buckets
211+
var downsampled = await db.ExecuteQueryAsync(@"
212+
SELECT
213+
bucket_timestamp(timestamp, 60000) as bucket,
214+
AVG(value) as avg_value,
215+
MAX(value) as max_value
216+
FROM metrics
217+
GROUP BY bucket
218+
");
219+
```
220+
221+
---
222+
223+
## 📖 Documentation
224+
225+
For comprehensive documentation, visit:
226+
- **GitHub**: [https://github.com/MPCoreDeveloper/SharpCoreDB](https://github.com/MPCoreDeveloper/SharpCoreDB)
227+
- **User Manual**: [https://github.com/MPCoreDeveloper/SharpCoreDB/blob/master/docs/USER_MANUAL.md](https://github.com/MPCoreDeveloper/SharpCoreDB/blob/master/docs/USER_MANUAL.md)
228+
- **API Reference**: [https://github.com/MPCoreDeveloper/SharpCoreDB/tree/master/docs](https://github.com/MPCoreDeveloper/SharpCoreDB/tree/master/docs)
229+
230+
## 💡 Support
231+
232+
- **GitHub Issues**: [https://github.com/MPCoreDeveloper/SharpCoreDB/issues](https://github.com/MPCoreDeveloper/SharpCoreDB/issues)
233+
- **Discussions**: [https://github.com/MPCoreDeveloper/SharpCoreDB/discussions](https://github.com/MPCoreDeveloper/SharpCoreDB/discussions)
234+
- **Sponsor**: [https://github.com/sponsors/mpcoredeveloper](https://github.com/sponsors/mpcoredeveloper)
235+
236+
## 📜 License
237+
238+
SharpCoreDB is licensed under the MIT License. See [LICENSE](https://github.com/MPCoreDeveloper/SharpCoreDB/blob/master/LICENSE) for details.
239+
240+
---
241+
242+
**Copyright © 2026 MPCoreDeveloper**

0 commit comments

Comments
 (0)