V3.0.0

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+
+*.sh  eol=lf

.vscode/launch.json

@@ -13,7 +13,7 @@
             "args": [
                 "sync"
             ],
-            "cwd": "${workspaceFolder}/src/DbBroker.Cli",
+            "cwd": "${workspaceFolder}/src/DbBroker.Showcase.Cli",
             "stopAtEntry": false,
             "console": "internalConsole"
         },

README.md

@@ -1,21 +1,28 @@
-<div align="center">
-  <img src="/assets/logo-with-name.png" alt="DBBroker logo" />
-  <br/>
-  A lightweight and easy to use .NET tool and library for effortless database records manipulation.
-</div>
+# DBBroker
+
+![DbBroker logo](/assets/logo-with-name.png "logo")
+
+A lightweight and easy to use .NET tool and library for effortless database records manipulation.
+
+## Benefits
+
+- Automatically generated Data Models
+- Zero-SQL
+- Compile time database compatibility and change check
 
 ## NuGet
 
 | Package | Latest | |
 |----|----|----|
-| DBBroker | ![NuGet Version](https://img.shields.io/nuget/v/dbbroker) | [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0#select-net-standard-version) |
-| DBBroker.Cli | ![NuGet Version](https://img.shields.io/nuget/v/dbbroker.cli) | |
+| [DBBroker](https://www.nuget.org/packages/DBBroker) | ![NuGet Version](https://img.shields.io/nuget/v/dbbroker) | [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0#select-net-standard-version) |
+| [DBBroker.Cli](https://www.nuget.org/packages/DBBroker.Cli) | ![NuGet Version](https://img.shields.io/nuget/v/dbbroker.cli) | |
 
-**IMPORTANT:** This version has no backward compatibility with DBBroker 1.x and 2.x.
+> [!WARNING]
+> Version 3.x has no backward compatibility with DBBroker 1.x and 2.x
 
-## What It Does?
+## How it works?
 
-Differently from another popular ORM packages, DBBroker approach associates a [.NET CLI tool](https://nuget.org/dbbroker.cli) to automatically generate **Data Models** and a [library](https://nuget.org/dbbroker) that uses those Data Models at runtime to manipulate database records.
+DBBroker approach is powerful and different from other ORMs because it associates a [.NET CLI tool](https://nuget.org/dbbroker.cli) to automatically generate **Data Models** and a [library](https://nuget.org/dbbroker) that uses those Data Models at runtime to generate SQL and manipulate database records.
 
 ## Philosophy
 
@@ -29,7 +36,7 @@ DBBroker offers features that benefit any kind of application, from the simplest
 
 These are common requirements for many organizations or database-centered solutions, and, arguably, by everyone who likes to keep things simple.
 
-## Quick Start
+## Quick Start⚡
 
 Open your terminal and navigate to your application's *.csproj directory. Then follow these steps:
 
@@ -48,7 +55,7 @@ dotnet nuget add DBBroker
 **Step 3:** Create a `dbbroker.config.json` file at the root of your project.
 
 ```bash
-dbbroker init --namespace="MyApp.DataModels" --connection-string "[database-connection-string]" --provider Oracle
+dbbroker init --namespace="MyApp.DataModels" --connection-string "<my_connection_string>" --provider Oracle
 ```
 
 **Step 4:** Synchronize your project with your database schemas to generate the Data Models.
@@ -67,15 +74,15 @@ var customer = new CustomersDataModel();
 customer.Name = "John Three Sixteen";
 customer.Birthday = new DateTime(1980, 3, 16);
 
-var id = await _dbBroker.InsertAsync(customer);
+var id = await dbConnection.InsertAsync(customer);
 ```
 
 Entity persistence with transactions.
 
 ```C#
-using var connection = new SqlConnection();
-connection.Open();
-var transaction = connection.GetTransaction();
+using var dbConnection = new SqlConnection();
+dbConnection.Open();
+var transaction = dbConnection.GetTransaction();
 
 try 
 {
@@ -84,14 +91,14 @@ try
     customer.Name = "John Three Sixteen";
     customer.Birthday = new DateTime(1980, 3, 16);
 
-    await connection.InsertAsync(customer, transaction);
+    await dbConnection.InsertAsync(customer, transaction);
 
-    var car = new CarEdm();
+    var car = new CarsDataModel();
     car.Model = "Renault Twingo";
     car.Year = 2001;
     car.CustomerId = customer.Id;
 
-    await connection.InsertAsync(car, transaction);
+    await dbConnection.InsertAsync(car, transaction);
     transaction.Commit();
 }
 catch(Exception ex)
@@ -103,24 +110,34 @@ catch(Exception ex)
 Retrieving a record.
 
 ```C#
-var customer = await connection.GetByKey<CustomersDataModel>("543491fa-788a-474c-9f3b-6ed6566e5d2c");
+var result = await dbConnection
+    .Select<CustomersDataModel>()
+    .AddFilter(x => x.Id, SqlEquals.To("1e6fc0e6-1fe2-49c0-ba37-ec14bf8eddc4"))
+    .ExecuteAsync();
+
+var customer = result.FirstOrDefault();
 ```
 
 Retrieving multiple and filtered records.
 
 ```C#
-var inactiveCustomers = await connection.Select<CustomersDataModel>()
+var inactiveCustomers = await dbConnection.Select<CustomersDataModel>()
   .AddFilter(x => x.StatusId, SqlEquals.To(3))
-  .FetchFirst(records: 100, skip: 300) // helps implement a 'load more' or pagination strategy
   .ExecuteAsync();
 ```
 
-```C#
-// another example with columns
-```
+Retrieving multiple records loading only specified columns.
 
 ```C#
-// another example with columns and order by
+var inactiveCustomers = await dbConnection
+    .Select<CustomersDataModel>([
+        x => x.Id,
+        x => x.Name,
+        x => x.Birthday
+    ])
+    .OrderBy(x => x.Name)
+    .AddFilter(x => x.StatusId, SqlEquals.To(3))
+    .ExecuteAsync();
 ```
 
 ## Supported Databases
@@ -134,7 +151,7 @@ var inactiveCustomers = await connection.Select<CustomersDataModel>()
 
 ## Contribute
 
-We appreciate all contributions, whether they're bug reports, feature suggestions, or pull requests. Thank you for your interest and support in improving this project!
+All contributions are appreciated, whether they're bug reports, feature suggestions, or pull requests. Thank you for your interest and support in improving this project!
 
 Financial support is also welcome, whether large or small contributions will help to keep this project moving and always secure.
 

docs/json-schema/dbbroker.config.schema.json

@@ -5,6 +5,21 @@
   "description": "Configuration file to describe database contexts",
   "type": "object",
   "properties": {
+    "database": {
+      "description": "The database information against which DBBroker will run",
+      "type": "object",
+      "properties": {
+        "provider": {
+          "description": "The database provider",
+          "type": "string",
+          "enum": ["SqlServer", "Oracle"]
+        },
+        "connectionString": {
+          "description": "The connection string DBBroker is going to use to prospect database metadata",
+          "type": "string"
+        }
+      }
+    },   
     "contexts": {
       "description": "Database contexts",
       "type": "array",
@@ -15,13 +30,21 @@
             "description": "The namespace where Data Models should be placed in",
             "type": "string"
           },
+          "name": {
+            "description": "The context name. Can be used to selectively synchronize a context in a dbbroker.config.json file.",
+            "type": "string"
+          },
+          "outputDirectory": {
+            "description": "The relative directory where Data Models should be placed in. If omitted a folder structure based on the namespace will be created skipping the first part (generaly the application name).",
+            "type": "string"
+          },
           "provider": {
-            "description": "The database provider",
+            "description": "The database provider. Overrides 'database.provider'.",
             "type": "string",
             "enum": ["SqlServer", "Oracle"]
           },
           "connectionString": {
-            "description": "The connection string DBBroker is going to use to prospect database metadata",
+            "description": "The connection string DBBroker is going to use to prospect database metadata. Overrides 'database.connectionString'.",
             "type": "string"
           },
           "defaultSqlInsertTemplateTypeFullName": {
@@ -36,8 +59,20 @@
             "description": "The name sufix that Entity Data Models classes will receive when generated. The default value is 'DataModel'.",
             "type": "string"
           },
+          "ignoreTablesNotListed": {
+            "description": "Should DBBroker ignore database tables not described on 'tables' array? If 'true', you need to include manually all table references of tables listed in 'tables' array, unless you set the 'addReferences' property on the table to false. The default value is 'false'.",
+            "type": "boolean"
+          },
+          "ignoreViewsNotListed": {
+            "description": "Should DBBroker ignore database views not described on 'views' array? The default value is 'false'.",
+            "type": "boolean"
+          },
+          "clearOutputDirectory": {
+            "description": "Specifies if DBBroker CLI should Remove all preexisting files from the output directory before syncing. Default value is 'false'.",
+            "type": "boolean"
+          },
           "tables": {
-            "description": "Array of tables DBBroker will use to generate the Data Models",
+            "description": "Array of database tables DBBroker will use to generate the Data Models. If empty, all tables will be included by default. See 'ignoreTablesNotListed'.",
             "type": "array",
             "items": {
               "type": "object",
@@ -67,6 +102,52 @@
                 "sqlInsertTemplateArguments": {
                   "description": "Arguments the ISqlInsertTemplate specified might be expecting",
                   "type": "object"
+                },
+                "addReferences": {
+                  "description": "Specifies if the table references should be included. Composite Primary Keys are not supported. Default value is true.",
+                  "type": "boolean"
+                }
+              }
+            }
+          },
+          "views": {
+            "description": "Array of database views DBBroker will use to generate the Data Models. If empty, all tables will be included by default.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "description": "The view name",
+                  "type": "string"
+                },
+                "schema": {
+                  "description": "The view schema name",
+                  "type": "string"
+                },
+                "type": {
+                  "description": "The Data Model type name",
+                  "type": "string"
+                },
+                "splitsOn": {
+                  "description": "A collection of descriptors to split the database view record set into Data Model entities. When using this feature the first column on the view will be used as the first 'Split value', therefore use an identifier value.",
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "column": {
+                        "description": "The column name to split the record set and start loading data of an entity",
+                        "type": "string"
+                      },
+                      "type": {
+                        "description": "The Data Model type name",
+                        "type": "string"
+                      },
+                      "collection": {
+                        "description": "Should the entity on this split be treated as a collection?",
+                        "type": "boolean"
+                      }
+                    }
+                  }
                 }
               }
             }

src/.gitignore

@@ -3,3 +3,6 @@ obj
 
 Edm
 DataModels
+
+*.ps1
+.vs