update docs

docs/badaas-orm/connecting_to_a_database.rst

@@ -9,13 +9,13 @@ 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 
-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>`_.
+To communicate with the database badaas-orm need a :ref:`GormDB <badaas-orm/concepts:GormDB>` object. 
+To create it, you can use the function `orm.Open` that will allow you to connect to a database 
+using the specified dialector. This function is equivalent to `gorm.Open` 
+but with the difference that in case of not adding any configuration, 
+the badaas-orm default logger will be configured instead of the gorm one. 
+For details about this logger visit :doc:`/badaas-orm/logger`. 
+For details about gorm configuration visit `gorm documentation <https://gorm.io/docs/connecting_to_the_database.html>`_.
 
 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`.
@@ -30,7 +30,4 @@ When using badaas-orm with `fx` as :ref:`dependency injector <badaas-orm/concept
 this method can't be called directly. In that case, badaas-orm will execute the migration by providing 
 `orm.AutoMigrate` to fx. For this to work, you will need to provide also a method that returns 
 `orm.GetModelsResult` with the models you want to include in the migration. 
-Remember that the order in this list is important for gorm to be able to execute the migration.
-
-
-
+Remember that the order in this list is important for gorm to be able to execute the migration.

docs/badaas-orm/crud.rst

@@ -21,7 +21,7 @@ Each pair of CRUDService and CRUDRepository corresponds to a model. To create th
 the `orm.GetCRUD[<model>, <modelID>](gormDB)` 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 `gormDB` is the :ref:`gorm.DB <badaas-orm/concepts:GormDB>` 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,122 @@
+==============================
+Logger
+==============================
+
+When connecting to the database, i.e. when creating the `gorm.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:
+
+.. code-block:: go
+
+  gormDB, err = orm.Open(
+    dialector,
+    &gorm.Config{
+      Logger: logger.Default,
+    },
+  )
+
+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,19 +24,19 @@ 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:`gorm.DB <badaas-orm/concepts:GormDB>` that allows connection with the database:
 
 .. code-block:: go
 
-    gormDB, err := NewGormDBConnection()
+    gormDB, 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::
@@ -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:`gorm.DB <badaas-orm/concepts:GormDB>` 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