What is Ballerina?
Swan Lake



import ballerinax/mssql;

Package overview

This package provides the functionality required to access and manipulate data stored in an MSSQL database.


Add the MSSQL driver JAR as a native library dependency in your Ballerina project's Ballerina.toml file. It is recommended to use a MSSQL driver version greater than 9.2.0 as this package uses the database properties from the MSSQL driver version 9.2.0 onwards.

Follow one of the following methods to add the JAR in the file:

  • Download the JAR and update the path.

    2path = "PATH"
  • Add JAR with the maven dependency params.

    2groupId = "com.microsoft.sqlserver"
    3artifactId = "mssql-jdbc"
    4version = "9.2.0.jre11"


To access a database, you must first create an mssql:Client object. The examples for creating an MSSQL client can be found below.

Creating a Client

These examples show the different methods of creating an mssql:Client.

The client can be created with an empty constructor, and thereby, will be initialized with the default properties.

1mssql:Client|sql:Error dbClient = new();

The mssql:Client receives the host, username, and password. Since the properties are passed in the same order as they are defined in the mssql:Client, you can pass them without named parameters.

1mssql:Client|sql:Error dbClient = new(
2 "localhost", "rootUser", "rootPass", "information_schema", 1443

The sample below shows an mssql:Client, which uses named parameters to pass the attributes since some parameters are skipped in the constructor. Further, the mssql:Options property is passed to configure the SSL and login timeout properties in the MSSQL client.

1mssql:Options mssqlOptions = {
2 secureSocket: {
3 encrypt: true,
4 cert: {
5 path: "trustStorePath",
6 password: "password"
7 }
8 },
9 loginTimeout: 10
12mssql:Client|sql:Error dbClient = new(
13 user = "rootUser", password = "rootPass", options = mssqlOptions

Similarly, in the sample below, the mssql:Client uses named parameters, and it provides an unshared connection pool of the sql:ConnectionPool type to be used within the client. For more details about connection pooling, see the sql Package.

1mssql:Client|sql:Error dbClient = new(
2 user = "rootUser", password = "rootPass",
3 connectionPool = {maxOpenConnections: 5}

Using SSL

To connect to the MSSQL database using an SSL connection, you must add the SSL configurations to the mssql:Options when creating the mssql:Client. The value of encrypt must be set to true. If trustServerCertificate is set to true, the client will not validate the server TLS/SSL certificate (used for testing in local environments). The key and cert files must be provided in the .p12 format.

1string clientStorePath = "/path/to/keystore.p12";
2string trustStorePath = "/path/to/truststore.p12";
4mssql:Options mssqlOptions = {
5 secureSocket: {
6 encrypt: true,
7 trustServerCertificate: false
8 key: {
9 path: clientStorePath,
10 password: "password"
11 },
12 cert: {
13 path: trustStorePath,
14 password: "password"
15 }
16 }

Connection Pool Handling

All database packages share the same connection pooling concept and there are three possible scenarios for connection pool handling. For its properties and possible values, see sql:ConnectionPool.

  1. Global, shareable, default connection pool

    If you do not provide the connectionPool field when creating the database client, a globally-shareable pool will be created for your database unless a connection pool matching with the properties you provided already exists.

    1mssql:Client|sql:Error dbClient = new ("localhost", "rootUser", "rootPass");
  2. Client-owned, unsharable connection pool

    If you define the connectionPool field inline when creating the client with the sql:ConnectionPool type, an unsharable connection pool will be created.

    1mssql:Client|sql:Error dbClient = new ("localhost", "rootUser", "rootPass",
    2 connectionPool = { maxOpenConnections: 5 });
  3. Local, shareable connection pool

    If you create a record of the sql:ConnectionPool type and reuse that in the configuration of multiple clients, for each set of clients that connects to the same database instance with the same set of properties, a shared connection pool will be created.

    1sql:ConnectionPool connPool = {maxOpenConnections: 5};
    3mssql:Client|sql:Error dbClient1 = new(
    4 "localhost", "rootUser", "rootPass", connectionPool = connPool
    6mssql:Client|sql:Error dbClient2 = new(
    7 "localhost", "rootUser", "rootPass", connectionPool = connPool
    9mssql:Client|sql:Error dbClient3 = new(
    10 "localhost", "rootUser", "rootPass", connectionPool = connPool

For more details about each property, see the mssql:Client constructor.

The mssql:Client references sql:Client and all the operations defined by the sql:Client will be supported by the mssql:Client as well.

Closing the Client

Once all the database operations are performed, you can close the client you have created by invoking the close() operation. This will close the corresponding connection pool if it is not shared by any other database clients.

1error? e = dbClient.close();


1check dbClient.close();

Database Operations

Once the client is created, database operations can be executed through that client. This package defines the interface and common properties that are shared among multiple database clients. It also supports querying, inserting, deleting, updating, and batch updating data.

Parameterized Query

The sql:ParameterizedQuery is used to construct the SQL query to be executed by the client. You can create a query with constant or dynamic input data as follows.

Query with constant values

1sql:ParameterizedQuery query = `SELECT * FROM students
2 WHERE id < 10 AND age > 12`;

Query with dynamic values

1int[] ids = [10, 50];
2int age = 12;
3sql:ParameterizedQuery query = `SELECT * FROM students
4 WHERE id < ${ids[0]} AND age > ${age}`;

Moreover, the SQL package has sql:queryConcat() and sql:arrayFlattenQuery() util functions which make it easier to create a dynamic/constant complex query.

The sql:queryConcat() is used to create a single parameterized query by concatenating a set of parameterized queries. The sample below shows how to concatenate queries.

1int id = 10;
2int age = 12;
3sql:ParameterizedQuery query = `SELECT * FROM students`;
4sql:ParameterizedQuery query1 = ` WHERE id < ${id} AND age > ${age}`;
5sql:ParameterizedQuery sqlQuery = sql:queryConcat(query, query1);

A query with the IN operator can be created using the sql:ParameterizedQuery as shown below. Here, you need to flatten the array and pass each element separated by a comma.

1int[] ids = [1, 2, 3];
2sql:ParameterizedQuery query = `SELECT count(*) as total FROM DataTable
3 WHERE row_id IN (${ids[0]}, ${ids[1]}, ${ids[2]})`;

The sql:arrayFlattenQuery() util function is used to make the array flattening easier. It makes the inclusion of varying array elements into the query easier by flattening the array to return a parameterized query. You can construct the complex dynamic query with the IN operator by using both functions as shown below.

1int[] ids = [1, 2];
2sql:ParameterizedQuery sqlQuery =
3 sql:queryConcat(`SELECT * FROM DataTable WHERE id IN (`,
4 sql:arrayFlattenQuery(ids), `)`);

Creating Tables

This sample creates a table with three columns. The first column is a primary key of type int while the second column is of type int and the other is of type varchar. The CREATE statement is executed via the execute remote function of the client.

1// Create the ‘Students’ table with the ‘id’, ’age’, and ’name’ fields.
2sql:ExecutionResult result =
3 check dbClient->execute(`CREATE TABLE student (
5 age INT,
6 name VARCHAR(255),
8 )`);
9// A value of the sql:ExecutionResult type is returned for 'result'.

Inserting Data

These samples show the data insertion by executing an INSERT statement using the execute remote function of the client.

In this sample, the query parameter values are passed directly into the query statement of the execute remote function.

1sql:ExecutionResult result = check dbClient->execute(`INSERT INTO student(age, name)
2 VALUES (23, 'john')`);

In this sample, the parameter values, which are assigned to local variables are used to parameterize the SQL query in the execute remote function. This type of parameterized SQL query can be used with any primitive Ballerina type such as string, int, float, or boolean and in that case, the corresponding SQL type of the parameter is derived from the type of the Ballerina variable that is passed.

1string name = "Anne";
2int age = 8;
4sql:ParameterizedQuery query = `INSERT INTO student(age, name)
5 VALUES (${age}, ${name})`;
6sql:ExecutionResult result = check dbClient->execute(query);

In this sample, the parameter values are passed as an sql:TypedValue to the execute remote function. Use the corresponding subtype of the sql:TypedValue such as sql:VarcharValue, sql:CharValue, sql:IntegerValue, etc., when you need to provide more details such as the exact SQL type of the parameter.

1sql:VarcharValue name = new ("James");
2sql:IntegerValue age = new (10);
4sql:ParameterizedQuery query = `INSERT INTO student(age, name)
5 VALUES (${age}, ${name})`;
6sql:ExecutionResult result = check dbClient->execute(query);

Inserting Data With Auto-generated Keys

This sample demonstrates inserting data while returning the auto-generated keys. It achieves this by using the execute remote function to execute the INSERT statement.

1int age = 31;
2string name = "Kate";
4sql:ParameterizedQuery query = `INSERT INTO student(age, name)
5 VALUES (${age}, ${name})`;
6sql:ExecutionResult result = check dbClient->execute(query);
8// Number of rows affected by the execution of the query.
9int? count = result.affectedRowCount;
11// The integer or string generated by the database in response to a query execution.
12string|int? generatedKey = result.lastInsertId;

Querying Data

These samples show how to demonstrate the different usages of the query operation to query the database table and obtain the results.

This sample demonstrates querying data from a table in a database. First, a type is created to represent the returned result set. This record can be defined as an open or a closed record according to the requirement. If an open record is defined, the returned stream type will include both defined fields in the record and additional database columns fetched by the SQL query, which are not defined in the record.

Note: the mapping of the database column to the returned record's property is case-insensitive if it is defined in the record(i.e., the ID column in the result can be mapped to the id property in the record). Additional column names are added to the returned record as in the SQL query. If the record is defined as a closed record, only the defined fields in the record are returned or gives an error when additional columns are present in the SQL query.

Next, the SELECT query is executed via the query remote function of the client. Once the query is executed, each data record can be retrieved by iterating through the result set. The stream returned by the SELECT operation holds a pointer to the actual data in the database, and it loads data from the table only when it is accessed. This stream can be iterated only once.

1// Define an open record type to represent the results.
2type Student record {
3 int id;
4 int age;
5 string name;
8// Select the data from the database table. The query parameters are passed
9// directly. Similar to the `execute` samples, parameters can be passed as
10// sub types of `sql:TypedValue` as well.
11int id = 10;
12int age = 12;
13sql:ParameterizedQuery query = `SELECT * FROM students
14 WHERE id < ${id} AND age > ${age}`;
15stream<Student, sql:Error?> resultStream = dbClient->query(query);
17// Iterating the returned table.
18check from Student student in resultStream
19 do {
20 // Can perform operations using the record 'student' of type `Student`.
21 };

Defining the return type is optional, and you can query the database without providing the result type. Hence, the above sample can be modified as follows with an open record type as the return type. The property name in the open record type will be the same as how the column is defined in the database.

1// Select the data from the database table. The query parameters are passed
2// directly. Similar to the `execute` samples, parameters can be passed as
3// sub types of `sql:TypedValue` as well.
4int id = 10;
5int age = 12;
6sql:ParameterizedQuery query = `SELECT * FROM students
7 WHERE id < ${id} AND age > ${age}`;
8stream<record{}, sql:Error?> resultStream = dbClient->query(query);
10// Iterating the returned table.
11check from record{} student in resultStream
12 do {
13 // Can perform operations using the record 'student'.
14 io:println("Student name: ", student.value["name"]);
15 };

There are situations in which you may not want to iterate through the database and in that case, you may decide to use the queryRow() operation. If the provided return type is a record, this method returns only the first row retrieved by the query as a record.

1int id = 10;
2sql:ParameterizedQuery query = `SELECT * FROM students WHERE id = ${id}`;
3Student retrievedStudent = check dbClient->queryRow(query);

The queryRow() operation can also be used to retrieve a single value from the database (e.g., when querying using COUNT() and other SQL aggregation functions). If the provided return type is not a record (i.e., a primitive data type) , this operation will return the value of the first column of the first row retrieved by the query.

1int age = 12;
2sql:ParameterizedQuery query = `SELECT COUNT(*) FROM students WHERE age < ${age}`;
3int youngStudents = check dbClient->queryRow(query);

Updating Data

This sample demonstrates modifying data by executing an UPDATE statement via the execute remote function of the client.

1int age = 23;
2sql:ParameterizedQuery query = `UPDATE students SET name = 'John' WHERE age = ${age}`;
3sql:ExecutionResult result = check dbClient->execute(query);

Deleting Data

This sample demonstrates deleting data by executing a DELETE statement via the execute remote function of the client.

1string name = "John";
2sql:ParameterizedQuery query = `DELETE from students WHERE name = ${name}`;
3sql:ExecutionResult result = check dbClient->execute(query);

Batch Updating Data

This sample demonstrates how to insert multiple records with a single INSERT statement that is executed via the batchExecute remote function of the client. This is done by creating a table with multiple records and parameterized SQL query as same as the above execute operations.

1// Create the table with the records that need to be inserted.
2var data = [
3 { name: "John", age: 25 },
4 { name: "Peter", age: 24 },
5 { name: "jane", age: 22 }
8// Do the batch update by passing the batches.
9sql:ParameterizedQuery[] batch = from var row in data
10 select `INSERT INTO students ('name', 'age')
11 VALUES (${row.name}, ${row.age})`;
12sql:ExecutionResult[] result = check dbClient->batchExecute(batch);

Execute SQL Stored Procedures

This sample demonstrates how to execute a stored procedure with a single INSERT statement that is executed via the call remote function of the client.

1int uid = 10;
2sql:IntegerOutParameter insertId = new;
4sql:ProcedureCallResult result =
5 check dbClient->call(`call InsertPerson(${uid}, ${insertId})`);
6stream<record{}, sql:Error?>? resultStr = result.queryResult;
7if resultStr is stream<record{}, sql:Error?> {
8 check from record{} result in resultStr
9 do {
10 // Can perform operations using the record 'result'.
11 };
13check result.close();

Note that you have to invoke the close operation explicitly on the sql:ProcedureCallResult to release the connection resources and avoid a connection leak as shown above.

Note: The default thread pool size used in Ballerina is: the number of processors available * 2. You can configure the thread pool size by using the BALLERINA_MAX_POOL_SIZE environment variable.

Report Issues

To report bugs, request new features, start new discussions, view project boards, etc., go to the Ballerina standard library parent repository.

Useful Links

Exported modules


License: Apache-2.0

Created date: 01 March,2022

Ballerina compatibility

Platform: java11

Ballerina version: 2201.0.1










Other versions