Database.do vs. Databases.do: Single Instance vs. Fleet Management Explained

In the world of modern software development, managing a single database is one thing. Managing a sprawling collection of them—spread across different environments, cloud providers, and projects—is another challenge entirely. As infrastructure becomes more complex, the need for clear, programmatic control has never been greater.

This is the core principle behind the .do Agentic Workflow Platform: turning complex infrastructure management into simple, repeatable code. Within this ecosystem, you'll find powerful agents for handling data, but two, in particular, can cause confusion: database.do and databases.do.

They sound similar, but their roles are distinct and complementary. Understanding the difference is key to unlocking the full power of managing your data infrastructure as code. Let's break down the micro view versus the macro view.

The Micro View: database.do for Single Instance Operations

Think of database.do as your specialized tool for working inside a single database instance. Once a database is up and running, this is the agent you'll use to interact directly with its content and structure.

Its primary jobs include:

Schema Management: Applying migrations or altering table structures.
Query Execution: Running SELECT, INSERT, UPDATE, or DELETE statements.
User & Permission Management: Creating roles and granting specific access within that database.
Specific Backups & Restores: Triggering a backup or restore for that single instance.

When to use database.do: You would use this agent when your application needs to perform a task within a known database. It’s perfect for a microservice that needs to read from or write to its dedicated database, or for an administrative script that needs to perform maintenance on a specific instance.

// A conceptual example for a single instance
import { Do } from '@do-sdk/core';
const ado = new Do();

// Access a specific database instance
const myAppDb = ado.use('database.do', { instanceId: 'prod-user-db-123' });

// Run a query within that specific database
const activeUsers = await myAppDb.query('SELECT * FROM users WHERE status = ?', ['active']);

console.log(`${activeUsers.length} active users found.`);

In short, database.do focuses on the data and schema within one database.

The Macro View: databases.do for Fleet Orchestration

If database.do is the specialist, databases.do is the general contractor. It’s a higher-level agent that acts as a control plane for your entire collection, or "fleet," of databases. It doesn't query tables; it provisions, monitors, and organizes the database instances themselves.

This is where true database fleet management comes to life.

Its primary jobs include:

Provisioning: Creating new database instances across any supported cloud (AWS, GCP, Azure) with a single API call.
Listing & Discovery: Getting an inventory of all managed database instances, regardless of type or provider.
Configuration: Modifying instance-level settings like size or region.
Decommissioning: Safely destroying database instances that are no longer needed.

This agent turns data orchestration from a manual, multi-console nightmare into a clean, automated workflow.

import { Do } from '@do-sdk/core';

// Initialize the .do client
const ado = new Do();

// Access the databases agent for fleet management
const myDatabases = ado.use('databases.do');

// List all managed database instances in our fleet
const allInstances = await myDatabases.list();

console.log(allInstances);

// Provision a new PostgreSQL database on AWS
const newStagingDb = await myDatabases.create({
  type: 'postgres',
  provider: 'aws',
  region: 'us-east-1',
  plan: 'small',
});

console.log(`Successfully provisioned: ${newStagingDb.instanceId}`);

Key Differences at a Glance

Feature	database.do (Single Instance)	databases.do (Fleet)
Scope	A single, specific database.	An entire collection of databases.
Primary Job	Interacting with data and schema.	Provisioning and orchestrating instances.
Analogy	A specialized tool (e.g., a screwdriver).	The entire toolbox and project plan.
Common Verbs	query(), migrate(), backup()	create(), list(), describe(), destroy()
Use Case	An app writing to its database.	A CI/CD pipeline setting up a new env.

The Power of a Unified Workflow

Why have both? Because this layered approach is the key to mastering database as code.

Your CI/CD pipeline can use the databases.do agent to spin up a complete set of databases for a new testing environment. Once created, individual services can use the database.do agent to connect to their specific instance, run migrations, and seed test data. When the tests are done, the pipeline calls databases.do again to tear the entire environment down.

This agentic workflow abstracts away the complexity of multi-cloud APIs and manual configuration. It provides a single, secure, and programmable interface to manage your data infrastructure, from a single query to a global fleet.

Ready to stop wrestling with individual database consoles and start orchestrating your data infrastructure as a single, cohesive service?