feat: add MLE application template #257

DimaNike · 2025-04-08T12:16:16Z

[PR] [Enhancement] MLE application template #255

## Description
mle-app template can be used to generate MLE basic application that can be built and deployed to the database. Database credentials should be provided via existing mechanism by answering questions during the application creation process. In addition, MLE application template requires SQLcl path to be specified.

Fixes #255

## Type of change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?
Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

- [ ] Test A
- [ ] Test B

## Checklist:
- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings/errors
- [n/a] I have added tests that prove my fix is effective or that my feature works
- [n/a] New and existing unit tests pass locally with my changes

dbtools-antcampo · 2025-04-24T22:53:39Z

templates/mle-js-basic/.env.example.wallet

+# Database User Password
+DB_PASSWORD=<%= connectionPassword %>
+# Connection string to your Autonomous Database/
+# Oracle Database Free instance


This might create confusion for users since the connection will not necessarily be to a free DB instance.

Changed to "Oracle Database instance"

dbtools-antcampo · 2025-04-24T22:55:14Z

templates/mle-js-basic/.env.example.wallet

+# Connection string to your Autonomous Database/
+# Oracle Database Free instance
+CONNECT_STRING=<%= connectionString %>
+MLE_MODULE=


This variable is empty and does not have a replacement token, is this expected?

Yes, this variable is updated after npm run deploy is executed. We need to keep this for the tests in case user provided custom MLE module name.

dbtools-antcampo · 2025-04-24T23:11:36Z

src/index.ts

