In this article, we’ll walk through how to setup Oracle REST Data Services (ORDS) with Oracle AI Database Free for local app development and testing — all you should need is a Docker-compatible environment to get started!
if you’re not familiar with Oracle REST Data Services, it’s a comprehensive REST gateway for Oracle AI Database, providing additional functionality that includes, among other features:
- REST API for interacting with Oracle AI Database, allowing developers to perform database operations using HTTP methods
- SQL Developer Web interface
- Oracle APEX UI
- Wire-compatible MongoDB API
For more about ORDS, refer to the Getting Started Documentation.
How to run ORDS?
We can run ORDS locally using the Oracle Autonomous AI Database Free Container Image, a free version of Oracle Cloud Infrastructure’s Autonomous Database. The image bundles Oracle Database, ORDS, and Oracle APEX, making it highly useful for local development.
You may also download ORDS and run it standalone connected to a database server, or use Oracle Autonomous Database which is included in OCI’s Always-Free tier.
NOTE: The Autonomous Database Free image currently supports x86_64 architecture only. If you have an ARM machine, I suggest using Rancher Desktop with QEMU or Colima with Rozetta for to run the container.
Starting the Autonomous AI Database container image
If you have a Docker-compatible environment, you can start an Autonomous Database container like so — Note that you’ll need around 8 GB of memory available on your system or container VM:
docker run -d \
-p 1521:1522 \
-p 1522:1522 \
-p 8443:8443 \
-p 27017:27017 \
-e WORKLOAD_TYPE='ATP' \
-e WALLET_PASSWORD=Welcome12345 \
-e ADMIN_PASSWORD=Welcome12345 \
--cap-add SYS_ADMIN \
--device /dev/fuse \
--name adb-free \
container-registry.oracle.com/database/adb-free:latest-23aiAfter a few moments, the container should enter a healthy state. The “MY_ATP” database is created by default, and the following services will be available on local ports:
- 1521: Database TLS
- 1522: Database mTLS
- 8443: ORDS
- 27017: Mongo API
Note that the TLS ports use a self-signed certificate created within the container.
ORDS Database API
The ORDS Database API is available on https://localhost:8443/ords/<schema name>/_/db-api
For example, you can use the Database API to get the current database version using the ADMIN user and the ADMIN_PASSWORD:
curl -k -u ADMIN:Welcome12345 \
"https://localhost:8443/ords/admin/_/db-api/stable/database/version" |\
jq -r '.version'Learn more about the Database REST APIs Here, including full featured REST APIs for data and databases.
SQL Developer UI
To access the SQL Developer UI, open https://localhost:8443/ords/sql-developer in your browser — You may have to accept the container’s self-signed certificate. Login with the ADMIN user, using the ADMIN_PASSWORD passed in during container creation. Once you’re logged in, you’ll access the SQL Developer landing page, and may use features like the SQL Worksheet:
You’ll also find a suite of other tools in the SQL Developer UI catered to enhancing the developer experience:
Oracle APEX UI
To navigate to the Oracle APEX UI, open https://localhost:8443/ords/apex in your browser — You may have to accept the container’s self-signed certificate. Login using the ADMIN_PASSWORD passed in during container creation, and you’ll be greeted with the Oracle APEX login screen:
Leave a Reply