CDK Turso

CDK constructs to create Turso cloud databases and manage auth tokens.

Installation

npm install cdk-turso

Usage

Create a TursoProvider with your API token:

import { RemovalPolicy, Stack } from 'aws-cdk-lib';
import { ParameterType, StringParameter } from 'aws-cdk-lib/aws-ssm';
import { TursoProvider, TursoDatabase, TursoAuthToken } from 'cdk-turso';

const stack = new Stack();

// SSM Parameter containing your Turso API token (must be a SecureString)
const apiToken = new StringParameter(stack, 'TursoApiToken', {
  parameterName: '/turso/api-token',
  stringValue: 'your-api-token',
  type: ParameterType.SECURE_STRING,
});

// Create the provider (one per stack)
const provider = new TursoProvider(stack, 'TursoProvider', {
  apiToken,
});

const database = new TursoDatabase(stack, 'Database', {
  provider,
  databaseName: 'my-database',
  group: 'group-name',
  organizationSlug: 'my-org',
  adopt: true, // optional: adopt existing database if it already exists
  removalPolicy: RemovalPolicy.RETAIN, // optional: keep DB on stack delete
});

// Access database attributes
database.dbId;      // Database ID
database.hostname;  // Database hostname (e.g., my-database-my-org.turso.io)
database.databaseName;  // Database name

Use RemovalPolicy.SNAPSHOT to create a point-in-time Turso database copy before the database is deleted:

new TursoDatabase(stack, 'DatabaseWithFinalSnapshot', {
  provider,
  databaseName: 'my-database',
  group: 'group-name',
  organizationSlug: 'my-org',
  removalPolicy: RemovalPolicy.SNAPSHOT,
});

Snapshots are implemented by creating a new Turso database from the source database at delete time. Changing to RemovalPolicy.SNAPSHOT does not update the existing Turso database; it only affects a later delete operation.

If you run a shared provider in another stack, import it by service token:

const provider = TursoProvider.fromServiceToken(
  stack,
  'TursoProvider',
  'arn:aws:lambda:us-east-1:123456789012:function:shared-turso-provider',
);

Auth Token

Generate a database auth token and store it as a SecureString in SSM Parameter Store:

const authToken = new TursoAuthToken(stack, 'AuthToken', {
  provider,
  databaseName: database.databaseName,
  organizationSlug: 'my-org',
  parameterName: '/turso/db-token',
  expiration: '2w',          // optional, default: 'never'
  authorization: 'read-only', // optional, default: 'full-access'
  removalPolicy: RemovalPolicy.RETAIN, // optional: keep SSM parameter
});

// The SSM parameter name where the JWT is stored
authToken.parameterName;

API

TursoProviderProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiToken | ssm.IParameter | Yes | SSM Parameter containing the Turso platform API token (must be SecureString) | | logGroup | ILogGroup | No | Optional CloudWatch log group for the Lambda handler |

TursoProvider

| Attribute | Type | Description | |-----------|------|-------------| | handler | Function | The Lambda function backing all Turso custom resources (for attaching IAM permissions) | | serviceToken | string | The CDK custom-resource provider service token |

Static method:

| Method | Returns | Description | |--------|---------|-------------| | fromServiceToken(scope, id, serviceToken) | ITursoProvider | Imports an existing Turso custom-resource provider |

ITursoProvider

| Attribute | Type | Description | |-----------|------|-------------| | serviceToken | string | The CDK custom-resource provider service token |

TursoDatabaseProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | provider | ITursoProvider | Yes | The Turso provider to use for this database | | databaseName | string | Yes | Database name (lowercase, numbers, dashes only, max 64 chars) | | group | string | Yes | Turso group name (must already exist) | | organizationSlug | string | Yes | Organization slug | | sizeLimit | string | No | Size limit (e.g., '256mb') | | seed | TursoDatabaseSeed | No | Database seed configuration | | encryption | TursoDatabaseEncryption | No | Encryption configuration | | adopt | boolean | No | On create, adopt an existing database when create returns "already exists" | | removalPolicy | RemovalPolicy | No | RemovalPolicy.RETAIN keeps the DB. RemovalPolicy.SNAPSHOT creates a point-in-time Turso DB copy before delete. |

TursoDatabaseSeed

interface TursoDatabaseSeed {
  readonly type: string;      // Seed type (e.g., 'schema')
  readonly name: string;       // Seed name
  readonly timestamp?: string;  // Optional timestamp
}

TursoDatabaseEncryption

interface TursoDatabaseEncryption {
  readonly encryptionKey: string;    // KMS key ARN
  readonly encryptionCipher: string; // Cipher type (e.g., 'AES')
}

TursoDatabase

| Attribute | Type | Description | |-----------|------|-------------| | dbId | string | Turso database ID | | hostname | string | DNS hostname (e.g., my-database-my-org.turso.io) for libSQL/HTTP connections | | databaseName | string | Database name |

TursoAuthTokenProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | provider | ITursoProvider | Yes | The Turso provider to use for this auth token | | databaseName | string | Yes | The name of the Turso database to create an auth token for | | organizationSlug | string | Yes | The Turso organization slug that owns the database | | parameterName | string | Yes | SSM parameter name where the generated JWT will be stored as a SecureString | | expiration | string | No | Token expiry (e.g., '2w', '1d30m'). Default: 'never' | | authorization | string | No | 'full-access' or 'read-only'. Default: 'full-access' | | removalPolicy | RemovalPolicy | No | Custom resource removal policy (for example RemovalPolicy.RETAIN) |

TursoAuthToken

| Attribute | Type | Description | |-----------|------|-------------| | parameterName | string | The SSM parameter name where the auth token is stored |

Requirements

• Node.js 24.x runtime for the Lambda handler
• The Lambda handler requires the AWS SDK for JavaScript v3 (pre-installed in Lambda runtime)