@@ -207,7 +207,7 @@ export default class Generate extends Command {
        'template': Flags.string({ 
            char: 't', 
            description: 'Template to use',
-            options: ['node-vanilla', 'node-react', 'node-vue', 'node-react-todo', 'node-jet', 'node-angular', 'ords-remix-jwt-sample'],
+            options: ['node-vanilla', 'node-react', 'node-vue', 'node-react-todo', 'node-jet', 'node-angular', 'ords-remix-jwt-sample', 'mle-js-basic'],


I think we need to adjust the template name to have consistency with other templates and be more explicit on it's main functionality, a few proposals I have in mind:

mle-ts-sample

mle-deployment-sample

mle-todo

mle-todo-sample

changed to mle-ts-sample

dbtools-antcampo · 2025-04-24T23:13:58Z

.github/dependabot.yml

@@ -188,3 +188,8 @@ updates:
      - "templates-ords-remix"
    commit-message:
      prefix: fix(deps)
+
+  - package-ecosystem: "npm" 
+    directory: "/templates/mle-js-basic/"


When the template name is defined, I'll create a label on the project so that PRs created by dependabot can be easily filtered.
This will require a minor change here, but let's define that other item first.

dbtools-antcampo · 2025-04-28T23:55:12Z

templates/mle-js-basic/utils/db.mjs

+}
+
+console.log(`Executing: ${filePath}...`);
+const sqlclCommand = `"${sqlExecutable}" -S /nolog <<'EOF'


Regarding SQLcl, one of the concerns raised when discussing with the team is the fact that this:

This adds external dependencies.

Users who are not used to the Oracle ecosystem will probably not have SQLcl installed on their system, which represents a barrier to the use of the template.

We should explore the possibility of performing deployments using the node-oracledb driver as other templates do in the project for the DB connection.

For additional context: the objective of this generator is to help newcomers to the Oracle ecosystem by automating repetitive boilerplate tasks, eliminating setup friction, and accelerating onboarding, that why SQLcl is a concern for us.

@mig8447 @LeonSilva15

Currently using SQLcl for MLE template project is one of our requirements. SQLcl team is working on MLE specific functionality that simplifies user's interaction with MLE. For instance, it allows users to deploy large MLE modules directly from JS file without introducing PL/SQL wrapper code. Basically our goal is exactly the same as you describe "...help newcomers to the Oracle ecosystem by automating repetitive boilerplate tasks....". SQLcl functionality is still in development. There will be more functionality in the future that will make user's life easier.

What do you think @mig8447 ? That SQLcl feature seems reasonable to avoid more complexity in the code/deployments, maybe the download, unzip, and execution of SQLcl can be automated within the template 🤔

For the future templates we aim to use SQLcl projects to manage state of the database objects. SQLcl is using liquibase to keep track of changes. It also allows to export current state of the database, make changes, stage and the changes will be represented in the corresponding liquibase executable SQL scripts.

For the future, we can consider automated SQLcl installation. For the basic template we propose to keep things as it is now.

dbtools-antcampo · 2025-04-28T23:59:32Z

templates/mle-js-basic/package.json

+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --minify=false --platform=neutral --format=esm --outfile=dist/index.js",
+    "deploy": "node deploy.mjs",
+    "initdb": "node utils/db.mjs utils/database/initdb.sql",


How does initdb handle the case where objects are already in the DB but the cleandb has not been run?

User will see the corresponding message: 00000 - "name is already used by an existing object" or 00000 - "such a referential constraint already exists in the table"

dbtools-antcampo · 2025-04-29T21:34:36Z

.github/dependabot.yml

+  - package-ecosystem: "npm" 
+    directory: "/templates/mle-ts-sample/"
+    schedule:
+      interval: "monthly"


I created a new label templates-mlein the repo, let's add the corresponding configuration to this file to make issues generated by dependabot be tagged accordingly.

As an extra note, dependencies are usually updated every quarter, so you guys don't have to send updates every month as patch releases also occur in based on this schedule, of course security bugs/CVEs are the exception.

Added:

labels: - "dependencies" - "templates-mle"

dbtools-antcampo · 2025-04-29T22:27:15Z

templates/mle-ts-sample/README.md

+
+An Always Free Autonomous Database offers the quickest way to get started. If you would like to use {Docker,Podman} Compose to get up-and-running quickly, you can refer to [Server-Side JavaScript driven by node-express](https://blogs.oracle.com/developers/post/serverside-javascript-driven-by-nodeexpress) for reference.
+
+To execute JavaScript using Oracle Multilingual Engine (MLE), a database user typically needs the CREATE SESSION privilege to connect, and may require EXECUTE ON JAVASCRIPT depending on the database version (this requirement is being deprecated). If the JavaScript code imports MLE modules, the user must have EXECUTE privileges on those specific modules. Additional privileges like CREATE PROCEDURE or data access privileges (SELECT, INSERT, etc.) may be needed based on what the JS code does. For more information please read [System and Object Privileges Required for Working with JavaScript in MLE](https://docs.oracle.com/en/database/oracle/oracle-database/23/mlejs/system-and-object-privileges-required-working-javascript-mle.html).


Is this something that is automated in your scripts? Or users will have to execute these manually in their DB?

It is not automated. Normally, users are given a user by DBA that can be used to execute MLE JS code. If user wants to "play" with some local database installation the DB user should be created manually and corresponding privileges given.

dbtools-antcampo · 2025-04-29T22:30:17Z

templates/mle-js-basic/utils/db.mjs

+}
+
+console.log(`Executing: ${filePath}...`);
+const sqlclCommand = `"${sqlExecutable}" -S /nolog <<'EOF'


What do you think @mig8447 ? That SQLcl feature seems reasonable to avoid more complexity in the code/deployments, maybe the download, unzip, and execution of SQLcl can be automated within the template 🤔

dbtools-antcampo · 2025-04-29T23:24:52Z

templates/mle-ts-sample/package.json

+    "typescript": "^5.7.3",
+    "esbuild": "0.25.1",
+    "oracledb": "^6.7.1",
+    "vitest": "^1.0.0"


Is there any reason to use vitest 1.0.0 instead of the latest 3.1.2?

no specific reason, changed to 3.1.2

DimaNike added 3 commits April 3, 2025 11:38

feat: MLE app template

155744d

feat: added README

6c36f71

feat: added more information in README

cccbb2e

oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Apr 8, 2025

DimaNike added 2 commits April 8, 2025 14:22

feat: removed generated files

39f8335

feat: revert package.json and package-lock.json changes

3ee44f9

dbtools-antcampo self-assigned this Apr 8, 2025

dbtools-antcampo requested a review from LeonSilva15 April 8, 2025 21:44

DimaNike and others added 5 commits April 11, 2025 16:01

feat: addressing review comments

f918383

feat: enable the use of wallets and Autonomous DB

41d17b2

doc: more detailed readme for mle-app

80ef9d2

feat: improvements, addressing feedback, added automated test

f45cf8f

feat: removed mle types directive and added to tsconfig

c77888b

dbtools-antcampo reviewed Apr 29, 2025

View reviewed changes

feat: addressing PR comments

e67ed30

dbtools-antcampo reviewed Apr 29, 2025

View reviewed changes

feat: review comments, dependabot label, vitest version

649c625

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add MLE application template #257

feat: add MLE application template #257

DimaNike commented Apr 8, 2025

dbtools-antcampo Apr 24, 2025

DimaNike Apr 29, 2025

dbtools-antcampo Apr 24, 2025

DimaNike Apr 29, 2025

dbtools-antcampo Apr 24, 2025

DimaNike Apr 29, 2025

dbtools-antcampo Apr 24, 2025

dbtools-antcampo Apr 28, 2025

DimaNike Apr 29, 2025

dbtools-antcampo Apr 29, 2025

DimaNike Apr 30, 2025

dbtools-antcampo Apr 28, 2025

DimaNike Apr 29, 2025

dbtools-antcampo Apr 29, 2025

DimaNike Apr 30, 2025

dbtools-antcampo Apr 29, 2025

DimaNike Apr 30, 2025

dbtools-antcampo Apr 29, 2025

dbtools-antcampo Apr 29, 2025

DimaNike Apr 30, 2025


		An Always Free Autonomous Database offers the quickest way to get started. If you would like to use {Docker,Podman} Compose to get up-and-running quickly, you can refer to [Server-Side JavaScript driven by node-express](https://blogs.oracle.com/developers/post/serverside-javascript-driven-by-nodeexpress) for reference.

		To execute JavaScript using Oracle Multilingual Engine (MLE), a database user typically needs the CREATE SESSION privilege to connect, and may require EXECUTE ON JAVASCRIPT depending on the database version (this requirement is being deprecated). If the JavaScript code imports MLE modules, the user must have EXECUTE privileges on those specific modules. Additional privileges like CREATE PROCEDURE or data access privileges (SELECT, INSERT, etc.) may be needed based on what the JS code does. For more information please read [System and Object Privileges Required for Working with JavaScript in MLE](https://docs.oracle.com/en/database/oracle/oracle-database/23/mlejs/system-and-object-privileges-required-working-javascript-mle.html).

feat: add MLE application template #257

Are you sure you want to change the base?

feat: add MLE application template #257

Conversation

DimaNike commented Apr 8, 2025

[PR] [Enhancement] MLE application template #255

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment