update docs

docs/badaas-orm/concepts.rst

@@ -33,14 +33,13 @@ Auto Migration
 
 To persist the models it is necessary to migrate the database, 
 so that the structure of the tables corresponds to the definition of the model. 
-This migration is performed by gorm through the gormDB.
 
 For details visit :ref:`badaas-orm/connecting_to_a_database:migration`.
 
-GormDB
+orm.DB object
 -----------------------------
 
-GormDB is a gorm.DB object that allows communication with the database.
+It's a object that allows communication with the database.
 
 For details visit :ref:`badaas-orm/connecting_to_a_database:connection`.
 

docs/badaas-orm/connecting_to_a_database.rst

@@ -9,21 +9,20 @@ badaas-orm supports the PostgreSQL databases using gorm's driver.
 Some databases may be compatible with the postgres dialect, 
 in which case you could just use the dialect for those databases (from which CockroachDB is tested).
 
-To communicate with the database badaas-orm need a :ref:`GormDB <badaas-orm/concepts:GormDB>` object, 
-that can be created by following `gorm documentation <https://gorm.io/docs/connecting_to_the_database.html>`_. 
-
-badaas-orm also offers the `orm.ConnectToDialector` method that will allow you to connect to a database 
+To communicate with the database badaas-orm need a orm.DB object. 
+To create it, you can use the function `orm.Open` that will allow you to connect to a database 
 using the specified dialector with retrying. 
-It also configures the `gorm's logger <https://gorm.io/docs/logger.html>`_ to work with 
-`zap logger <https://github.com/uber-go/zap>`_.
+It also lets you configure the logger, for details visit :doc:`/badaas-orm/logger`.
 
 When using badaas-orm with `fx` as :ref:`dependency injector <badaas-orm/concepts:Dependency injection>` you 
-will need to provide (`fx.Provide`) a function that returns a `*gorm.DB`.
+will need to provide (`fx.Provide`) a function that returns a `*orm.DB`.
+
+You can access all the methods provided by gorm using the GormDB reference of the orm.DB object.
 
 Migration
 ----------------------------
 
-Migration is done by gorm using the `gormDB.AutoMigrate` method. 
+Migration is done by gorm using the `db.GormDB.AutoMigrate` method, where db is a orm.DB object.
 For details visit `gorm docs <https://gorm.io/docs/migration.html>`_.
 
 When using badaas-orm with `fx` as :ref:`dependency injector <badaas-orm/concepts:Dependency injection>` 

docs/badaas-orm/crud.rst

@@ -18,10 +18,10 @@ On the other hand, read (query) operations are provided by badaas-orm via its
 (see how in :doc:`/badaas-orm/query`).
 
 Each pair of CRUDService and CRUDRepository corresponds to a model. To create them you must use 
-the `orm.GetCRUD[<model>, <modelID>](gormDB)` where 
+the `orm.GetCRUD[<model>, <modelID>](ormDB)` where 
 `<model>` is the type of your :ref:`model <badaas-orm/concepts:model>`, 
 `<modelID>` is the type of your :ref:`model's id <badaas-orm/concepts:model id>` 
-and `gormDB` is the :ref:`GormDB <badaas-orm/concepts:GormDB>` object.
+and `ormDB` is the :ref:`orm.DB <badaas-orm/concepts:orm.DB object>` object.
 
 When using badaas-orm with `fx` as :ref:`dependency injector <badaas-orm/concepts:Dependency injection>` you 
 will need to provide to fx `orm.GetCRUDServiceModule[<model>]()` 
