Repository files navigation

A progressiveNode.js framework for building efficient and scalable server-side applications.

Azure Database (Table Storage,Cosmos DB - NoSQL) module forNest framework (node.js)

You are reading the documentation for version 3. If you are looking for version 2 documentation,click here. Please also note that version 2 is no longer maintained and will not receive any updates!

For Cosmos DB (NoSQL ONLY)

1. Create a Cosmos DB account and resource (read more)
2. Note down the "URI", Database name and the "Primary Key" (or "Secondary Key") - You will need them later

For Table Storage

1. Create a Storage account and resource (read more)
2. Note down the "Connection string" - You will need it later

$ npm i --save @nestjs/azure-database

1. Create or update your existing.env file with the following content:

AZURE_COSMOS_DB_NAME=AZURE_COSMOS_DB_ENDPOINT=AZURE_COSMOS_DB_KEY=

2. IMPORTANT: Make sure to add your.env file to your .gitignore! The.env file MUST NOT be versioned on Git.

3. Make sure to include the following call to yourmain.ts file:

if(process.env.NODE_ENV!=='production')require('dotenv').config();

This line must be added before any other imports!

Note: Check out the CosmosDB example project included in thesample folder

0. Create a new feature module, eg. with the nest CLI:

$ nest generate module event

1. Create a Data Transfer Object (DTO) inside a file namedevent.dto.ts:

exportclassEventDTO{id?:string;name:string;type:string;createdAt:Date;}

2. Create a file calledevent.entity.ts and describe the entity model using the provided decorators:

• @CosmosPartitionKey(value: string | HierarchicalPartitionKey): Represents thePartitionKey orHierarchicalPartitionKey of the entity (required).

• @CosmosDateTime(value?: string): For DateTime values.

Important: Using a Hierarchical Partition Key requires a container that uses hierarchical partition keys,read more.

For instance, the shape of the following entity:

import{CosmosDateTime,CosmosPartitionKey}from'@nestjs/azure-database';import{PartitionKeyDefinitionVersion,PartitionKeyKind}from'@azure/cosmos';@CosmosPartitionKey({paths:['/name','/type/label'],version:PartitionKeyDefinitionVersion.V2,kind:PartitionKeyKind.MultiHash,})exportclassEvent{id?:string;name:string;type:{label:string;};  @CosmosDateTime()createdAt:Date;}

Will be automatically converted to:

{"name":"NestJS Meetup","type": {"label":"Meetup"  },"createdAt":"2019-11-15T17:05:25.427Z"}

1. Import theAzureCosmosDbModule inside your Nest feature moduleevent.module.ts:

import{AzureCosmosDbModule}from'@nestjs/azure-database';import{Module}from'@nestjs/common';import{Event}from'./event.entity';@Module({imports:[AzureCosmosDbModule.forRoot({dbName:process.env.AZURE_COSMOS_DB_NAME,endpoint:process.env.AZURE_COSMOS_DB_ENDPOINT,key:process.env.AZURE_COSMOS_DB_KEY,retryAttempts:1,}),AzureCosmosDbModule.forFeature([{dto:Event}]),],})exportclassEventModule{}

0. Create a service that will abstract the CRUD operations:

$ nest generate service event

1. Use the@InjectModel(Event) to get an instance of the Azure Cosmos DBContainer for the entity definition created earlier:

import{InjectModel}from'@nestjs/azure-database';importtype{Container}from'@azure/cosmos';import{Injectable}from'@nestjs/common';import{Event}from'./event.entity';@Injectable()exportclassEventService{constructor(    @InjectModel(Event)privatereadonlyeventContainer:Container,){}}

@InjectModel(Event) will inject an Azure Cosmos DBContainer instance for theEvent entity. TheContainer provides a list of public methods for managing the database.

IMPORTANT: Please note that theContainer instance is not a NestJS repository. It is the actual instance provided by the officialAzure Cosmos DB SDK.

asynccreate(eventDto:EventDTO):Promise<Event>{const{ resource}=awaitthis.eventContainer.items.create<Event>(eventDto,);returnresource;}

Fetches all the results of the query.

asyncgetEvents():Promise<Event[]>{constquerySpec={query:'SELECT * FROM events',};const{ resources}=awaitthis.eventContainer.items.query<Event>(querySpec).fetchAll();returnresources;}

Fetch a single resource.

asyncgetEvent(id:string,partitionKey:string|string[]):Promise<Event>{const{ resource}=awaitthis.eventContainer.item(id,type).read<Event>();returnresource;}

Replaces an item in the database.

