refactor: Rename execute function to sqlExecute and update documentation

- Renamed the `execute` function to `sqlExecute` for clarity and consistency.
- Updated all references in the README, example scripts, and tests to reflect the new function name.
- Enhanced documentation to provide clearer usage examples for SQL execution functions.

Signed-off-by: Edmund Miller <[email protected]>

Co-authored-by: Edmund Miller <[email protected]>
Co-authored-by: Paolo Di Tommaso <[email protected]>

Author: edmundmiller

README.md

@@ -131,15 +131,15 @@ The following options are available:
 
 This plugin provides the following functions for executing SQL statements that don't return data, such as DDL (Data Definition Language) and DML (Data Manipulation Language) operations.
 
-### execute
+### sqlExecute
 
-The `execute` function executes a SQL statement that doesn't return a result set, such as `CREATE`, `ALTER`, `DROP`, `INSERT`, `UPDATE`, or `DELETE` statements. For example:
+The `sqlExecute` function executes a SQL statement that doesn't return a result set, such as `CREATE`, `ALTER`, `DROP`, `INSERT`, `UPDATE`, or `DELETE` statements. For example:
 
 ```nextflow
-include { execute } from 'plugin/nf-sqldb'
+include { sqlExecute } from 'plugin/nf-sqldb'
 
 // Create a table
-execute(
+sqlExecute(
     db: 'foo',
     statement: '''
         CREATE TABLE IF NOT EXISTS sample_table (
@@ -151,13 +151,13 @@ execute(
 )
 
 // Insert data
-execute(
+sqlExecute(
     db: 'foo',
     statement: "INSERT INTO sample_table (id, name, value) VALUES (1, 'alpha', 10.5)"
 )
 
 // Delete data
-execute(
+sqlExecute(
     db: 'foo',
     statement: "DELETE FROM sample_table WHERE id = 1"
 )
@@ -173,7 +173,7 @@ The following options are available:
 
 ### executeUpdate
 
-The `executeUpdate` function is similar to `execute`, but it returns the number of rows affected by the SQL statement. This is particularly useful for DML operations like `INSERT`, `UPDATE`, and `DELETE` where you need to know how many rows were affected. For example:
+The `executeUpdate` function is similar to `sqlExecute`, but it returns the number of rows affected by the SQL statement. This is particularly useful for DML operations like `INSERT`, `UPDATE`, and `DELETE` where you need to know how many rows were affected. For example:
 
 ```nextflow
 include { executeUpdate } from 'plugin/nf-sqldb'
@@ -216,8 +216,8 @@ The plugin provides two different ways to interact with databases:
    - `fromQuery`: Queries data from a database and returns a channel that emits the results.
    - `sqlInsert`: Takes data from a channel and inserts it into a database.
 
-2. **Execution Functions** (`execute` and `executeUpdate`): These are designed for direct SQL statement execution that doesn't require channel integration.
-   - `execute`: Executes a SQL statement without returning any data.
+2. **Execution Functions** (`sqlExecute` and `executeUpdate`): These are designed for direct SQL statement execution that doesn't require channel integration.
+   - `sqlExecute`: Executes a SQL statement without returning any data.
    - `executeUpdate`: Executes a SQL statement and returns the count of affected rows.
 
 Use **Dataflow Operators** when you need to:

examples/sql-execution/main.nf

@@ -1,10 +1,10 @@
 #!/usr/bin/env nextflow
 
 /*
- * Example script demonstrating how to use the SQL execute and executeUpdate functions
+ * Example script demonstrating how to use the SQL sqlExecute and executeUpdate functions
  */
 
-include { execute; executeUpdate } from 'plugin/nf-sqldb'
+include { sqlExecute; executeUpdate } from 'plugin/nf-sqldb'
 include { fromQuery } from 'plugin/nf-sqldb'
 
 // Define database configuration in nextflow.config file

plugins/nf-sqldb/src/main/nextflow/sql/ChannelSqlExtension.groovy

