Remote Database Connections

In Onyx, you can connect to a remote database either by configuring your own remote Onyx server (Open Source) or by using the fully managed Onyx Cloud Database. This tutorial will guide you through both approaches:

Onyx Cloud Database

The Onyx Cloud Database provides a fully-managed environment, removing the need to manually configure or manage persistence managers. Once you have your databaseId, apiKey, and apiSecret, you can connect directly to the Onyx Cloud.

The OnyxClient can be obtained by generating an SDK through the Onyx Cloud Dashboard. It will contain the JavaScript SDK and code generation for your entities. Instructions on how to generate the client can be found Onyx Cloud Services API and SDK Generation.

The cloud database provides additional features such as enhanced security, scalability, and automated backups. For more details, visit our User Guide for Onyx Cloud Database.

Steps to Connect to Onyx Cloud Database

1

Initialize the OnyxClient

Create a new OnyxClient instance and provide your cloud database credentials.
1import { OnyxClient } from "@/path/to/onyx-sdk";
2
3// Create a new OnyxClient instance for the cloud database
4const db = new OnyxClient({
5    baseUrl: "https://api.onyx.dev",
6    databaseId: "<your_database_id>",       // Replace with your database ID
7    apiKey: "<your_api_key>",               // Replace with your API key
8    apiSecret: "<your_api_secret>"          // Replace with your API secret
9});
10
11// The OnyxClient acts as your connection interface to the Onyx Cloud Database.
2

Perform CRUD Operations

Use the OnyxClient instance to interact with the cloud database. No manual setup or teardown required.
1// Once connected, you can perform CRUD operations directly using the client.
2// For example, to save an entity:
3const league = { name: "NFL", description: "National Football League" };
4await db.save('League', league);
5
6// To find an entity by its ID (primary key):
7const foundLeague = await db.findById('League', 'NFL');
8console.log(`Found League Description: ${foundLeague.description}`);
Next Tutorial: Entity Attributes

Troubleshooting

  • Invalid credentials: Verify your credentials (username/password for Open Source or apiKey/apiSecret for Cloud).
  • Cannot connect to server: Ensure the server URL (for Open Source) or the baseUrl (for Cloud) is correct and accessible.
  • Connection refused (Open Source): Check the server's firewall and port availability.

Next Steps

Whether you're using the Open Source solution or Onyx Cloud Database, you can now focus on modeling data, performing queries, and integrating with your application: