The Oracle Database Multilingual Engine (MLE) enables JavaScript execution in Oracle Database. In this database JavaScript environment, there exist some JavaScript modules that are available out of the box. This repository contains documentation and interface definitions (in the form of TypeScript declarations) for those predefined modules. While the documentation contains set of human-readable, linked pages, the TypeScript declaration files are typically consumed by an IDE for improving auto-completion. This is particularly useful in a scenario where JavaScript code gets developed locally in an IDE and then deployed to the database.
The following JavaScript modules are currently available:
- 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
You need an Oracle Database to make use of the JavaScript modules provided in the Oracle Database Multilingual Engine (MLE). A very convenient way of getting an Oracle Database instance is to create an always-free Oracle Cloud account and set up a free autonomous database instance there as our blog article explains in great detail.
You can install all relevant declarations of these modules plus the declarations of all global symbols (Polyglot, console, session, soda, oracledb, OracleNumber, etc.) in one bundle.
You can conveniently install mle-js from NPM and then reference it in the beginning of your JavaScript code using the <reference> tag:
npm install mle-js
/// <reference types="mle-js" />
If you only need declarations of a particular module, you can also just install them individually:
npm install mle-js-oracledb
npm install mle-js-bindings
npm install mle-js-plsqltypes
npm install mle-js-fetch
This bundle contains all relevant declarations of predefined JavaScript modules that ship with the database plus the declarations of all global symbols.
If JavaScript is executed inside the database, SQL statements can be executed using an easy to use SQL driver. This driver is built-in into the JavaScript engine in the database.
The MLE Bindings module can be used to exchange values between PL/SQL and JavaScript. 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 get converted to JavaScript values during that process, e.g. an Oracle NUMBER gets 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.
Oracle Database is the world's most popular database. Available on cloud and on-premises platforms, Oracle Database 19c is the most recent long term release, with an extended support window. Oracle Database 21c is the latest innovation release, initially available on Oracle cloud through Autonomous Database Free Tier and Database Cloud Service.
The following table shows which version of module documentation and declarations work with which version of Oracle Database:
| Oracle Database | Modules |
|---|---|
| 23c | [email protected] [email protected] [email protected] [email protected] [email protected] |
| 21c | [email protected] [email protected] [email protected] |
The following code snippet exemplifies the usage of some of these MLE modules combined. For additional examples, please check the module documentation pages or have a look at our blog article.
// imports
const oracledb = require('mle-js-oracledb');
const bindings = require('mle-js-bindings');
const plsqltypes = require("mle-js-plsqltypes");
// Read a large number as an Oracle NUMBER from SQL and add another ORACLE NUMBER to it.
// mle-js-oracledb is used for reading from SQL and mle-js-plsqltypes is used to construct the second Oracle NUMBER.
const conn = oracledb.defaultConnection();
const query = "SELECT 9007199254740992 AS n FROM dual";
const options = { fetchInfo: { N: { type: oracledb.ORACLE_NUMBER } } };
const queryResult = conn.execute(query, [], options);
const OracleNumber = plsqltypes.OracleNumber;
const result = queryResult.rows[0][0].add(new OracleNumber(7));
// Use mle-js-bindings to export the result of the computation.
// On the database side, this result could be retrieved using something like `dbms_mle.import_from_mle(ctx, 'result', result);`.
bindings.exportValue("result", result);If you have questions or change requests about MLE, please create a ticket or contact Oracle Support.
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 Oracle and/or its affiliates.
Released under the Universal Permissive License v1.0 as shown at https://oss.oracle.com/licenses/upl/.