Merge remote-tracking branch 'origin/HEAD' into fmeheust-testing

Author: fmeheust

README.md

@@ -18,13 +18,13 @@ dsn := `user="scott" password="tiger"
         libDir="/Path/to/your/instantclient_23_8"`
 ```
 
-## Quick start
+## Getting Started
 
 ```go main.go
 package main
 
 import (
-        "github.com/oracle/gorm-oracle/oracle"
+        "github.com/oracle-samples/gorm-oracle/oracle"
         "gorm.io/gorm"
 )
 

go.mod

@@ -1,4 +1,4 @@
-module github.com/oracle/gorm-oracle
+module github.com/oracle-samples/gorm-oracle
 
 go 1.24.4
 

oracle/clause_builder.go

@@ -58,6 +58,7 @@ const (
 	ClauseReturning  = "RETURNING"
 )
 
+// Returns the clause builders that are used to generate clauses for Oracle DB
 func OracleClauseBuilders() map[string]clause.ClauseBuilder {
 	return map[string]clause.ClauseBuilder{
 		ClauseInsert:     InsertClauseBuilder,
@@ -70,6 +71,7 @@ func OracleClauseBuilders() map[string]clause.ClauseBuilder {
 	}
 }
 
+// InsertClauseBuilder builds the INSERT INTO cluase
 func InsertClauseBuilder(c clause.Clause, builder clause.Builder) {
 
 	if insert, ok := c.Expression.(clause.Insert); ok {
@@ -87,6 +89,7 @@ func InsertClauseBuilder(c clause.Clause, builder clause.Builder) {
 	// Modifier field is intentionally ignored for Oracle
 }
 
+// UpdateClauseBuilder builds the UPDATE clause
 func UpdateClauseBuilder(c clause.Clause, builder clause.Builder) {
 	if update, ok := c.Expression.(clause.Update); ok {
 		builder.WriteString("UPDATE ")
@@ -103,6 +106,7 @@ func UpdateClauseBuilder(c clause.Clause, builder clause.Builder) {
 	// Modifier field is intentionally ignored for Oracle
 }
 
+// DeleteClauseBuilder builds the DELETE clause
 func DeleteClauseBuilder(c clause.Clause, builder clause.Builder) {
 	if _, ok := c.Expression.(clause.Delete); ok {
 		builder.WriteString("DELETE")
@@ -176,8 +180,8 @@ func ReturningClauseBuilder(c clause.Clause, builder clause.Builder) {
 	}
 }
 
-// getDefaultValues remains the same - it extracts values from sql.Out parameters
-
+// LimitClauseBuilder builds the Oracle FETCH clause instead of using the default LIMIT syntax
+// The FETCH syntax is supported in Oracle 12c and later
 func LimitClauseBuilder(c clause.Clause, builder clause.Builder) {
 	if limit, ok := c.Expression.(clause.Limit); ok {
 		// Convert LIMIT to Oracle FETCH syntax
@@ -187,6 +191,7 @@ func LimitClauseBuilder(c clause.Clause, builder clause.Builder) {
 	}
 }
 
+// ValuesClauseBuilder builds the VALUES clause of an INSERT statement
 func ValuesClauseBuilder(c clause.Clause, builder clause.Builder) {
 	if values, ok := c.Expression.(clause.Values); ok {
 		if len(values.Columns) > 0 {
@@ -273,7 +278,7 @@ func buildOracleFetchLimit(limit clause.Limit, builder clause.Builder, stmt *gor
 	}
 }
 
-// Updated OnConflictClauseBuilder - builds MERGE statement directly
+// OnConflictClauseBuilder builds MERGE statement directly
 func OnConflictClauseBuilder(c clause.Clause, builder clause.Builder) {
 	if onConflict, ok := c.Expression.(clause.OnConflict); ok {
 		if stmt, ok := builder.(*gorm.Statement); ok {

oracle/create.go

@@ -50,6 +50,22 @@ import (
 	"gorm.io/gorm/schema"
 )
 
+// Create overrides GORM's create callback for Oracle.
+//
+// Behavior:
+//   - If the schema has fields with default DB values and only one row is
+//     being inserted, it builds an INSERT ... RETURNING statement.
+//   - If no RETURNING is needed, it emits a standard INSERT.
+//   - If multiple rows require RETURNING, it builds a PL/SQL block using
+//     FORALL and BULK COLLECT; if an ON CONFLICT clause is present and
+//     resolvable, it emits a MERGE.
+//   - For that last case, it validates Dest (non-nil, non-empty slice with
+//     no nil elements), normalizes bind variables for Oracle, and populates
+//     destinations from OUT parameters.
+//
+// Register with:
+//
+//	db.Callback().Create().Replace("gorm:create", oracle.Create)
 func Create(db *gorm.DB) {
 	if db.Error != nil || db.Statement == nil {
 		return

oracle/delete.go

@@ -49,7 +49,31 @@ import (
 	"gorm.io/gorm/schema"
 )
 
-// Delete callback function for Oracle
+// Delete overrides GORM's delete callback for Oracle.
+//
+// Delete builds a safe, Oracle-compatible DELETE that supports soft deletes,
+// hard deletes, and optional RETURNING of deleted rows.
+//
+// Behavior:
+//   - DELETE safety: checks for missing WHERE conditions and refuses to run
+//     unless AllowGlobalUpdate is set or the WHERE clause has meaningful
+//     conditions.
+//   - Soft delete: if the model has a soft-delete field and Unscoped is false,
+//     it lets GORM emit the UPDATE that marks rows as deleted. If a RETURNING
+//     clause is present with soft delete, it executes via QueryContext so the
+//     returned columns can be scanned.
+//   - Hard delete + RETURNING: it emits a PL/SQL block that performs DELETE …
+//     RETURNING BULK COLLECT INTO, wiring per-row sql.Out destinations so the
+//     deleted rows (or selected columns) can be populated back into the
+//     destination slice.
+//   - Hard delete (no RETURNING): it emits a standard DELETE and executes it
+//     via ExecContext.
+//   - Expressions: it expands WHERE expressions, including IN with slices, and
+//     normalizes bind variables for Oracle.
+//
+// Register with:
+//
+//	db.Callback().Delete().Replace("gorm:delete", oracle.Delete)
 func Delete(db *gorm.DB) {
 	if db.Error != nil || db.Statement == nil {
 		return

oracle/migrator.go

@@ -57,22 +57,22 @@ type Migrator struct {
 	migrator.Migrator
 }
 
-// RunWithValue run migration with statement value
+// RunWithValue runs migration for the given `value`
 func (m Migrator) RunWithValue(value interface{}, fc func(*gorm.Statement) error) error {
 	if table, ok := value.(string); ok {
 		return m.Migrator.RunWithValue(table, fc)
 	}
 	return m.Migrator.RunWithValue(value, fc)
 }
 
-// Database
+// CurrentDatabase returns the the name of the current Oracle database
 func (m Migrator) CurrentDatabase() string {
 	var name string
 	m.DB.Raw("SELECT ora_database_name FROM dual").Scan(&name)
 	return name
 }
 
-// CreateTable create table in database for values
+// CreateTable creates table in database for the given `values`
 func (m Migrator) CreateTable(values ...interface{}) error {
 
 	for _, value := range m.ReorderModels(values, false) {
@@ -201,7 +201,9 @@ func (m Migrator) CreateTable(values ...interface{}) error {
 	return nil
 }
 
-// Drops the table starting from the bottom of the dependency chain
+// DropTable drops the table starting from the bottom of the dependency chain.
+// The function returns an error when Oracle databases report a missing table.
+// If multiple errors occur, it returns a combined (joint) error.
 func (m Migrator) DropTable(values ...interface{}) error {
 	var errorList []error
 	values = m.ReorderModels(values, false)
@@ -234,7 +236,7 @@ func (m Migrator) HasTable(value interface{}) bool {
 	return count > 0
 }
 
-// RenameTable rename table from oldName to newName
+// RenameTable renames table from oldName to newName
 func (m Migrator) RenameTable(oldName, newName interface{}) error {
 	var oldTable, newTable interface{}
 	if v, ok := oldName.(string); ok {
@@ -259,10 +261,6 @@ func (m Migrator) RenameTable(oldName, newName interface{}) error {
 		}
 	}
 
-	// TODO: Cannot rename a table that is referenced by a foreign key
-	// Disable the constraints for each referencing table before renaming,
-	// and recreate them after renaming
-
 	return m.DB.Exec("RENAME ? TO ?", oldTable, newTable).Error
 }
 
@@ -273,8 +271,7 @@ func (m Migrator) GetTables() (tableList []string, err error) {
 	return
 }
 
-// Columns
-// AddColumn create `name` column for value
+// AddColumn creates `name` column for the given `value`
 func (m Migrator) AddColumn(value interface{}, name string) error {
 	return m.RunWithValue(value, func(stmt *gorm.Statement) error {
 		// Check if the column name is already used
@@ -290,7 +287,7 @@ func (m Migrator) AddColumn(value interface{}, name string) error {
 	})
 }
 
-// DropColumn drop value's `name` column
+// DropColumn drops value's `name` column
 func (m Migrator) DropColumn(value interface{}, name string) error {
 	return m.RunWithValue(value, func(stmt *gorm.Statement) error {
 		if stmt.Schema != nil {
@@ -307,7 +304,7 @@ func (m Migrator) DropColumn(value interface{}, name string) error {
 	})
 }
 
-// AlterColumn alter value's `field` column's type based on schema definition
+// AlterColumn alters value's `field` column's type based on schema definition
 func (m Migrator) AlterColumn(value interface{}, field string) error {
 	return m.RunWithValue(value, func(stmt *gorm.Statement) error {
 		if stmt.Schema != nil {
@@ -326,7 +323,7 @@ func (m Migrator) AlterColumn(value interface{}, field string) error {
 	})
 }
 
-// HasColumn check has column `field` for value or not
+// HasColumn checks whether the table for the given value contains the specified column `field`
 func (m Migrator) HasColumn(value interface{}, field string) bool {
 	var count int64
 
@@ -340,7 +337,7 @@ func (m Migrator) HasColumn(value interface{}, field string) bool {
 	return count > 0
 }
 
-// ColumnTypes return columnTypes []gorm.ColumnType and execErr error
+// ColumnTypes returns the column types for the given value’s table and any error encountered during execution
 func (m Migrator) ColumnTypes(value interface{}) ([]gorm.ColumnType, error) {
 	columnTypes := make([]gorm.ColumnType, 0)
 	execErr := m.RunWithValue(value, func(stmt *gorm.Statement) (err error) {
@@ -370,7 +367,7 @@ func (m Migrator) ColumnTypes(value interface{}) ([]gorm.ColumnType, error) {
 	return columnTypes, execErr
 }
 
-// HasConstraint check has constraint or not
+// HasConstraint checks whether the table for the given `value` contains the specified constraint `name`
 func (m Migrator) HasConstraint(value interface{}, name string) bool {
 	var count int64
 
@@ -389,8 +386,7 @@ func (m Migrator) HasConstraint(value interface{}, name string) bool {
 	return count > 0
 }
 
-// Indexes
-// DropIndex drop index `name`
+// DropIndex drops the index with the specified `name` from the table associated with `value`
 func (m Migrator) DropIndex(value interface{}, name string) error {
 	return m.RunWithValue(value, func(stmt *gorm.Statement) error {
 		if stmt.Schema != nil {
@@ -403,7 +399,7 @@ func (m Migrator) DropIndex(value interface{}, name string) error {
 	})
 }
 
-// HasIndex check has index `name` or not
+// HasIndex checks whether the table for the given `value` contains an index with the specified `name`
 func (m Migrator) HasIndex(value interface{}, name string) bool {
 	var count int64
 	m.RunWithValue(value, func(stmt *gorm.Statement) error {
@@ -423,7 +419,7 @@ func (m Migrator) HasIndex(value interface{}, name string) bool {
 	return count > 0
 }
 
-// RenameIndex rename index from oldName to newName
+// RenameIndex renames index from oldName to newName on the table for the given `value`
 func (m Migrator) RenameIndex(value interface{}, oldName, newName string) error {
 	return m.RunWithValue(value, func(stmt *gorm.Statement) error {
 		return m.DB.Exec(
@@ -460,7 +456,7 @@ func (m Migrator) FullDataTypeOf(field *schema.Field) (expr clause.Expr) {
 	return expr
 }
 
-// Build Oracle-compatible default values from string
+// Builds Oracle-compatible default values from string
 func (m Migrator) buildOracleDefault(defaultValue string) string {
 	defaultValue = strings.TrimSpace(defaultValue)
 

oracle/oracle.go

@@ -72,15 +72,17 @@ type Dialector struct {
 	*Config
 }
 
-// Returns the name of the database dialect
+// Name returns the name of the database dialect
 func (d Dialector) Name() string {
 	return "oracle"
 }
 
+// Open creates a new godror Dialector with the given DSN
 func Open(dsn string) gorm.Dialector {
 	return &Dialector{Config: &Config{DriverName: "godror", DataSourceName: dsn}}
 }
 
+// New creates a new Dialector with the given config
 func New(config Config) gorm.Dialector {
 	return &Dialector{Config: &config}
 }
@@ -116,7 +118,7 @@ func (d Dialector) Initialize(db *gorm.DB) (err error) {
 	return nil
 }
 
-// Registers the migrator
+// Migrator returns the migrator instance associated with the given gorm.DB
 func (d Dialector) Migrator(db *gorm.DB) gorm.Migrator {
 	return Migrator{
 		Migrator: migrator.Migrator{

oracle/update.go

@@ -50,7 +50,29 @@ import (
 	"gorm.io/gorm/schema"
 )
 
-// Update callback function for Oracle
+// Update overrides GORM's update callback for Oracle.
+//
+// It builds Oracle-compatible UPDATE statements and supports:
+//
+//   - Standard updates without RETURNING using GORM’s default SQL build, with
+//     bind variable conversion for Oracle types.
+//   - Updates with RETURNING, emitting a PL/SQL block that performs
+//     UPDATE … RETURNING BULK COLLECT INTO for multi-row updates,
+//     wiring sql.Out binds for each returned column and row.
+//   - UPDATE safety: checks for missing WHERE conditions and refuses to run
+//     unless AllowGlobalUpdate is set or the WHERE clause has meaningful
+//     conditions (beyond soft-delete filters).
+//   - Primary key WHERE injection when the destination object or slice has
+//     identifiable PK values, to avoid unintended mass updates.
+//   - Soft-delete compatibility: conditions on deleted_at are ignored for the
+//     safety check, but preserved in the WHERE for the actual SQL.
+//
+// For updates with RETURNING, OUT bind results are mapped back into the
+// destination struct or slice using getUpdateReturningValues.
+//
+// Register with:
+//
+//	db.Callback().Update().Replace("gorm:update", oracle.Update)
 func Update(db *gorm.DB) {
 	if db.Error != nil || db.Statement == nil {
 		return

tests/associations_belongs_to_test.go

@@ -42,7 +42,7 @@ import (
 	"strings"
 	"testing"
 
-	. "github.com/oracle/gorm-oracle/tests/utils"
+	. "github.com/oracle-samples/gorm-oracle/tests/utils"
 
 	"gorm.io/gorm"
 	"gorm.io/gorm/utils/tests"

tests/associations_has_many_test.go

@@ -41,7 +41,7 @@ package tests
 import (
 	"testing"
 
-	. "github.com/oracle/gorm-oracle/tests/utils"
+	. "github.com/oracle-samples/gorm-oracle/tests/utils"
 
 	"gorm.io/gorm"
 )