Oracle's Multilingual Engine (MLE), powered by GraalVM, enables JavaScript execution in Oracle Database. Oracle's JavaScript implementation ships with a number of essential JavaScript modules.
This repository contains documentation and interface definitions (in the form of TypeScript declarations) for those predefined modules. While the documentation consists of human-readable, linked pages, the TypeScript declaration files are typically consumed by an IDE. Developers using Oracle's SQL Developer Extension for Visual Studio Code for example benefit from a better developer experience thanks to code-completion, and Typescript checks.
The following JavaScript modules are currently available with Oracle's latest database release:
- MLE SQL Driver: mle-js-oracledb
- MLE Bindings: mle-js-bindings
- MLE PL/SQL Types: mle-js-plsqltypes
- MLE Fetch API polyfill: mle-js-fetch
- MLE Base64 Encoding: mle-encode-base64
- MLE Encodings: mle-js-encodings
- MLE Foreign Function Interface (FFI): mle-js-plsql-ffi
Apart from the modules shipping with the database listed above, you can optionally install modules from community repositories into the database after carefully vetting them with the relevant teams in your organisation.
This section details the both the installing and how to use the supplied typescript declarations in your Project.
You need access to an Oracle Database 23ai system running either on Linux x86-64 or aarch64 to make use of the JavaScript modules provided in Oracle Database Multilingual Engine (MLE). Developers wishing to experiment with MLE can choose from cloud solutions such as Oracle's Always-Free Autonomous Database (Serverless) see this blog article or use the container images available from container-registry.oracle.com. You can find more details described in this blog post.
The following sections describe how to use the Typescript declarations with your project.
You can install all relevant module declarations including the declarations of all global symbols (Polyglot, console, session, soda, oracledb, OracleNumber, etc.) in one bundle. You can conveniently install mle-js using Node Package Manager (NPM) or a comparable tool.
Once the declarations have been downloaded and configured you can use them in your Typescript project using the <reference> tag as shown:
/// <reference types="mle-js" />
/* more Typescript code ... */Provided your project's tsconfig.json has been configured correctly you should immediately see a benefit when writing server-side JavaScript code.
If you only need declarations of a particular module, you may also install declarations individually:
npm install mle-js-oracledb
npm install mle-js-bindings
npm install mle-js-plsqltypes
npm install mle-js-fetch
npm install mle-encode-base64
npm install mle-js-encodings
npm install mle-js-plsql-ffiThe following sections cover each declaration file's content, the module it documents, and what you can expect when referencing them in your code.
This bundle contains all relevant declarations of predefined JavaScript modules that ship with the database plus the declarations of all global symbols. Most users should start with this file
You use the SQL Driver to interact with the database. You can perform any operation with the MLE SQL Driver that you would SQL and PL/SQL for. If you prefer a more JavaScript-like experience working with the Database API see PL/SQL Packages and Types Reference you should also have a look at the Foreign Function Interface (FFI) below.
The MLE Bindings module can be used to exchange values between PL/SQL and JavaScript and is mostly used for Dynamic MLE Execution based on DBMS_MLE.
The module also takes care of converting values from PL/SQL types to JavaScript types and vice-versa automatically as required.
MLE allows importing SQL values from PL/SQL as well as fetching them from a SQL statement.
By default, SQL values are converted to JavaScript values during that process, e.g. an Oracle NUMBER is implicitly converted to a JavaScript number.
Sometimes it is required to have JavaScript values that behave exactly as if they were SQL values.
The mle-js-plsqltypes module contains JavaScript APIs for such JavaScript objects that wrap PL/SQL objects.
MLE offers the following functionality to fetch and upload resources asynchronously across the network: fetch, Headers, Request, Response. In order to make the Fetch API available, it needs to be imported first.
This module contains code to work with base64-encoded data.
This module is a partial implementation of the Encoding API. By default, TextDecoder and TextEncoder are available in the global namespace and can be used directly.
MLE Foreign Function Interface (FFI): API for calling PL/SQL functionality directly (mle-js-plsql-ffi)
This module offers a simple, straight-forward way for interacting with PL/SQL code from within JavaScript.
The following table shows which version of module documentation and declarations work with which version of Oracle Database:
| Oracle Database | Declarations | Documentation |
|---|---|---|
| 23ai | [email protected] for Oracle 23.7 [email protected] for Oracle 23.6 [email protected] for Oracle 23.5 [email protected] for Oracle 23.4 [email protected] for Oracle 23.3 [email protected] for Oracle 23.2 - Free |
mle-js (23ai) mle-js-oracledb (23ai) mle-js-bindings (23ai) mle-js-plsqltypes (23ai) mle-js-fetch (23ai) mle-encode-base64 (23ai) |
| 21c | [email protected] | mle-js-oracledb (21c) mle-js-bindings (21c) mle-js-plsqltypes (21c) |
This section describes how to use the Typescript declarations with MLE/JavaScript as well as some interactive, ad-hoc JavaScript execution.
Using the Typescript declarations you can create an MLE module as follows.
/// <reference types="mle-js" />
interface ISessionMetaData {
username: string;
oracleVersion: string;
}
/**
* A simple JavaScript function fetches the username and database
* release using the MLE JavaScript SQL driver.
*
* @returns an instance of ISessionMetaData
*/
export function sessionAndDBInfo(): ISessionMetaData {
// instantiate the session meta data
const mySession: ISessionMetaData = {
username: "unknown",
oracleVersion: "unknown",
};
let sql = `select
user`;
let result = session.execute(sql, [], { outFormat: oracledb.OUT_FORMAT_OBJECT });
if (result.rows?.length === 1) {
mySession.username = result.rows[0].USER;
}
sql = `select
version_full
from
product_component_version`;
result = session.execute(sql, [], { outFormat: oracledb.OUT_FORMAT_OBJECT });
if (result.rows?.length === 1) {
mySession.oracleVersion = result.rows[0].VERSION_FULL;
}
return mySession;
}In the next step you need to transpile the Typescript code to JavaScript. The resulting file can be imported to the Oracle database. SQL Command Line provides a nice way to do that
$ sql /nolog
SQLcl: Release 24.3 Production on Wed Jan 15 14:16:01 2025
Copyright (c) 1982, 2025, Oracle. All rights reserved.
SQL> connect app_user@localhost:5432/freepdb1
Password? (**********?) ***********
Connected.
SQL> mle create-module -filename ./dist/demo.js -module-name demo_module
MLE Module demo_module created
The following snippet can be run in SQLcl, SQL*Plus, and Oracle SQL Developer Extension for Visual Studio Code. The invocation of the SQL code differs from the Typescript example by using the objects stored in the global scope.
set serveroutput on;
declare
l_ctx dbms_mle.context_handle_t;
l_source_code clob;
begin
-- Create execution context for MLE execution and provide an environment_
l_ctx := dbms_mle.create_context();
-- using q-quotes to avoid problems with unwanted string termination
l_source_code :=
q'~
const result = session.execute(
`select 'hello, world'`,
[],
{
outFormat: oracledb.OUT_FORMAT_ARRAY
}
);
const message = result.rows[0][0];
console.log(message);
~';
dbms_mle.eval(
context_handle => l_ctx,
language_id => 'JAVASCRIPT',
source => l_source_code
);
dbms_mle.drop_context(l_ctx);
exception
when others then
dbms_mle.drop_context(l_ctx);
raise;
end;
/If you plan to use database-side JavaScript at a larger scale, we highly recommend to read our blog post on Linting MLE JavaScript Modules in Continuous Integration Pipelines.
- Oracle 23.7
- MLE Foreign Function Interface (FFI) for calling PL/SQL functionality directly from JavaScript: mle-js-plsql-ffi
- support for setting the fetchTypeHandler
in
mle-js-oracledb/session.executefor custom handler functions during result fetching
- Oracle 23.6
- improved documentation for OracleNumber infix operators.
- Oracle 23.5
- support for
sql-template-tag
in SQL execution in
mle-js-oracledb/session.executeby allowing the first argument to be of new type IExecuteArgs
- support for
sql-template-tag
in SQL execution in
- Oracle 23.4 (first release of Oracle 23ai)
- support for VECTOR type (INT8ARRAY, FLOAT32ARRAY, FLOAT64, DB_TYPE_VECTOR) in mle-js-oracledb and mle-js-bindings including new vectorDimensions and vectorFormat meta data properties
- support for binding collection types, including new properties
elementTypeClass
and
packageName
of
DBObjectClassand maxArraySize of bind definitions inmle-js-oracledb. - support for
keepInStmtCache
option in SQL execution in
mle-js-oracledb/session.execute
If you have questions or change requests about MLE, please create a ticket or contact Oracle Support. Users of Oracle Database 23ai Free can refer to the Database Free forum.
This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide.
Please consult the security guide for our responsible security vulnerability disclosure process.
Copyright (c) 2022, 2025, Oracle and/or its affiliates.
Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.