Follow the Coffee

Tag: release notes

  • ORDS 25.2 Release Highlights

    ORDS 25.2 Release Highlights

    As always, the complete, official list of enhancements and fixes can be found here. Contained in this brief post are some of the highlights from this latest release.

    My top enhancements

    Of the new features the team has published, I’d say these next two are probably going to be the “most sought after” for folks.

    Managed service connections

    In short, you can now use either Instance Principal and OCI Profile credentials for the db.connectionType in your ORDS configuration settings. Details can be found here.

    My takeaways from this:

    • It is going to make credential storage a LOT easier
    • Use Instance Principal for when you are using a VM to host ORDS in OCI, and OCI Profile for all else (easy way to look at this without getting too complicated)

    I am working on a tutorial for this, using the OCI Profile method. Once I’m back from traveling, I’ll publish on the official Oracle blog site.

    JWT Profile at the pool level

    The elevator pitch for this: “You know how you could only set a JWT profile for a schema? Well this makes it possible to set this profile at the pool level, for all consumers (schemas) of that pool.” Meaning, this makes it optional, should you want to “share” a JWT Profile across schemas. Details can be found here. Expect an official tutorial soon.

    Pre-Authenticated Requests (PARs)

    ORDS recently introduced support for Pre-Authenticated Requests (PARs). Well, we now have updates in the SQL Developer Web UI. You can create PARs from within the Resource Handler Dashboard. You can revoke PARs too.

    SQL Developer Web UI

    Creating a new PAR

    Creating a new PAR from an existing Resource Handler is fairly effortless now. After creating the PAR, you’ll be provided a Token, Alias, and complete PAR URI. You’ll see how the URI is a concatenation of the existing URI and the PAR token. But what if you want to revoke access?

    Revoking a PAR

    PARs are automatically revoked when they expire. You can alternatively revoke the PAR:

    1. In the PAR dashboard, or
    2. From within the same Resource Handler dashboard

    PAR Expiration by Alias function

    We have introduced a new function that will ingest the PAR alias, and return the time left till expiration. You can find this new function under the ORDS_PAR package of the ORDS_METADATA schema.

    I’d like to know, how would you use this though? Would you use this in some sort of automation, or would you somehow display the remaining time on screen (if we are talking about a client application)?

    MLE/JS

    Now, when a Resource Handler has anything to do with MLE and you encounter an MLE error, you’ll receive a message with a callout to MLE.

    Exception handling

    In the example below, I’ve created a simple MLE/JS Resource Handler that should display some details about a specified employee (identified by their employee number). However, since this test schema has zero objects in it, I’d expect to receive an error.

    In the example below, I use a random employee number, for a non-existent “employees” table. And to truly see the benefits, you’ll want to have the ORDS printDebugToScreen configuration setting set to TRUE.

    ORDS CLI

    Verify command

    I cannot tell you how many times people ask questions that can be answered with this one command.

    On its face, it seems trivial, but this is such a nice shortcut to determining if an ORDS installation is valid. I can see this being used in your shell scripts too, for validation. Something like:

    sed 'ords config --db-pool default verify'

    Or perhaps, add it to the compose.yaml file that we include in our ORDS container?

    Other/Misc

    Want to share your story?

    If you’ve stopped by the ORDS product page recently, then you may have seen our latest customer testimonial. Sphere is a heavy consumer of ORDS, and they love the product. If you have an ORDS story to share email me. Let’s collab on a similar write-up.

    GitHub

    Apparently the oracle/docker-images/ords repo has been “dormant” for quite sometime. Well no more. We (Adrian and I) are now in full control of the ORDS content. So we are updating the Dockerfiles and README. They should be ready in a week or so (end of July 2025), we are finalizing the drafts now. And if you have an outstanding/pending issue you can expect to see some movement on your ticket.

    Oracle Container Registry

    We have taken your feedback and updated the README for the ORDS official container. You can see the latest here. However, we have another update planned, so if you don’t see your suggestions yet, give us another week! We are updating the README to make it more approachable for a container newbie, and we are adding in some additional, helpful comments in the compose.yaml file too!

    Oracle Cloud World 2025

    We are in full Cloud World mode now, till the end October. View the details and register here. Kris, Jeff, and I will be there. We’ll be presenting on several topics. But if travel isn’t in your future, never fear, we’ll have recordings of the presentations once Cloud World has wrapped up.

    Official Release Notes

    And finally, the official release notes can be found here.

    That’s all for now, thanks for stopping by 😊.

  • ORDS 25.1 Release Highlights

    ORDS 25.1 Release Highlights

    ORDS 25.1 is now available, here are the highlights 😀

    JWT roles-based scopes

    You are probably well aware of our current JWTs authentication and authorization support. But shortly after releasing this functionality, one of our long-time customers asked us to enhance ORDS JWT Profiles so they could also support roles “claims” (and scopes). So now, when creating your ORDS JWT Profile, you can set your p_role_claim_name => '/roles'. This setting would “point” to the roles you have configured within your identity provider (like IAM, IDCS, Auth0, etc.).1

    🛎️ Come back to my blog in about two days, and you’ll see a new updated tutorial illustrating this new functionality (with JSON Pointers for the roles-based claim).

    In the meantime, be sure to check out my current JWT-related blog posts:

    ORDS_EXPORT and ORDS_EXPORT_ADMIN

    The most significant changes are available options for users you’ve granted the ORDS_ADMINISTRATOR_ROLE.2 Now, you can export another user’s entire schema, including the details for their JWT Profile. In the screenshots below, you’ll see examples of the ORDS_EXPORT_ADMIN.EXPORT_SCHEMA procedure, using various optional parameters.

    You have a lot of flexibility here; you can choose which optional parameters to include. Can you spot the differences?

    An example showing the ENABLE_SCHEMA and RUNNABLE_AS_ADMIN parameters.
    An example that consists of the SCHEMA parameter but turns off the RUNNABLE_AS_ADMIN parameter.
    An example showing the new INCLUDE_JWT_PROFILES parameter.

    ORDS_SECURITY updates

    The next time you create an ORDS OAuth client, you might notice some changes to the UI. Under the covers, this action is made possible by the ORDS_SECURITY PL/SQL package. You can still use the older, now deprecated OAUTH packages, but we now default to these newer ORDS_SECURITY procedures and functions.

    One of the most notable changes is that these procedures now follow the standard convention (you’ve probably seen elsewhere) of showing a Client’s Secret once and only once. The procedure is now more succinct, organized, and secure.

    💡When you need a new Client Secret, you can “rotate” it with the new ROTATE_CLIENT_SECRET functions (using the Client Name, Client Id, ORDS/internal Id).

    Dark mode

    Dark mode is activated. You can set SQL Developer Web (aka Database Actions) to Light, Dark, or Same as browser. I quite like the third option, as it makes shifting from Apple’s Light to Dark Mode seamless.

    Including this here to remind you of the other available configurable settings.

    DBA_ORDS views

    These views aren’t new for this release, but I don’t think we’ve mentioned them recently. Any of your REST-enabled schemas can access these DBA_ORDS_[View Name] views (for their respective schemas), and they are really helpful when you need to quickly view your most important configurations.

    Like always, you can drag and drop “objects” into the SQL Worksheet. After dropping, a modal will appear with different options (depending on the object type), allowing you to choose an action.

    Important links

    And finally, the important links:

    That’s all for now. I am working on a JWT-using-roles tutorial, which should be out by Friday this week. I’ll update this post when it is live.

    And I have another new ORDS plug-in tutorial that I’d like to share; this one is Java-based. My friend Reydan from the Oracle Health (via Cerner) side is integrating the heck out of their stuff with ORDS, and this example is something he came up with as an exploratory exercise. It’s nothing fancy, but I thought it would be great for the beginner.

    And that’s all for now!

    References

    1. This is known as a JavaScript Object Notation Pointer (JSON Pointer). An upcoming JWT tutorial using role-based claims will provide more details. The technical specifications for the JSON Pointer can be found here. ↩︎
    2. If you are using the Autonomous Database (ADB, ATP, JSON), then you’ll know this ORDS Administrator as your “ADMIN” user. ↩︎

  • ORDS 24.4 Release Highlights

    ORDS 24.4 Release Highlights

    So what even is new in ORDS 24.4? How about an abbreviated list of some fan favorites?

    Pre-Authenticated endpoints

    Using the new ORDS_PAR PL/SQL package, users can create, revoke, issue and set tokens and token life for specific resources. Your REST-enabled schema will automatically have access to this new feature in 24.4. You can execute these functions and procedures from within the Database Actions SQL Worksheet, the SQL Developer for VS Code extension, the SQL Developer desktop client, and SQLcl (new version out) too!

    A mini-tutorial

    Here is an easy way to test these new PAR functions and procedures from the SQL Worksheet. First, Select the ORDS_METADATA schema from the SQL Worksheet Navigator. Then, select “All Objects,” scroll down to, and right-mouse-click on the ORDS_PAR PL/SQL package. Then select Run.

    The first function you see will be the DEFINE_FOR_HANDLER function. Enter your details in the required fields, and execute the code in the SQL Worksheet. You’ll see a new URI populate.

    You can now share that URI (or use it in your test). And it will remain valid for however long you set for the P_DURATION parameter.

    Finally, here is an example of using that same PAR URI in a curl command.
    A reminder of where you can locate all these required fields

    Navigate to the REST Workshop; choose your target Resource Module, then…

    Next, click the Export Module option.
    Export your target module in PL/SQL.
    You can now easily decide which Module, Template, and Handler to use for your PAR.

    ORDS Central Configuration

    ORDS Central Configuration now natively supports pool identifiers in URLs. We still have the Header method of mapping for Central Configuration. But now we support the Request Host Method, too. For instance, if your Global configuration’s (when using a Central Configuration deployment) URI is:

    https://central-config.example.com:8585/central/v1/config/pool/{host}

    You can issue a GET request (something like this, perhaps) to:

    curl https://my_database_pool.localhost:8080.com/ords/hr/employees/

    Your ORDS Central Configuration will take that database pool “prefix” and use it to “look up” that database pool’s settings (in the Central Configuration server). From there, your ORDS instance would have both Global and Pool configuration settings, and it would then be able to satisfy the above GET request.

    Previously, to “inform” the Central Configuration of the {host} value (the URI you see in the first code block), you’d have to pass in a request header. YOU CAN STILL DO THIS! But we support both methods now. Depending on your use case, you may prefer one method over the other. Details here.

    Plain-text in XML Files

    ORDS will notify users when plain-text “secrets,” such as passwords, are present in the ORDS configuration XML files. What does this look like? You can “test” this new functionality by retrieving something like the db.password configuration property.

    Typically, ORDS looks for this value in the cwallet.sso file, but you can add it here (it will just be redundant).

    Adding the password, in plain text, to a pool.xml configuration file.

    We then warn you not once but twice! Once when ORDS first starts up and then again when it fully initializes.

    A new ORDS CLI option

    The ORDS CLI now includes a script-friendly --quiet option, which hides banner, copyright, and configuration location information from the ORDS STDOUT.

    Here is an example where we use the standard command:

    ords config get db.servicename

    Followed by the much leaner version:

    ords config --quiet get db.servicename

    As you can see, this makes it much easier for scripts and automation tools to navigate the ORDS STDOUT.

    APEX updates to ORDS access logs

    Standalone access log records now include an APEX app_id and APEX page_id for records, where applicable. The end of the log captures both app_id and page_id (in this example, 4550:1, respectively).

    [0:0:0:0:0:0:0:1] - [21/Nov/2024:17:37:42 +0000] "POST /ords/wwv_flow.accept?p_context=workspace-sign-in/oracle-apex-sign-in/12558700474753 HTTP/1.1" 200 6494 "http://localhost:8080/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" 1362 localhost:8080 - 4550:1

    In cases where APEX is absent, dashes will replace these fields.

    JSON Syntax highlighting

    When viewing JSON data from a query result in the SQL Worksheet, pretty printing, and JSON syntax highlighting are now applied. In this example, you’ll notice a single-row table with the column “Glossary.” Clicking the “Eyeball” icon on the Select * From... results reveal this gorgeously formatted and highlighted JSON object.

    Click to add Implicit, Handler parameters

    You can now add user-defined parameters (i.e., Handler parameters) and Implicit parameters to Handler code blocks with a single mouse click of the parameter name. Take a look at the examples below:

    README: We have a TON of additions planned for the Implicit parameters chapter in the ORDS Developer's Guide. You might notice some new additions already. Either way, bookmark this chapter now, as we are also rolling out new in-context code examples and mini-tutorials from now till...we can't anymore.

    SQL Worksheet file functionality

    You can now rename SQL Worksheet files (from within Database Actions and the OCI console). This update applies to browser files and OCI object storage files. You can now open, rename, and trash these files.

    And those are just some of the highlights. But be sure to review the links below!

    The links

    1. Download ORDS /latest today.
    2. Read the complete, official Release Notes.
    3. Read the latest edition of the ORDS Developer’s Guide and ORDS Installation/Configuration Guide.
    4. Check out our latest ORDS npm samples.

    And that’s all for now! Enjoy 😊

    Follow

    And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!