Content written by Doug Drechsel.
This document describes how to build and run Parse Server with the new Oracle storage adapter based on the Oracle NodeJS libraries. It will demonstrate running against the Free23ai Docker container and the JSON Autonomoumous database in the cloud.
Building the Server
Building the server is easy. you will need Node.js (Node) and npm (Node Package Manager) installed. Node.js is the runtime environment for executing JavaScript on the server, while npm is the package manager for managing JavaScript packages and their dependencies in Node.js projects.
Clone Parse Server Repository. Use the alpha branch
git clone https://github.com/parse-community/parse-server.git
Clone the oracle-samples/oracleadapter-parse repo into src/Adapters/Storage/Oracle
cd src/Adapters/Storage
git clone git@github.com:oracle-samples/oracleadapter-parse.git Oracle
cd Oracle
rm -rf .git // IMPORTANT or build will fail
cd ../../../.. // Go back to Project Root
At this point the source tree is populated correctly but there still are a few modifications needed prior to building the server. One is to add the Oracle database dependency to package.json.
"oracledb": "^5.5.0",
And the other is to update src/Controllers/index.js to support the new Oracle storage adapter. First, add the import
import OracleStorageAdapter from '../Adapters/Storage/Oracle/OracleStorageAdapter';
and second, update the adapter case statement at the bottom of the file with
case 'oracledb:':
return new OracleStorageAdapter({
uri: databaseURI,
collectionPrefix,
databaseOptions,
});
Run npm install to get Oracle database dependencies
and run npm ci to build the server
If everything was successful, a Parse server exists that can connect to an Oracle database.
Configuring Free23ai Oracle database image
First download and start the Free23c image.
docker run --name free23ai -d -p 1521:1521 -e ORACLE_PWD=Welcome12345 container-registry.oracle.com/database/free:latest
It takes about a minute for the image to reach a healthy state on my MacBook
Next connect to the image as sysdba. Oracle SQL client is required. The Oracle SQL client is a software application that allows users to connect to Oracle databases and execute SQL queries and manage the database. It can be downloaded HERE
sql sys/Welcome12345@localhost:1521/free as sysdba
Once connected, run the following commands to enable JSON database support in the image
alter session set container=FREEPDB1;
grant db_developer_role to pdbadmin;
grant soda_app to pdbadmin;
GRANT UNLIMITED TABLESPACE TO pdbadmin;
quit;
Run Parse Server
Create a config.json. This is a minimal set of configuration parameters for booting the server.
{
"appId": "APPLICATION_ID",
"masterKey": "MASTER_KEY",
"databaseURI": "oracledb://pdbadmin:Welcome12345@localhost:1521/freepdb1",
"port": 1338,
"logLevel": "info",
"verbose": false,
"mountGraphQL": true,
"mountPlayground": true,
"graphQLPath": "/graphql"
}
Boot the Server using the Oracle Instant Client location. The Oracle Instant Client is a set of software libraries that allow you to connect to an Oracle database without a full Oracle database installation and can be downloaded HERE
ORACLE_CLIENT_LOCATION=/Users/myuser/instantclient_19_8 npm start -- ./config.json
The last few lines of a successful server boot look like
info: creating a connection pool
info: connection pool successfully created
[77985] parse-server running on http://localhost:1338/parse
[77985] GraphQL running on http://localhost:1338/graphql
[77985] Playground running on http://localhost:1338/playground
The local stack is ready to support development work.
Test the Local Stack
Run a curl command that creates a simple document in the GameScore collection
curl -X POST -H "X-Parse-Application-Id: APPLICATION_ID" -H "Content-Type: application/json" -d '{"score":12,"playerName":"scooby","cheatmode":false}' http://localhost:1338/parse/classes/GameScore
Successful completion returns
{"objectId":"CdmLJT6Duc","createdAt":"2023-10-16T19:33:27.382Z"}
Connect to the database and verify results
sql pdbadmin/Welcome12345@localhost:1521/FREEPDB1
Run SODA commands, the collections prefixed with an underscore are Parse internal tables
SQL> soda list
List of collections:
GameScore
_Hooks
_Idempotency
_Role
_SCHEMA
_User
SQL> soda get GameScore
KEY Created On
3A8CB47A41A74F59BFDD143A3F365F4A 2023-10-16T19:33:27.404374000Z
1 row selected.
SQL> soda get GameScore -k 3A8CB47A41A74F59BFDD143A3F365F4A
Key: 3A8CB47A41A74F59BFDD143A3F365F4A
Content: {"score":12,"playerName":"scooby","cheatmode":false,"updatedAt":"2023-10-16T19:33:27.382Z","createdAt":"2023-10-16T19:33:27.382Z","_id":"CdmLJT6Duc"}
1 row selected.
soda help – list all soda commands
And that concludes this simple exercise of standing up a mobile development environment locally based upon the Oracle database. There are just a few simple updates if this local Parse server was to run against an Autonomous JSON Database instance in the cloud.
Running against Autonomous Database in the cloud
Update databaseURI in config.json to point at the cloud database instance
"databaseURI": "oracledb://username:password@tnsname",
and download the cloud database wallet and use it when starting the server
ORACLE_CLIENT_LOCATION=/Users/myuser/instantclient_19_8 ORACLE_WALLET_LOCATION=/Users/myuser/wallet-oradb npm start -- ./config.json
The username, password, tnsname (a user-friendly alias for a database connection) and wallet (database credentials) are required parameters. All of these parameters can be retrieved either by the developer, if they have access or the database administrator.
Summary
I hope this article illustrated just how simple it is to configure and run a mobile/web development environment using the Oracle database and Parse Server.
Here are a few links to other related articles