Tigris TypeScript SDK overview
Prerequisites​
System requirements​
- Node.js 18.13.0 or newer
- MacOS, Windows, and Linux are supported
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.
Tigris will generate the credentials for your application, and you will be shown a command to generate application code with Tigris pre-configured.
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
oryarn dev
orpnpm dev
to start the development server onhttp://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
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
.
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.
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
.
"scripts": {
...
"setup": "npx ts-node setup.ts",
"predev": "npm run setup",
"postbuild": "npm run setup",
}