Skip to main content

Getting Started with Databases

This guide walks you through setting up your first database connection in Ductape, from installation to executing your first query.

Prerequisites​

Before you begin, make sure you have:

  1. A Ductape account and workspace
  2. A product created in your workspace
  3. Access to a database (PostgreSQL, MySQL, MongoDB, or DynamoDB)
  4. The Ductape SDK installed in your project

Step 1: Install the SDK​

Install the Ductape SDK:

npm install @ductape/sdk@0.1.8

The SDK includes all database drivers (PostgreSQL, MySQL, MongoDB, DynamoDB) out of the box.

Step 2: Initialize the SDK​

Set up the Ductape SDK with your credentials. Set product and env on the constructor (runtime defaults):

import Ductape from '@ductape/sdk';

const ductape = new Ductape({
  accessKey: 'your-access-key',
});

Step 3: Register a Database​

Register your database with environment-specific connection strings:

await ductape.databases.create({
  product_tag: 'my-app',
  name: 'User Database',
  tag: 'users-db',
  type: 'postgresql',
  description: 'Stores user accounts and profiles',
  envs: [
    {
      slug: 'dev',
      connection_url: 'postgresql://localhost:5432/myapp_dev',
    },
    {
      slug: 'stg',
      connection_url: 'postgresql://staging-host:5432/myapp_staging',
    },
    {
      slug: 'prd',
      connection_url: 'postgresql://prod-host:5432/myapp_prod',
    },
  ],
});

You can also link a managed PostgreSQL instance from a workspace cloud account by tag — Ductape imports or provisions the instance and stores the connection URL as a secret.

Check available tiers before provisioning to control cost:

const tiers = await ductape.cloud.tiers.list({ provider: 'aws', resource_type: 'database', db_type: 'postgresql' });
// tiers[0].tiers → [{ name: 'db.t3.micro', label: 'Micro — 2 vCPU, 1 GB', est_cost_per_month: 11.68, free_tier: true }, …]

AWS RDS:

await ductape.databases.create({
  product: 'my-app',
  name: 'User Database',
  tag: 'users-db',
  type: 'postgresql',
  envs: [{
    slug: 'prd',
    cloud: 'prod_aws',
    instance: 'my-rds-instance',
    tier: 'db.t3.micro',   // from cloud.tiers.list()
    region: 'us-east-1',
  }],
});

GCP Cloud SQL (PostgreSQL):

await ductape.databases.create({
  product: 'my-app',
  name: 'User Database',
  tag: 'users-db',
  type: 'postgresql',
  envs: [{
    slug: 'prd',
    cloud: 'gcp_prod',
    instance: 'my-cloudsql-instance',
    tier: 'db-n1-standard-2',
    region: 'us-central1',
  }],
});

Azure PostgreSQL Flexible Server:

await ductape.databases.create({
  product: 'my-app',
  name: 'User Database',
  tag: 'users-db',
  type: 'postgresql',
  envs: [{
    slug: 'prd',
    cloud: 'prod_azure',
    instance: 'my-pg-server',
    tier: 'Standard_B1ms',
    region: 'eastus',
  }],
});

See Cloud-linked components for the full AWS / GCP / Azure matrix, tier reference, and setup steps.

Database Configuration Fields​

FieldTypeRequiredDescription
product_tagstringYesProduct identifier to associate the database with
namestringYesHuman-readable display name
tagstringYesUnique identifier for the database
typestringYesDatabase type: postgresql, mysql, mongodb, or dynamodb
descriptionstringNoDescription of what the database stores
envsarrayYesEnvironment-specific connection configurations

Environment Configuration​

FieldTypeRequiredDescription
slugstringYesEnvironment identifier (e.g., dev, staging, prd)
connection_urlstringYesDatabase connection string
descriptionstringNoEnvironment-specific notes

Step 4: Connect to Your Database​

Before running queries, establish a connection:

const result = await ductape.databases.connect({
  database: 'users-db',
});

console.log('Connected:', result.connected); console.log('Database Version:', result.version); console.log('Latency:', result.latency, 'ms');


Once connected, subsequent operations inherit the connection context. You no longer need to specify `env`, `product`, or `database` on every query (constructor defaults apply before connect; connection context applies after).

## Step 5: Run Your First Query

With the connection established, you can query your database:

```ts
// Query all active users
const result = await ductape.databases.find({
  table: 'users',
  where: { status: 'active' },
  limit: 10,
});

console.log('Found users:', result.records);
console.log('Total count:', result.count);

Step 6: Insert Data​

Add new records to your database:

const result = await ductape.databases.insert({
  table: 'users',
  records: [{
    name: 'Jane Doe',
    email: 'jane@example.com',
    status: 'active',
    created_at: new Date(),
  }],
  returning: true,
});

console.log('Inserted user ID:', result.insertedIds[0]);
console.log('Inserted data:', result.records);

Complete Example​

Here's a complete example bringing it all together:

import Ductape from '@ductape/sdk';

async function main() {
  // Initialize SDK
  const ductape = new Ductape({
    accessKey: 'your-access-key',
  });

  // Register database (usually done once during setup)
  await ductape.databases.create({
    product_tag: 'my-app',
    name: 'User Database',
    tag: 'users-db',
    type: 'postgresql',
    envs: [
      { slug: 'dev', connection_url: 'postgresql://localhost:5432/myapp_dev' },
      { slug: 'prd', connection_url: 'postgresql://prod-host:5432/myapp_prod' },
    ],
  });

  // Connect to database
  await ductape.databases.connect({
    database: 'users-db',
  });

  // Insert a new user
  const insertResult = await ductape.databases.insert({
    table: 'users',
    records: [{
      name: 'John Doe',
      email: 'john@example.com',
      status: 'active',
    }],
    returning: true,
  });

  console.log('Created user:', insertResult.records);

  // Query users
  const queryResult = await ductape.databases.find({
    table: 'users',
    where: { status: 'active' },
    orderBy: [{ column: 'created_at', order: 'DESC' }],
    limit: 10,
  });

  console.log('Active users:', queryResult.records);

  // Count total users
  const count = await ductape.databases.count({
    table: 'users',
  });

  console.log('Total users:', count);

  // Close connections when done
  await ductape.databases.closeAll();
}

main().catch(console.error);

Testing Your Connection​

Use the testConnection method to verify connectivity without performing operations:

const result = await ductape.databases.testConnection({
  database: 'users-db',
});

if (result.connected) {
  console.log('Connection successful!');
  console.log('Version:', result.version);
  console.log('Latency:', result.latency, 'ms');
} else {
  console.error('Connection failed:', result.error);
}

Managing Multiple Databases​

You can register and use multiple databases in a single product:

// Register multiple databases
await ductape.databases.create({
  product_tag: 'my-app',
  name: 'User Database',
  tag: 'users-db',
  type: 'postgresql',
  envs: [{ slug: 'dev', connection_url: '...' }],
});

await ductape.databases.create({
  product_tag: 'my-app',
  name: 'Analytics Database',
  tag: 'analytics-db',
  type: 'mongodb',
  envs: [{ slug: 'dev', connection_url: '...' }],
});

await ductape.databases.create({
  product_tag: 'my-app',
  name: 'Session Store',
  tag: 'sessions-db',
  type: 'dynamodb',
  envs: [{ slug: 'dev', connection_url: '...' }],
});

// Switch between databases by connecting to each (product/env from constructor)
await ductape.databases.connect({ database: 'users-db' });

// Query users database
const users = await ductape.databases.find({ table: 'users' });

// Connect to a different database
await ductape.databases.connect({ database: 'analytics-db' });

// Query analytics database
const events = await ductape.databases.find({ table: 'events' });

Updating Database Configuration​

Update an existing database configuration:

await ductape.databases.update('my-app', 'users-db', {
  name: 'User Database v2',
  description: 'Updated user storage',
  envs: [
    { slug: 'dev', connection_url: 'postgresql://new-dev-host:5432/myapp' },
    { slug: 'prd', connection_url: 'postgresql://new-prod-host:5432/myapp' },
  ],
});

Fetching Database Information​

Retrieve information about your registered databases:

// Get all databases in the product
const databases = await ductape.databases.fetchAll('my-app');

databases.forEach((database) => {
  console.log(`${database.name} (${database.tag}): ${database.type}`);
});

// Get a specific database
const usersDb = await ductape.databases.fetch('my-app', 'users-db');
console.log('Database:', usersductape.databases.name);
console.log('Type:', usersductape.databases.type);
console.log('Environments:', usersductape.databases.envs);

Connection String Formats​

PostgreSQL​

postgresql://username:password@host:port/database
postgresql://user:pass@localhost:5432/myapp

MySQL​

mysql://username:password@host:port/database
mysql://user:pass@localhost:3306/myapp

MongoDB​

mongodb://username:password@host:port/database
mongodb://user:pass@localhost:27017/myapp
mongodb+srv://user:pass@cluster.mongoductape.databases.net/myapp

DynamoDB​

dynamodb://region/access-key-id/secret-access-key
# Or use AWS credential configuration
dynamodb://us-east-1

Next Steps​

Now that you have your database set up, learn how to:

See Also​