Forem: Alex Raileanu

Working with AWS DSQL and Lambda: First Part - Setup of the project

Alex Raileanu — Tue, 10 Jun 2025 14:55:16 +0000

Not long ago, I was exploring Amazon Aurora DSQL, AWS's newest distributed SQL database built specifically for serverless workloads. Unlike traditional databases that require constant maintenance, Aurora DSQL scales automatically and only charges for what you use - making it a perfect match for Lambda functions.

When you think serverless databases, DynamoDB probably comes to mind first — and for good reason. It's been the go-to NoSQL solution for serverless applications for years. But now we can finally consider relational databases in a truly serverless context too. Aurora DSQL brings the familiarity of SQL and relational data modeling to the serverless world, without the overhead of managing database instances or worrying about scaling.

Welcome to the first installment in a three-part series where I'll build a serverless backend using Amazon Aurora DSQL, AWS Lambda, AWS CDK, and GitHub Actions.

What will this first article cover?

Project Setup:

You’ll learn how to initialize and organize your serverless backend project, including setting up your repository and preparing the necessary files and folders for a smooth development workflow.

AWS CDK for Infrastructure:

This article walks you through using AWS CDK to define your cloud infrastructure as code. You’ll see how to use CDK constructs (especially L1 for Aurora DSQL, where applicable) to provision resources such as Lambda functions and Aurora DSQL clusters, and how to structure your CDK stack for maintainability and scalability.

Lambda and DSQL Connectivity:

You’ll discover how to establish secure connectivity between AWS Lambda and Amazon Aurora DSQL. This includes configuring IAM roles and policies to allow Lambda to interact with the DSQL Data API, and setting up environment variables or secrets for secure database access.

Code Snippets – Step-by-Step:

Practical, actionable code examples are provided at each stage. You’ll see how to write CDK stacks, define Lambda functions, and connect them to DSQL, making it easy to follow along and adapt the approach to your own projects.

Open Source Repository:

The article references an open-source repository, allowing you to review the complete project structure, clone the code, and experiment with the setup yourself. This ensures transparency and makes it easy to check or extend the approach.

Step 1:

Here’s how I like to organize the project

infra/ – Contains all CDK-related infrastructure code.
service/ – Your Lambda source code goes here.
.github/ - The GitHub Actions workflows go here.

Note:

This approach usually empowers me to easily separate infrastructure from business logic and isolate the pipeline related actions as well.
Also - I like to structure the infrastructure in stacks based on their domain. I found it useful as the project kept on growing.

Step 2:

Now let's jump into the details of working with AWS CDK and AWS DSQL.

Note: Since AWS DSQL has been recently released, the only Constructs that are available are L1 Constructs which are automatically generated. I will adjust this article & open-source repository as the AWS DSQL support becomes more widely adopted in the CDK world.

export class StorageStack extends cdk.Stack {
    dsqlCluster: cdk.CfnResource;
    dsqlClusterArn: string;
    dsqlClusterEndpoint: string;

    constructor(scope: constructs.Construct, id: string, props: cdk.StackProps) {
        super(scope, id, props);

        // Create DSQL cluster using native CloudFormation resource
        this.dsqlCluster = new cdk.CfnResource(this, 'DSQLCluster', {
            type: 'AWS::DSQL::Cluster',
            properties: {
                DeletionProtectionEnabled: true,
                Tags: [
                    {
                        Key: 'Project',
                        Value: 'aws-dsql-demo'
                    }
                ]
            }
        });

        this.dsqlClusterArn = this.dsqlCluster.getAtt('ResourceArn').toString();
        this.dsqlClusterEndpoint = `${this.dsqlCluster.getAtt('Identifier').toString()}.dsql.${this.region}.on.aws`;
    }
}

Step 3:

Moving further to the Lambda layer, I will need to ensure it has the correct permissions to be able to connect to the DSQL Cluster.

export interface FunctionsStackProps extends cdk.StackProps {
    label: {
        id: string;
    },
    domainName: string;
    dsqlClusterEndpoint: string;
    dsqlClusterArn: string;
}

export class FunctionsStack extends cdk.Stack {
    generateGameLambda: lambda.Function;