asyncupdateEvent(id:string,partitionKey:string|string[],eventData:EventDTO,):Promise<Event>{let{resource:item}=awaitthis.eventContainer.item(id,type).read<Event>();item={    ...item,    ...eventData,};const{resource:replaced}=awaitthis.eventContainer.item(id,type).replace(item);returnreplaced;}

Deletes an item from the database.

asyncdeleteEvent(id:string,partitionKey:string|string[]):Promise<Event>{const{resource:deleted}=awaitthis.eventContainer.item(id,type).delete<Event>();returndeleted;}

If using hierarchical partition keys, you need to provide the partition key as an array of strings when calling one of the CRUD methods on theContainer. For example, when reading a single resource:

this.eventContainer.item("1234",['foo','bar']).read<Event>();

Read more aboutHierarchical Partition Keys.

1. Create or update your existing.env file with the following content:

AZURE_STORAGE_CONNECTION_STRING=

2. IMPORTANT: Make sure to add your.env file to your .gitignore! The.env file MUST NOT be versioned on Git.

3. Make sure to include the following call to yourmain.ts file:

if(process.env.NODE_ENV!=='production')require('dotenv').config();

This line must be added before any other imports!

4. TheAzureTableStorageModule will automatically read theAZURE_STORAGE_CONNECTION_STRING environment variable and use it to connect to your Azure Storage account.

Check out the Table Storage example project included in thesample folder

0. Create a new feature module, eg. with the nest CLI:

$ nest generate module event

1. Create a Data Transfer Object (DTO) inside a file namedevent.dto.ts:

exportclassEventDTO{name:string;type:string;}

2. Create a file calledevent.entity.ts and describe the entity model using plain JavaScript objects.The only requirement is to provide apartitionKey and arowKey properties. For instance, the shape of the following entity:

exportclassEvent{partitionKey:string;// requiredrowKey:string;// requiredname:string;type:string;}

1. Import theAzureTableStorageModule inside your Nest feature moduleevent.module.ts:

import{Module}from'@nestjs/common';import{AzureTableStorageModule}from'@nestjs/azure-database';@Module({imports:[AzureTableStorageModule.forFeature(Event)],})exportclassEventModule{}

You can optionally pass in the following arguments:

import{Module}from'@nestjs/common';import{AzureTableStorageModule}from'@nestjs/azure-database';@Module({imports:[AzureTableStorageModule.forFeature(Event,{table:'foobar',createTableIfNotExists:true,}),],})exportclassEventModule{}

• table: string: The name of the table. If not provided, the name of theEvent entity will be used as a table name
• createTableIfNotExists: boolean: Whether to automatically create the table if it doesn't exists or not:
  • Iftrue the table will be created during the startup of the app.
  • Iffalse the table will not be created.You will have to create the table by yourself before querying it!

0. Create a service that will abstract the CRUD operations:

$ nest generate service event

1. Use the@InjectRepository(Event) to get an instance of the AzureRepository for the entity definition created earlier:

import{InjectRepository,Repository}from'@nestjs/azure-database';import{Injectable}from'@nestjs/common';import{Event}from'./event.entity';@Injectable()exportclassEventService{constructor(    @InjectRepository(Event)privatereadonlyeventRepository:Repository<Event>,){}}

TheAzureTableStorageRepository provides a list of public methods for managing various CRUD operations:

create(entity: T): Promise<T | null>: creates a new entity.

asynccreate(event:Event):Promise<Event>{returnawaitthis.eventRepository.create(event);}

find(partitionKey: string, rowKey: string): Promise<T>: finds one entity using itspartitionKey androwKey.

asyncfind(partitionKey:string,rowKey:string):Promise<Event>{returnawaitthis.eventRepository.find(partitionKey,rowKey);}

findAll(options: { queryOptions?: TableEntityQueryOptions }): Promise<T[]>: finds all entities.

asyncfindAll(options:{queryOptions?:TableEntityQueryOptions}):Promise<Event[]>{returnawaitthis.eventRepository.findAll();}

update(partitionKey: string, rowKey: string, entity: T): Promise<T>: Updates an entity using a "merge" strategy.

asyncupdate(partitionKey:string,rowKey:string,event:Event,):Promise<Event>{returnawaitthis.eventRepository.update(partitionKey,rowKey,event);}

delete(partitionKey: string, rowKey: string): Promise<DeleteTableEntityResponse>: Removes an entity from the table.

asyncdelete(partitionKey:string,rowKey:string):Promise<void>{awaitthis.eventRepository.delete(partitionKey,rowKey);}

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, pleaseread more here.

• Author -Wassim Chegham
• Website -https://wassim.dev
• Twitter -@manekinekko

Nest isMIT licensed.