@@ -43,8 +43,7 @@ For example:
     func main() {
         fx.New(
             // connect to db
-            fx.Provide(NewGormDBConnection),
-            // activate badaas-orm
+            fx.Provide(NewDBConnection),
             fx.Provide(GetModels),
             orm.AutoMigrate,
 
@@ -55,4 +54,16 @@ For example:
 
     func QueryCRUDObjects(crudYourModelService orm.CRUDService[YourModel, model.UUID]) {
         // use crudYourModelService
-    }
+    }
+
+Transactions
+--------------------
+
+To execute transactions badaas-orm provides the function orm.Transaction. 
+The function passed by parameter will be executed inside a gorm transaction 
+(for more information visit https://gorm.io/docs/transactions.html). 
+Using this method will also allow the transaction execution time to be logged.
+
+In accordance to the previous section, 
+CRUDServices make use of the orm.Transaction function while 
+CRUDRepositories must be called within one of them.

docs/badaas-orm/logger.rst

@@ -0,0 +1,115 @@
+==============================
+Logger
+==============================
+
+When connecting to the database, i.e. when creating the `orm.DB` object, 
+it is possible to configure the type of logger to use, the logging level, among others. 
+As explained in the :ref:`connection section <badaas-orm/connecting_to_a_database:Connection>`, 
+this can be done by using the `orm.Open` method. 
+Any logger that complies with `logger.Interface` can be configured.
+
+Log levels
+------------------------------
+
+The log levels provided by badaas-orm are the same as those of gorm:
+
+- `logger.Error`: To only view error messages in case they occur during the execution of a sql query.
+- `logger.Warn`: The previous level plus warnings for execution of queries and transactions that take 
+  longer than a certain time 
+  (configurable with SlowQueryThreshold and SlowTransactionThreshold respectively, 200ms by default).
+- `logger.Info`: The previous level plus information messages for each query and transaction executed.
+
+Transactions
+------------------
+
+For the logs corresponding to transactions 
+(slow transactions and transaction execution) 
+to be performed, it is necessary to use the orm.Transaction method.
+
+Default logger
+-------------------------------
+
+badaas-orm provides a default logger that will print Slow SQL and happening errors. 
+
+You can create one with the default configuration using 
+(take into account that logger is github.com/ditrit/badaas/orm/logger 
+and gormLogger is gorm.io/gorm/logger):
+
+.. code-block:: go
+
+  logger.Default
+
+or use `logger.New` to customize it:
+
+.. code-block:: go
+
+  logger.New(gormLogger.Config {
+    SlowQueryThreshold:        200 * time.Millisecond,
+    SlowTransactionThreshold:  200 * time.Millisecond,
+    LogLevel:                  gormLogger.Warn,
+    IgnoreRecordNotFoundError: false,
+    ParameterizedQueries:      false,
+    Colorful:                  true,
+  })
+
+The LogLevel is also configurable via the `ToLogMode` method. 
+
+**Example**
+
+.. code-block:: bash
+
+  standalone/example.go:30 [10.392ms] [rows:1] INSERT INTO "products" ("id","created_at","updated_at","deleted_at","string","int","float","bool") VALUES ('4e6d837b-5641-45c9-a028-e5251e1a18b1','2023-07-21 17:19:59.563','2023-07-21 17:19:59.563',NULL,'',1,0.000000,false)
+
+Zap logger
+------------------------------
+
+badaas-orm provides the possibility to use `zap <https://github.com/uber-go/zap>`_ as logger. 
+For this, there is a package called `gormzap`. 
+The information displayed by the zap logger will be the same as if we were using the default logger 
+but in a structured form, with the following information:
+
+* level: ERROR, WARN or DEBUG
+* message:
+
+  * query_error for errors during the execution of a query (ERROR)
+  * query_slow for slow queries (WARN)
+  * transaction_slow for slow transactions (WARN)
+  * query_exec for query execution (DEBUG)
+  * transaction_exec for transaction execution (DEBUG)
+* error: <error_message> (for errors only)
+* elapsed_time: query or transaction execution time
+* rows_affected: number of rows affected by the query
+* sql: query executed
+
+You can create one with the default configuration using:
+
+.. code-block:: go
+
+  gormzap.NewDefault(zapLogger)
+
+where `zapLogger` is a zap logger, or use `gormzap.New` to customize it:
+
+.. code-block:: go
+
+  gormzap.New(zapLogger, logger.Config {
+    LogLevel:                  logger.Warn,
+    SlowQueryThreshold:        200 * time.Millisecond,
+    SlowTransactionThreshold:  200 * time.Millisecond,
+    IgnoreRecordNotFoundError: false,
+    ParameterizedQueries:      false,
+  })
+
+The LogLevel is also configurable via the `ToLogMode` method. 
+Any configuration of the zap logger is done directly during its creation following the 
+`zap documentation <https://pkg.go.dev/go.uber.org/zap#hdr-Configuring_Zap>`_. 
+Note that the zap logger has its own level setting, so the lower of the two settings 
+will be the one finally used.
+
+**Example**
+
+.. code-block:: bash
+
+  DEBUG	fx/example.go:107	query_exec	{"elapsed_time": "3.291981ms", "rows_affected": "1", "sql": "SELECT products.* FROM \"products\" WHERE products.int = 1 AND \"products\".\"deleted_at\" IS NULL"}
+
+
+

docs/badaas-orm/quickstart.rst

@@ -24,24 +24,24 @@ Once you have started your project with `go init`, you must add the dependency t
 
 .. code-block:: bash
 
-    go get -u github.com/ditrit/badaas github.com/uber-go/zap gorm.io/gorm
+    go get -u github.com/ditrit/badaas gorm.io/gorm
 
 
 In models.go the :ref:`models <badaas-orm/concepts:model>` are defined and 
 in conditions/orm.go the file required to 
 :ref:`generate the conditions <badaas-orm/concepts:conditions generation>` is created.
 
 In main.go a main function is created with the configuration required to use the badaas-orm. 
-First, we need to create a :ref:`gormDB <badaas-orm/concepts:gormDB>` that allows connection with the database:
+First, we need to create a :ref:`orm.DB <badaas-orm/concepts:orm.DB object>` that allows connection with the database:
 
 .. code-block:: go
 
-    gormDB, err := NewGormDBConnection()
+    db, err := NewDBConnection()
 
 After that, we have to call the :ref:`AutoMigrate <badaas-orm/concepts:auto migration>` 
 method of the gormDB with the models you want to be persisted::
 
-    err = gormDB.AutoMigrate(
+    err = db.GormDB.AutoMigrate(
       models.Product{},
       models.Company{},
       models.Seller{},
@@ -53,7 +53,7 @@ and :ref:`CRUDRepository <badaas-orm/concepts:CRUDRepository>` of a model with t
 
 .. code-block:: go
 
-    crudProductService, crudProductRepository := orm.GetCRUD[models.Product, model.UUID](gormDB)
+    crudProductService, crudProductRepository := orm.GetCRUD[models.Product, model.UUID](db)
 
 As you can see, we need to specify the type of the model and the kind 
 of :ref:`id <badaas-orm/concepts:model ID>` this model uses.
@@ -62,7 +62,7 @@ Finally, you can use this service and repository to perform CRUD operations on y
 
 .. code-block:: go
 
-  CreateCRUDObjects(gormDB, crudProductRepository)
+  CreateCRUDObjects(db, crudProductRepository)
   QueryCRUDObjects(crudProductService)
 
 This two functions are defined in `example.go`. 
@@ -88,12 +88,17 @@ First, we will need to start your application with `fx`:
 
     func main() {
       fx.New(
+        fx.Provide(NewZapLogger),
         // connect to db
-        fx.Provide(NewGormDBConnection),
-        // activate badaas-orm
+        fx.Provide(NewDBConnection),
         fx.Provide(GetModels),
         orm.AutoMigrate,
 
+        // logger for fx
+        fx.WithLogger(func(logger *zap.Logger) fxevent.Logger {
+          return &fxevent.ZapLogger{Logger: logger}
+        }),
+
         // create crud services for models
         orm.GetCRUDServiceModule[models.Company](),
         orm.GetCRUDServiceModule[models.Product](),
@@ -108,8 +113,11 @@ First, we will need to start your application with `fx`:
 
 There are some things you need to provide to the badaas-orm module:
 
-- `NewGORMDBConnection` is the function that we need to create 
-  a :ref:`gormDB <badaas-orm/concepts:gormDB>` that allows connection with the database.
+- `NewZapLogger` (optional) in this case we will use the zap logger instead of the gorm logger, 
+  so we have to provide it and then use it as a logger for fx. 
+  For more information visit :doc:`logger`.
+- `NewDBConnection` is the function that we need to create 
+  a :ref:`orm.DB <badaas-orm/concepts:orm.DB object>` that allows connection with the database.
 - `GetModels` is a function that returns in a `orm.GetModelsResult` the list of models 
   you want to be persisted by the :ref:`auto migration <badaas-orm/concepts:auto migration>`.
 

docs/badaas/configuration.rst

@@ -105,6 +105,29 @@ The values available are `method`, `url` and `protocol`.
     # Either `dev` or `prod`
     # default (`prod`)
     mode: prod
+
+    # Disable error stacktrace from logs
+    # default (true)
+    disableStacktrace: true
+
+    # Threshold for the slow query warning in milliseconds
+    # default (200)
+    # use 0 to disable slow query warnings
+    slowQueryThreshold: 200
+
+    # Threshold for the slow transaction warning in milliseconds
+    # default (200)
+    # use 0 to disable slow transaction warnings
+    slowTransactionThreshold: 200
+
+    # If true, ignore gorm.ErrRecordNotFound error for logger
+    # default (false)
+    ignoreRecordNotFoundError: false
+
+    # If true, don't include params in the query execution logs
+    # default (false)
+    parameterizedQueries: false
+
     request:
       # Change the log emitted when badaas receives a request on a valid endpoint.
       template: "Receive {{method}} request on {{url}}"

docs/contributing/developing.md

@@ -21,7 +21,7 @@ This is the directory structure we use for the project:
 - `mocks/`: Contains the mocks generated with `mockery`.
 - `orm/` *(Go code)*: Contains the code of the orm used by badaas.
 - `persistance/`:
-  - `gormdatabase/`: Contains the logic to create a <https://gorm.io> database. Also contains a go package named `gormzap`: it is a compatibility layer between *gorm.io/gorm* and *github.com/uber-go/zap*.
+  - `database/`: Contains the logic to create a <https://gorm.io> database.
   - `models/`: Contains the models.
     - `dto/`: Contains the Data Transfer Objects. They are used mainly to decode json payloads.
   - `repository/`: Contains the repository interfaces and implementations to manage queries to the database.

docs/index.rst

@@ -52,6 +52,7 @@ Learn how to use BaDaaS following the :doc:`badaas/quickstart`.
    badaas-orm/query
    badaas-orm/advanced_query
    badaas-orm/preloading
+   badaas-orm/logger
 
 .. toctree::
    :caption: Contributing