@@ -149,8 +149,8 @@ class ChannelSqlExtension extends PluginExtensionPoint {
      * @param params A map containing 'db' (database alias) and 'statement' (SQL string to execute)
      */
     @Function
-    void execute(Map params) {
-        CheckHelper.checkParams('execute', params, EXECUTE_PARAMS)
+    void sqlExecute(Map params) {
+        CheckHelper.checkParams('sqlExecute', params, EXECUTE_PARAMS)
 
         final String dbName = params.db as String ?: 'default'
         final String statement = params.statement as String

plugins/nf-sqldb/src/main/nextflow/sql/QueryHandler.groovy

@@ -52,11 +52,11 @@ class QueryHandler implements QueryOp<QueryHandler> {
         type_mapping.TINYINT = Byte
         type_mapping.SMALLINT = Short
         type_mapping.INTEGER = Integer
-        type_mapping.BIGINT	= Long
+        type_mapping.BIGINT    = Long
         type_mapping.REAL= Float
         type_mapping.FLOAT= Double
-        type_mapping.DOUBLE	= Double
-        type_mapping.BINARY	= byte[]
+        type_mapping.DOUBLE    = Double
+        type_mapping.BINARY    = byte[]
         type_mapping.VARBINARY = byte[]
         type_mapping.LONGVARBINARY= byte[]
         type_mapping.DATE = java.sql.Date

plugins/nf-sqldb/src/test/nextflow/sql/SqlExecutionTest.groovy

@@ -53,7 +53,7 @@ class SqlExecutionTest extends Specification {
         sqlExtension.init(session)
 
         when: 'Creating a table'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'CREATE TABLE test_table(id INT PRIMARY KEY, name VARCHAR(255))'
         ])
@@ -62,7 +62,7 @@ class SqlExecutionTest extends Specification {
         sql.rows('SELECT 1 FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = \'TEST_TABLE\'').size() > 0
 
         when: 'Altering the table'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'ALTER TABLE test_table ADD COLUMN description VARCHAR(255)'
         ])
@@ -71,7 +71,7 @@ class SqlExecutionTest extends Specification {
         sql.rows('SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = \'TEST_TABLE\' AND COLUMN_NAME = \'DESCRIPTION\'').size() > 0
 
         when: 'Dropping the table'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'DROP TABLE test_table'
         ])
@@ -96,7 +96,7 @@ class SqlExecutionTest extends Specification {
         sqlExtension.init(session)
 
         when: 'Inserting data'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'INSERT INTO test_dml (id, name, value) VALUES (1, \'item1\', 100)'
         ])
@@ -106,7 +106,7 @@ class SqlExecutionTest extends Specification {
         sql.firstRow('SELECT * FROM test_dml WHERE id = 1').name == 'item1'
 
         when: 'Updating data'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'UPDATE test_dml SET value = 200 WHERE id = 1'
         ])
@@ -115,7 +115,7 @@ class SqlExecutionTest extends Specification {
         sql.firstRow('SELECT value FROM test_dml WHERE id = 1').value == 200
 
         when: 'Deleting data'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'DELETE FROM test_dml WHERE id = 1'
         ])
@@ -186,7 +186,7 @@ class SqlExecutionTest extends Specification {
         sqlExtension.init(session)
 
         when: 'Executing invalid SQL'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'INVALID SQL STATEMENT'
         ])
@@ -195,7 +195,7 @@ class SqlExecutionTest extends Specification {
         thrown(Exception)
 
         when: 'Executing query with invalid table name'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'SELECT * FROM non_existent_table'
         ])
@@ -213,7 +213,7 @@ class SqlExecutionTest extends Specification {
         sqlExtension.init(session)
 
         when: 'Using non-existent database alias'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'non_existent_db',
             statement: 'SELECT 1'
         ])
@@ -222,15 +222,15 @@ class SqlExecutionTest extends Specification {
         thrown(IllegalArgumentException)
 
         when: 'Missing statement parameter'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test'
         ])
 
         then: 'Should throw an IllegalArgumentException'
         thrown(IllegalArgumentException)
 
         when: 'Empty statement parameter'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: ''
         ])
@@ -252,7 +252,7 @@ class SqlExecutionTest extends Specification {
         sqlExtension.init(session)
 
         when: 'Executing statement without semicolon'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'CREATE TABLE test_norm(id INT PRIMARY KEY)'
         ])
@@ -261,7 +261,7 @@ class SqlExecutionTest extends Specification {
         sql.rows('SELECT 1 FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = \'TEST_NORM\'').size() > 0
 
         when: 'Executing statement with trailing whitespace'
-        sqlExtension.execute([
+        sqlExtension.sqlExecute([
             db: 'test',
             statement: 'DROP TABLE test_norm  '
         ])

plugins/nf-sqldb/src/testResources/testDir/test_sql_db.nf

@@ -1,13 +1,13 @@
 nextflow.enable.dsl=2
 
-include { fromQuery; sqlInsert; execute; executeUpdate } from 'plugin/nf-sqldb'
+include { fromQuery; sqlInsert; sqlExecute; executeUpdate } from 'plugin/nf-sqldb'
 
 workflow {
     // Setup: create table
-    execute(
+    sqlExecute(
         db: 'foo',
         statement: '''
-            CREATE TABLE IF NOT EXISTS sample_table (
+            CREATE TABLE IF NOT EXISTS testing (
                 id INTEGER PRIMARY KEY,
                 name VARCHAR(100),
                 value DOUBLE