Add support for init parameters in the generated client

[TharmiganK]

Purpose

Introduces support for individual initialization parameters in Ballerina persist clients as an alternative to the existing module-level configurable-based approach. This enables better client reusability and improves developer experience, particularly in low-code environments.

Key improvements:

• Enables initializing persist clients with different configurations without code duplication
• Makes database connection parameters explicit and self-documenting
• Improves low-code developer experience by clearly associating parameters with client initialization
• Maintains full backward compatibility with existing configurable-based approach

Fixes: ballerina-platform/ballerina-library#8505

Examples

CLI Usage

Generate persist client with individual init parameters:

bal persist generate --datastore mysql --module entities --with-init-params

Add persist configuration with init parameters to project:

bal persist add --datastore mysql --module entities --with-init-params

Generated Code

Before (configurable-based):

// Generated module-level configurables
configurable string host = ?;
configurable int port = ?;
configurable string user = ?;
configurable string password = ?;
configurable string database = ?;

// Generated init function
public function init() returns Client|error {
    final mysql:Client dbClient = check new ();  // Uses configurables internally
    return new (dbClient);
}

After (with --with-init-params):

// Generated init function with explicit parameters
public function init(
    string host,
    int port,
    string user,
    string password,
    string database,
    mysql:Options connectionOptions = {}
) returns Client|error {
    final mysql:Client dbClient = check new (host, port, user, password, database, connectionOptions);
    return new (dbClient);
}

Usage in Application Code

Single database connection:

import myapp/entities;

public function main() returns error? {
    entities:Client db = check entities:init(
        host = "localhost",
        port = 3306,
        user = "admin",
        password = "secure_password",
        database = "production_db"
    );
    
    stream<entities:User, error?> users = db->/users();
    check users.forEach(user => io:println(user));
}

Multiple database connections with different configurations:

import myapp/entities;

public function main() returns error? {
    // Primary database
    entities:Client primaryDb = check entities:init(
        host = "primary.db.example.com",
        port = 3306,
        user = "app_user",
        password = getPrimaryPassword(),
        database = "production"
    );
    
    // Read replica
    entities:Client replicaDb = check entities:init(
        host = "replica.db.example.com",
        port = 3306,
        user = "readonly_user",
        password = getReplicaPassword(),
        database = "production"
    );
    
    // Use different connections for different operations
    stream<entities:User, error?> users = primaryDb->/users();
    // ... perform operations
}

PostgreSQL with schema parameter:

import myapp/entities;

public function main() returns error? {
    entities:Client db = check entities:init(
        host = "localhost",
        port = 5432,
        username = "admin",
        password = "secure_password",
        database = "mydb",
        defaultSchema = "public"
    );
}

Build Integration

When using bal persist add --with-init-params, the Ballerina.toml is updated with:

[[tool.persist]]
id = "generate-db-client"
targetModule = "myapp.entities"
options.datastore = "mysql"
options.withInitParams = true
filePath = "persist/model.bal"

This ensures bal build regenerates the client with the correct initialization approach.

Files NOT Generated

When using --with-init-params, the following files are not generated:

• Config.toml - No external configuration file
• persist_db_config.bal - No module-level configurables

This reduces deployment complexity and makes the initialization approach explicit in the code.

Checklist

• Linked to an issue
• Updated the specification
• Updated the changelog
• Added tests

[codecov]

Codecov Report

❌ Patch coverage is 80.29197% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.82%. Comparing base (21ac485) to head (d8b6399).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...allerina/persist/cmd/PersistCodeGeneratorTool.java	0.00%	7 Missing ⚠️
...java/io/ballerina/persist/components/Function.java	0.00%	7 Missing ⚠️
...t/nodegenerator/syntax/clients/DbClientSyntax.java	91.66%	4 Missing and 3 partials ⚠️
...c/main/java/io/ballerina/persist/cmd/Generate.java	50.00%	2 Missing ⚠️
...llerina/persist/nodegenerator/SourceGenerator.java	88.88%	0 Missing and 2 partials ⚠️
...ist/nodegenerator/syntax/sources/DbSyntaxTree.java	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #435      +/-   ##
==========================================
- Coverage   85.96%   85.82%   -0.14%     
==========================================
  Files          68       68              
  Lines        6596     6667      +71     
  Branches      881      890       +9     
==========================================
+ Hits         5670     5722      +52     
- Misses        662      677      +15     
- Partials      264      268       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.5% Duplication on New Code

See analysis details on SonarQube Cloud