    constructor(scope: constructs.Construct, id: string, props: FunctionsStackProps) {
        super(scope, `${id}-functions-stack`, props);

        // Create Lambda role with DSQL permissions
        const lambdaRole = new iam.Role(this, 'DSQLLambdaRole', {
            assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
            managedPolicies: [
                iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
            ]
        });

        // Add DSQL permissions
        lambdaRole.addToPolicy(new iam.PolicyStatement({
            effect: iam.Effect.ALLOW,
            actions: [
                'dsql:DbConnect',
                'dsql:ExecuteStatement',
                'dsql:DbConnectAdmin',
            ],
            resources: [props.dsqlClusterArn]
        }));

        this.generateGameLambda = new nodeLambda.NodejsFunction(this, 'GenerateGameLambda', {
            entry: './service/generate-game/Handler.ts',
            runtime: lambda.Runtime.NODEJS_20_X,
            role: lambdaRole,
            environment: {
                DSQL_ENDPOINT: props.dsqlClusterEndpoint
            }
        });
    }
}

I also added the DSQL_ENDPOINT as an environment variable to easily adapt it dynamically when creating a new infrastructure without any manual changes to the Lambda.

Step 4:

One important part of working with Aurora DSQL in Lambda is managing the database connection efficiently. Since Lambdas are ephemeral and scale rapidly, you want to avoid repeatedly initializing database connections which can be expensive and slow.

Here, we create a DatabaseService class that:

Caches the TypeORM DataSource connection so it’s initialized only once per Lambda container lifecycle.
Uses the DsqlSigner from @aws-sdk/dsql-signer to generate secure, temporary authentication tokens to connect to the database without storing passwords.
Leverages TypeORM’s DataSource for managing your entities and database interactions with familiar ORM patterns. We will dive deeper in the second article of the series to explain more on the TypeORM integration.

import "reflect-metadata";
import { DataSource } from "typeorm";
import { DsqlSigner } from "@aws-sdk/dsql-signer";
import { Game } from "../models/Game";

export class DatabaseService {
    private static dataSource: DataSource;

    private static async getAuthToken(host: string): Promise<string> {
        const signer = new DsqlSigner({
            hostname: host,
            region: process.env.AWS_REGION || 'eu-west-2'
        });

        return await signer.getDbConnectAdminAuthToken();
    }

    static async initialize(): Promise<DataSource> {
        if (!DatabaseService.dataSource) {
            const host = process.env.DSQL_ENDPOINT || '';

            DatabaseService.dataSource = new DataSource({
                type: "postgres",
                host: host,
                port: 5432,
                username: 'admin',
                password: await DatabaseService.getAuthToken(host),
                database: "postgres",
                ssl: {
                    rejectUnauthorized: true
                },
                synchronize: true,
                logging: true,
                entities: [Game]
            });

            // Initialize connection to postgres database
            await DatabaseService.dataSource.initialize();
        }

        return DatabaseService.dataSource;
    }

    static async saveGame(game: Partial<Game>): Promise<Game> {
        const dataSource = await DatabaseService.initialize();
        const gameRepository = dataSource.getRepository(Game);

        const newGame = gameRepository.create(game);
        return await gameRepository.save(newGame);
    }
}

Step 5:

Creating the Handler for the Lambda

export async function handler(event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult> {
    console.log(event, context);
    await DatabaseService.initialize();

    try {
        // Generate a random game
        const gameData = generateRandomGame();

        // Save it to the database
        const savedGame = await DatabaseService.saveGame(gameData);

        return {
            statusCode: 200,
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                message: 'Game generated and saved successfully',
                game: savedGame
            })
        };
    } catch (error) {
        console.error('Error generating game:', error);
        return {
            statusCode: 500,
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                message: 'Failed to generate and save game',
                error: error instanceof Error ? error.message : String(error)
            })
        };
    }
}

You can see the response at the API level here.

Manual debugging

You can even connect to the Database directly using the AWS Console.

Go to:

Search AWS DSQL.
Select your cluster.
Press on Connect > Open in Cloudshell.
Connect as admin > Press Run script.
And you're live -> You can directly run SQL Queries.

Achievements in this article:

