Skip to main content

Tigris TypeScript SDK overview

Prerequisites​

System requirements​

Sign up​

To get started, go to the Tigris console and sign up.

Create a project​

Once you have successfully signed up, you are ready to start creating a project. You can create a new project from the Tigris Cloud dashboard by clicking on the Create a new project button from the Tigris Cloud dashboard.

Create a new project

Tigris will generate the credentials for your application, and you will be shown a command to generate application code with Tigris pre-configured.

The create-tigirs-app terminal command displayed within a dialog within the Tigris web console

Automatic Setup​

Copy the create-tigris-app command that is shown in the create a project section above.

We recommend creating a new app using create-tigris-app, which sets up the Tigris SDK automatically for you. (You don't need to create an empty directory. create-tigris-app will make one for you.)

After the installation is complete:

  • Run npm run dev or yarn dev or pnpm dev to start the development server on http://localhost:3000

Manual Setup​

Install the packages​

Install the Tigris SDK that is provided as a npm package

npm install @tigrisdata/core --save

Install reflect-metadata that enables automatic type inference using reflection

npm install reflect-metadata --save

Ensure that you are on Typescript version 4.5 or above and have the following settings enabled in compilerOptions section of tsconfig.json:

"emitDecoratorMetadata": true,
"experimentalDecorators": true,

Configure environment variables​

Let's copy the project name, clientId and clientSecret from the command shown in the create a project section above.

Now that we have created the project, lets set up the environment variables which will allow the application to connect with Tigris.

We will use the project name, clientId and clientSecret from the previous step

.env
TIGRIS_URI=api.preview.tigrisdata.cloud
TIGRIS_PROJECT=myapp
TIGRIS_CLIENT_ID=ftSUj9B5czFW79s9M6YUkxKE3H4WeRyY
TIGRIS_CLIENT_SECRET=DOxxx
TIGRIS_DB_BRANCH=main

Instantiate the Tigris client​

import { Tigris } from "@tigrisdata/core";

const tigrisClient = new Tigris();

Define the data model​

Every Tigris project comes with a pre-configured database and stores data records as documents. Documents are analogous to JSON objects grouped in a Collection.

Let's create a data model to define the collection. We will be storing the data models in the directory db/models.

db/models/catalog.ts
import {
  Field,
  PrimaryKey,
  TigrisCollection,
  TigrisDataTypes,
} from "@tigrisdata/core";

export class ProductAttributes {
  @Field()
  name: string;

  @Field()
  value: string;
}

@TigrisCollection("catalog")
class Catalog {
  @PrimaryKey(TigrisDataTypes.INT64, { order: 1, autoGenerate: true })
  id?: string;

  @Field()
  name: string;

  @Field()
  price: number;

  @Field()
  brand: string;

  @Field(TigrisDataTypes.INT32)
  popularity: number;

  @Field({ elements: ProductAttributes })
  attributes: Array<ProductAttributes>;
}

Let's see what is going on here. You've imported the Tigris @TigrisCollection decorator, which accepts a collection name as an argument to create a collection. The TigrisDataTypes type gives you access to the Tigris data types. @Field decorator defines the collection fields and the @PrimaryKey decorator define the primary of the collection.

Initialize the branch and create the collection​

import { Catalog } from "./db/models/catalog";

await tigrisClient.getDatabase().initializeBranch();
await tigrisClient.registerSchemas([Catalog]);

Here we have used the initializeBranch which creates the database branch if it does not exist. We have also used the registerSchemas method, which takes in an array of all the model classes defined in your db/model directory. In our case we have a single model class Catalog. Tigris will create a collection named catalog corresponding to the model class Catalog.

Query the collection​

import { Catalog } from "./db/models/catalog";

const db = tigrisClient.getDatabase();

const collection = db.getCollection<Catalog>(Catalog);
const cursor = collection.findMany();
const results = await cursor.toArray();

Here we used a simple findMany() function to read all the documents from the collection.

Using a setup script​

We recommend using a setup script to automate the initialization of the database branch, and to manage the creation of collections and the schema updates.

setup.ts
import { Tigris } from "@tigrisdata/core";
import { Catalog } from "./db/models/catalog";

async function main() {
  // setup client
  const tigrisClient = new Tigris();
  // ensure branch exists, create it if it needs to be created dynamically
  await tigrisClient.getDatabase().initializeBranch();
  // register schemas
  await tigrisClient.registerSchemas([Catalog]);
}

main()
  .then(async () => {
    console.log("Setup complete ...");
    process.exit(0);
  })
  .catch(async (e) => {
    console.error(e);
    process.exit(1);
  });

Next, add setup.ts as one of the scripts in package.json.

package.json
  "scripts": {
    ...
    "setup": "npx ts-node setup.ts",
    "predev": "npm run setup",
    "postbuild": "npm run setup",
  }