fix [#31]: Add explicit 'file:' URL handling and update documentation

Libsql.Client.Tests/DatabaseClientTests.cs

@@ -0,0 +1,32 @@
+namespace Libsql.Client.Tests;
+
+public class DatabaseClientTests
+{
+    [Theory]
+    [InlineData("file:testdb.sqlite")]
+    [InlineData(":memory:")]
+    public async Task Create_WithValidPaths_ShouldCreateDatabaseClient(string path)
+    {
+        var client = await DatabaseClient.Create(path);
+
+        Assert.NotNull(client);
+        Assert.IsAssignableFrom<IDatabaseClient>(client);
+    }
+
+    [Fact]
+    public async Task Create_WithLocalPath_ShouldCreateDatabaseClient()
+    {
+        var filePath = Path.GetFullPath("testdb.sqlite");
+
+        var client = await DatabaseClient.Create(filePath);
+
+        Assert.NotNull(client);
+        Assert.IsAssignableFrom<IDatabaseClient>(client);
+    }
+
+    [Fact]
+    public async Task Create_WithNullPath_ShouldThrowArgumentNullException()
+    {
+        await Assert.ThrowsAsync<ArgumentNullException>(() => DatabaseClient.Create((string)null!));
+    }
+}

Libsql.Client/DatabaseClientOptions.cs

@@ -18,7 +18,21 @@ private DatabaseClientOptions(string url, string authToken = null, string replic
         /// <summary>
         /// Gets or sets the URL of the database server.
         /// </summary>
-        /// <remarks>Default: <c>""</c>. <c>""</c> or <c>":memory:"</c> will create an in-memory database.</remarks>
+        /// <remarks>
+        /// Supported values:
+        /// <list type="bullet">
+        ///   <item>
+        ///     <description><c>":memory:"</c> or <c>""</c> - Creates an in-memory database.</description>
+        ///   </item>
+        ///   <item>
+        ///     <description>Local file path (e.g. <c>file:localdb.sqlite</c> or <c>C:\data\localdbs.sqlite</c>) - Creates or opens a file-based database.</description>
+        ///   </item>
+        ///   <item>
+        ///     <description>Remote URL (e.g. <c>http://example.com/db</c>) - For remote database support.</description>
+        ///   </item>
+        /// </list>
+        /// Default: <c>""</c>.
+        /// </remarks>
         public string Url { get; set; }
 
         /// <summary>

Libsql.Client/DatabaseWrapper.cs

@@ -37,6 +37,9 @@ public unsafe DatabaseWrapper(DatabaseClientOptions options)
                         case "wss":
                             _type = _options.ReplicaPath != null ? DatabaseType.EmbeddedReplica : DatabaseType.Remote;
                             break;
+                        case "file":
+                            _type = DatabaseType.File;
+                            break;
                         default:
                             throw new InvalidOperationException($"Unsupported scheme: {uri.Scheme}");
                     }

README.md

@@ -29,13 +29,57 @@ For an example, see the Demo project in the repository.
 
 ### Creating a Database
 
+You can open a database in different locations:
+
+1. In-Memory Database
 ```csharp
 // Create an in-memory database.
 var dbClient = await DatabaseClient.Create(opts => {
     opts.Url = ":memory:";
 });
 ```
 
+2. From a File
+```csharp
+// Creates or opens a database stored in a local file.
+var dbClient = await DatabaseClient.Create(opts => {
+    opts.Url = "file:./mydb.sqlite";
+});
+```
+
+3. From a Connection String
+```csharp
+// Opens a database using a full connection string.
+var dbClient = await DatabaseClient.Create(opts => {
+    opts.Url = "https://my-remote-db.example.com";
+});
+```
+
+#### Provide Additional Connection Options
+#### Remote Databases
+For remote libSQL databases, use client options for authentication and secure connections:
+
+```csharp
+// Connect to a remote database with authentication and HTTPS enabled
+var dbClient = await DatabaseClient.Create(opts =>
+{
+    opts.Url = "https://my-remote-db.example.com";
+    opts.AuthToken = "MY_TOKEN";
+    opts.UseHttps = true;
+});
+```
+
+#### Local File Databases
+For local files, you can pass standard query parameters via the file URI:
+
+```csharp
+// Open a local database with query parameters
+var dbClient = await DatabaseClient.Create(opts =>
+{
+    opts.Url = "file:mydb.sqlite?mode=rwc&cache=shared";
+});
+```
+
 ### Executing SQL Statements
 
 Using direct queries