Set up a clean, scalable project structure separating infrastructure, service code, and CI/CD workflows.
Provisioned an Amazon Aurora DSQL cluster and Lambda functions using AWS CDK, leveraging L1 constructs for the new DSQL resource.
Configured IAM roles and permissions enabling Lambda to securely connect and execute SQL commands on Aurora DSQL.
Implemented an efficient Lambda database connection pattern using TypeORM with AWS DsqlSigner to generate secure temporary auth tokens.
Created a Lambda handler that generates and saves data to Aurora DSQL, exposing it via an API Gateway endpoint secured by an api key.

In the upcoming articles, you’ll learn how to:

Implement business logic with TypeORM entities and migrations
Expose multiple operations on these TypeORM entities via API Gateway, including how to add an effective caching mechanism to improve performance and reduce latency.
Benefits of using AWS DSQL and best practices for efficient & performant infrastructure.

Open Source Repository:

https://github.com/raileanualex/aws-dsql-demo

Documentation:

Smooth AWS Local Development with Localstack, AWS CDK and Typescript

Alex Raileanu — Tue, 08 Apr 2025 12:25:18 +0000

Working with AWS services in real applications is amazing — until you realize how often you need to deploy even for the smallest change. While the cloud offers incredible scalability and flexibility, local development still feels like an afterthought in many serverless workflows.

Why this matters?

In smaller teams, this might not seem like a huge issue — you deploy, test, and move on. But as the team grows and the codebase gets more complex, the friction starts to add up. Waiting for CloudFormation to deploy changes or running integration tests against actual AWS infrastructure can slow down development significantly and make rapid iteration much harder.

How can this be solved?

Not long ago, I stumbled upon a podcast episode about LocalStack v4, and it got me curious. I'd heard of LocalStack before but never gave it a proper try — so I figured, why not?

A couple of commands later, I had my entire AWS CDK project running locally. Lambda, API Gateway, DynamoDB — all spun up on my machine, no cloud deploys needed. It was surprisingly smooth.

What really stood out was how little effort it took. I didn’t have to rewrite anything in my CDK code. LocalStack just worked. It felt like I finally had a proper local dev setup for the cloud — fast, easy to debug, and perfect for experimenting without worrying about breaking something in the real AWS environment.

How to setup your local environment in less than 5 minutes?

Before diving in, here’s a quick look at the tech stack I was using:

Node.js with TypeScript
AWS CDK for infrastructure-as-code
A serverless architecture using Lambda, API Gateway, DynamoDB and IAM.

If that sounds familiar, you're in luck — getting this running locally with LocalStack was way easier than I expected.

Step 1:

Install Local Stack brew install localstack/tap/localstack-cli

Step 2:

Step 3:

Ensure it is correctly installed localstack --version

Step 4:

Start localstack localstack start

Step 5:

Install dependencies needed for CDK globally npm install -g aws-cdk-local aws-cdk

Step 6:

Verify installation cdklocal --version

Step 7:

Ensure that your CDK application is not using hardcoded AWS Account or Region. You should use the Environment Variables.

Step 8:

Add the cdklocal scripts in package.json

"local-deploy": "cdklocal deploy --all",
"local-synth": "cdklocal synth",
"local-bootstrap": "cdklocal bootstrap"`

Step 9:

Run npm run local-synth

Step 10:

Run npm run local-bootstrap

Step 11:

Run npm run local-deploy

Step 12:

Open localstack browser and check created resources: https://app.localstack.cloud/inst/default/resources

Step 13:

You can check the Cloudformation stacks and the resources created and start already testing the application.
You can literally test the API Gateway Endpoint as if it was deployed and see the Cloudwatch logs for that.
I was able to trigger the API using Postman

Important Note: The recommendation from LocalStack is to delete the stacks and re-create them instead of updating them.

Personal thoughts

Local development for AWS has always felt like something you just had to live without — but with tools like LocalStack, that's no longer the case. Whether you're working solo or in a larger team, being able to test and iterate quickly without deploying to the cloud is a game changer.

I was genuinely impressed by how smooth the experience was — and I’ll definitely be including LocalStack in more of my AWS workflows moving forward.

Give it a shot and let me know how it goes!

References:

https://docs.localstack.cloud/getting-started/
https://github.com/raileanualex/serverless-api [ Basic similar setup as reference ]
https://www.youtube.com/watch?v=vVUBnXD6eto