Refactor README to enhance usage instructions and add detailed examples for database operations

Author: IvanMurzak

Assets/Sample/2. DatabaseOperations/Scripts/Database/SQLiteContext.cs

@@ -11,5 +11,8 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
     {
         base.OnModelCreating(modelBuilder);
         modelBuilder.Entity<LevelData>();
+
+        // To create connection between tables read more about Code First EFCore approach
+        // Highly recommended to use command line to generate the code automatically.
     }
 }

README.md

@@ -27,14 +27,6 @@ Supports AOT an JIT compilation. For AOT it uses nested `link.xml` file to exclu
 - ✔️ `.NET Standard 2.0`
 - ✔️ `.NET Standard 2.1`
 
-# Usage
-
-Call the function once at app startup. Important to do that before opening SQLite connection.
-
-```C#
-SQLitePCLRaw.Startup.Setup();
-```
-
 Then use EFCore as usual.
 
 # Installation
@@ -47,11 +39,32 @@ Then use EFCore as usual.
 openupm add extensions.unity.bundle.efcore.sqlite
 ```
 
-# Alternative usage
+# Usage
+
+## Option 1: Explicit (Recommended)
+
+Use this approach to setup your database and establish connection.
+
+### 1. Create data model `LevelData.cs`
+
+```csharp
+using System.ComponentModel.DataAnnotations;
 
-## 1. Create `SQLiteContext` class
+public class LevelData
+{
+    [Key]
+    public int Id { get; set; }
+    [StringLength(100)]
+    public string Name { get; set; }
+    [Range(1, 10)]
+    public int Difficulty { get; set; }
+    public string Description { get; set; }
+}
+```
 
-```C#
+### 2. Create `SQLiteContext.cs`
+
+```csharp
 using Microsoft.EntityFrameworkCore;
 
 public class SQLiteContext : DbContext
@@ -66,39 +79,104 @@ public class SQLiteContext : DbContext
     {
         base.OnModelCreating(builder);
         builder.Entity<LevelData>();
+
+        // To create connection between tables read more about Code First EFCore approach
+        // Highly recommended to use command line to generate the code automatically.
     }
 }
 ```
 
-## 2. Create `SQLiteContextFactory` class
+### 3. Create `SQLiteContextFactory.cs`
 
-```C#
+```csharp
 using Microsoft.EntityFrameworkCore;
 
 public class SQLiteContextFactory : EFCoreSQLiteBundle.SQLiteContextFactory<SQLiteContext>
 {
-    protected override string DesignTimeDataSource => "replace it with path to design time database";
-
-    public SQLiteContextFactory() : base(UnityEngine.Application.persistentDataPath, "data.db") { }
+    public SQLiteContextFactory() : base(UnityEngine.Application.persistentDataPath, "data.db")
+    {
+        // Optional logging
+        UnityEngine.Debug.Log($"Using database: {DataSource}");
+    }
 
     protected override SQLiteContext InternalCreateDbContext(DbContextOptions<SQLiteContext> optionsBuilder)
-        => new SQLiteContext(optionsBuilder);
+    {
+        return new SQLiteContext(optionsBuilder);
+    }
 }
 ```
 
 The `EFCoreSQLiteBundle.SQLiteContextFactory` class under the hood executes `SQLitePCLRaw.Startup.Setup();` for proper SQLite setup depends on the current platform.
 
-## 3. Create database context
+### 4. Create database context
+
+```csharp
+using (var dbContext = new SQLiteContextFactory().CreateDbContext())
+{
+    // use it for data manipulations
+    // sample:
+    var level_1 = dbContext.Levels.FirstOrDefault(level => level.Id == 1);
+}
+```
+
+There is full usage sample in this source code:
+
+```csharp
+using System.Linq;
+using UnityEngine;
+
+public class DatabaseOperations : MonoBehaviour
+{
+    void Awake()
+    {
+        AddLevel("Level 1", 1, "Easy level");
+        AddLevel("Level 2", 2, "Medium level");
+        AddLevel("Level 3", 3, "Hard level");
+
+        PrintAllLevels();
+    }
+
+    void AddLevel(string name, int difficulty, string description)
+    {
+        using (var dbContext = new SQLiteContextFactory().CreateDbContext())
+        {
+            var level = new LevelData
+            {
+                Name = name,
+                Difficulty = difficulty,
+                Description = description
+            };
+            dbContext.Levels.Add(level);
+            dbContext.SaveChanges();
+        }
+        Debug.Log($"Added Level: {name}, Difficulty: {difficulty}");
+    }
+    void PrintAllLevels()
+    {
+        using (var dbContext = new SQLiteContextFactory().CreateDbContext())
+        {
+            var levels = dbContext.Levels.ToList();
+            foreach (var level in levels)
+                Debug.Log($"Level ID: {level.Id}, Name: {level.Name}, Difficulty: {level.Difficulty}");
+        }
+    }
+}
+```
 
-```C#
-var contextFactory = new SQLiteContextFactory();
-var dbContext = contextFactory.CreateDbContext();
+---
 
-// use it for data manipulations
-// sample:
-var level_1 = dbContext.Levels.FirstOrDefault(level => level.id == 1);
+## Option 2: Minimalistic
+
+Use this option if you well understand how to operate with EFCore on your own.
+
+Call the function once at app startup. Important to do that before opening SQLite connection. This method call prepares SQLite.
+
+```csharp
+SQLitePCLRaw.Startup.Setup();
 ```
 
+---
+
 # Helpful information
 
 Read more how to use [EntityFrameworkCore](https://learn.microsoft.com/en-us/ef/ef6/get-started?redirectedfrom=MSDN). My favorite approach is `Code First`.