Skip to main content

Switch Database Context

Switch the active database context for all subsequent SDK operations. When you switch to a database, all table, record, column, index, and SQL operations automatically target that database until you switch again or reset to the default database.

Method Signatures​

// Switch to a database by internal name (slug)
client.useDatabase(dbInternalName?: string): Promise<void>

// Get the current database context
client.getCurrentDatabase(): { databaseId?: string; dbInternalName?: string } | null

Parameters​

useDatabase Parameters​

ParameterTypeRequiredDescription
dbInternalNamestring❌Database internal name (slug) to switch to. If omitted or empty, resets to default database.

getCurrentDatabase Parameters​

The getCurrentDatabase() method takes no parameters.

Return Value​

useDatabase Return Value​

useDatabase() returns Promise<void>. It throws an error if the database with the specified internal name is not found.

getCurrentDatabase Return Value​

interface DatabaseContext {
    databaseId?: string; // Database UUID
    dbInternalName?: string; // Database internal name (slug)
}

// Returns DatabaseContext | null
  • Returns { databaseId, dbInternalName } when a custom database is active
  • Returns null when using the default database

Behavior​

Default Database​

If you never call useDatabase(), the SDK automatically uses your account's default Boltic Cloud database for all operations. This ensures backward compatibility with existing code.

Switching Context​

When you call useDatabase(dbInternalName):

  1. The SDK looks up the database by its db_internal_name (slug)
  2. Stores the database id and db_internal_name as the current context
  3. All subsequent operations on tables, records, columns, indexes, and sql automatically target the specified database.

Resetting to Default​

Call useDatabase() with no argument (or an empty string) to reset the context back to the default database. This clears the stored context and all operations will use the default database again.

Examples​

Basic Database Switching​

import { createClient } from "@boltic/sdk";

const client = createClient("your-api-key");

// Switch to a custom database
await client.useDatabase("demo_primary_db");

// All subsequent operations target this database
const { data: tables } = await client.tables.findAll(); // Runs against demo_primary_db
const { data: records } = await client.records.findAll("my_table"); // Runs against demo_primary_db

// Switch back to default database
await client.useDatabase();

Inspect Current Context​

// Switch to a database
await client.useDatabase("my_custom_db");

// Check current context
const context = client.getCurrentDatabase();

if (context) {
    console.log("Current database:", context.dbInternalName);
    console.log("Database ID:", context.databaseId);
} else {
    console.log("Using default database");
}