Getting Started with Onyx Database

Welcome to the Onyx Database Getting Started guide! This tutorial will walk you through the steps to integrate Onyx Database into your project, define entities, perform CRUD operations, and execute queries.

Note: Open Source vs. Onyx Cloud Database

This tutorial covers the setup and usage of the Onyx Open Source Database. If you're interested in using the Onyx Cloud Database, please refer to our comprehensiveUser Guide for Onyx Cloud Database.

The cloud database offers additional features such as managed services, enhanced security, and JavaScript or Kotlin based query scripting.

Prerequisites

  • Ensure your schema defines all required attributes, including types, sizes, and nullability.
  • The identifier field is mandatory for each table and must include a unique name and a supported generator type (e.g., Sequence or UUID).
  • Relationships and indexes are optional but improve performance and enforce data integrity.

Step 1: Define a Simple Entity

Define your data model by creating an entity class. Onyx uses annotations to manage entities and their attributes.

To create a database and define a schema for Onyx Cloud Database, please refer to our comprehensiveUser Guide for Onyx Cloud Database.

Step 2: (Optional) Connect to the Cloud Database

If you are accessing the cloud database from your own project, you will need to connect to it using the generated JavaScript SDK. This is not needed if you are using the query editor within the Onyx Cloud Services Dashboard.

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.

Here, we instantiate a new Onyx Client and give it the required parameters to connect. Prior to doing this, you will need to have created an access key that grants it permission to read and write to the database.

Step 3: Create an Instance of the Entity

Instantiate your entity and set its attributes. Below are examples in JavaScript.

1const person = {
2    id: 1,
3    firstName: "Michael",
4    lastName: "Jordan"
5};

Here, we create a new Person object with sample data.

Step 4: Save the Entity Instance

Use the PersistenceManager to save your entity instance to the database.

1await client.save("Person", person);

This operation persists the person instance in the database.

Step 5: Execute a Query

Retrieve data from the database by executing queries. Below is an example of querying for a person named "Michael".

1// Execute a query to see your entity in the collection
2const people = await client.from("Person")
3                          .where(eq("firstName", "Michael"))
4                          .limit(20)
5                          .list();
6
7// There should be 1 person in the list named "Michael"
8console.log("Records returned: " + people.length);
9console.log("First person in the list: " + people[0].firstName + " " + people[0].lastName);

The query criteria specify that we're looking for entities where firstName equals "Michael". The results are then printed to the console.

Troubleshooting

  • Unauthorized : Ensure that you have access to the selected database and that you have write privileges.
  • Database connection issues: Verify that the database deployed and is in a running state.
  • Entity not saving: Check that your entity class is properly defined and the schema is correctly set up.

Next Steps

Congratulations! You've successfully integrated Onyx Database into your project. To further enhance your knowledge, proceed to the next tutorials: