demo read/write and radonly combo

Author: MPCoreDeveloper

SharpCoreDB.Demo/Program.cs

@@ -64,8 +64,6 @@ static void Main(string[] args)
 
             // Read/write connection (default)
             var dbReadWrite = db;
-            // Create a readonly connection to the same database path
-            var dbReadOnly = factory.Create(dbPath, masterPassword, isReadOnly: true);
 
             // Step 3: Create Tables
             Console.WriteLine("--- Creating Tables ---");
@@ -99,6 +97,9 @@ static void Main(string[] args)
             dbReadWrite.ExecuteSQL("INSERT INTO test (id, name) VALUES (?, ?)", new Dictionary<string, object?> { { "0", 3 }, { "1", "AutoTest" } });
             Console.WriteLine("Inserted data");
 
+            // Create a readonly connection AFTER schema/data creation so it can load metadata
+            var dbReadOnly = factory.Create(dbPath, masterPassword, isReadOnly: true);
+
             // Step 5: Query Data from readonly connection
             Console.WriteLine("\n--- Querying Data (readonly connection) ---");
             dbReadOnly.ExecuteSQL("SELECT * FROM users");

SharpCoreDB/docs/ROADMAP.md

@@ -0,0 +1,68 @@
+# SharpCoreDB Roadmap
+
+## 1) Read-only instances and schema changes
+
+- Problem
+  - A read-only database instance loads the metadata (tables/indexes) once during construction.
+  - New tables created later by a read-write instance are invisible to already opened read-only instances.
+  - Result: queries against newly created tables fail on those read-only instances until they are recreated.
+
+- Current guidance (to document in guides/demos)
+  - Open read-only instances after completing schema changes; or
+  - Dispose and recreate read-only instances after CREATE/ALTER; or
+  - Run reporting/read-only processes that restart on schema changes.
+
+- Plan (non-breaking; v1.1.x)
+  1. API: `IDatabase.ReloadMetadata()`
+     - Forces a reload of `meta.json` and rebinds in-memory tables/indexes.
+     - Allowed for read-only instances (no write locks needed).
+  2. Opt-in auto-refresh for read-only
+     - `DatabaseConfig` flag: `AutoReloadMetadataOnChange` (default: false).
+     - File watcher on `meta.json` → debounce → `ReloadMetadata()`.
+  3. Schema versioning
+     - Extend meta with `SchemaVersion` (monotonic counter).
+     - Validate at query start: mismatch → (optional) auto-reload when the flag is active.
+  4. Events
+     - Read-write: `OnSchemaChanged` after `CREATE/DROP/ALTER` (increments `SchemaVersion`).
+  5. Connection pool integration
+     - Invalidate/refresh read-only pooled instances on schema changes (when pooling is enabled).
+
+- Testing
+  - Unit: `ReloadMetadata` reflects a newly created table; existing queries keep working.
+  - Integration: Read-write → CREATE TABLE; read-only with AutoReload flag sees the new table without recreation.
+
+- Documentation
+  - Add a section in `docs/guides/EXAMPLES.md`: timing of read-only instances, `ReloadMetadata()` usage, and the opt-in auto-reload flag.
+
+- Expected impact
+  - Backwards compatible; no breaking changes.
+  - Minimal runtime overhead when auto-reload is disabled (default).
+
+- Target versions
+  - v1.1.0: API + docs
+  - v1.1.1: opt-in auto-reload + tests
+
+---
+
+## 2) Users & permissions demo (completed)
+- Demo shows:
+  - Two users (`writer`, `reader`) and two connections (RW/RO).
+  - RW performs schema and data mutations; RO performs selects and blocks writes.
+  - Included in `SharpCoreDB.Demo` and referenced from docs.
+
+---
+
+## 3) Quality-of-life improvements
+- More specific exception for write attempts on read-only connections (include hint to recreate or reload).
+- `IDatabaseInfo` surface: `IsReadOnly`, `SchemaVersion`, `Tables` (for diagnostics/telemetry).
+
+---
+
+## Git compliance
+- Follow Conventional Commits for changes related to this roadmap:
+  - `feat(db): add ReloadMetadata API to refresh catalog on read-only instances`
+  - `feat(config): add AutoReloadMetadataOnChange flag`
+  - `docs(guide): document read-only behavior and metadata reload`
+  - `test(db): add integration tests for metadata reload`
+- Ensure updates include unit/integration tests and documentation changes in the same PR when feasible.
+

SharpCoreDB/docs/guides/EXAMPLES.md

@@ -12,6 +12,7 @@
 6. [Adaptive WAL Batching](#adaptive-wal-batching) - ⚡ **NEW!**
 7. [Entity Framework Core](#ef-core)
 8. [Advanced Queries](#advanced-queries)
+9. [Read-only Instances & Schema Changes](#read-only-instances--schema-changes)  <!-- NEW -->
 
 ---
 
@@ -489,20 +490,16 @@ var results = db.Query(@"
 
 ---
 
-## Performance Tips
+## Read-only Instances & Schema Changes
 
-1. **Use indexes** for frequently queried columns
-2. **Enable caching** for read-heavy workloads
-3. **Batch inserts** instead of individual inserts
-4. **Use transactions** for multiple operations
-5. **Choose correct index type** (B-Tree for ranges, Hash for equality)
-6. **Enable adaptive WAL batching** for variable/concurrent workloads ⚡ **NEW!**
-7. **Use HighPerformance or Concurrent config** for production deployments
-8. **Monitor batch size adjustments** to verify optimal scaling
+Read-only instances load the catalog (tables/indexes) once on construction. If a read-write instance creates a new table later, already opened read-only instances do not automatically “see” the new table.
 
----
+- Effect: queries against newly created tables fail on those read-only instances until they are recreated.
+- Cost: recreating a read-only instance only reloads small metadata files (O(#tables)) and has negligible overhead. It does not affect regular query performance.
+
+### Recommended patterns
 
-For more examples, see:
-- [Benchmarks](../SharpCoreDB.Benchmarks/)
-- [Demo Project](../SharpCoreDB.Demo/)
-- [Unit Tests](../SharpCoreDB.Tests/)
+```csharp
+// 1) Create schema with a read-write connection
+var rw = factory.Create(dbPath, password);
+rw.ExecuteSQL("CREATE TABLE users (id INTEGER, name TEXT)");