Database Management

Oblien Sandbox provides full SQLite database management capabilities, allowing you to create databases, manage schemas, execute queries, and handle data operations within your isolated environment.

Overview

The database API supports:

Database Operations - Create, delete, and manage databases
Table Management - Create tables, modify schemas, manage indexes
Data Operations - Insert, update, delete, and query data
Import/Export - Export to JSON/CSV/SQL, import from JSON
Advanced Features - Transactions, foreign keys, table analysis

Create Database

Create a new SQLite database in your sandbox.

await sandbox.database.createDatabase({
  name: 'myapp'
});

Parameters:

name (string, required) - Database name

await fetch(`${sandbox.url}/database/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'myapp'
  })
});

curl -X POST https://sandbox.oblien.com/database/create \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "myapp"}'

Response:

{
  "success": true,
  "message": "Database created successfully",
  "database": "myapp",
  "path": "/opt/databases/myapp.db"
}

List Databases

Get a list of all databases in your sandbox.

const result = await sandbox.database.listDatabases();
console.log(result.databases);

const response = await fetch(`${sandbox.url}/database/list`, {
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

const result = await response.json();

curl https://sandbox.oblien.com/database/list \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN"

Response:

{
  "success": true,
  "databases": [
    {
      "name": "myapp",
      "size": 32768,
      "tables": 3,
      "created": "2025-10-27T10:00:00Z"
    }
  ]
}

Get Database Info

Get detailed information about a database.

const info = await sandbox.database.getDatabaseInfo('myapp');
console.log(info);

const response = await fetch(`${sandbox.url}/database/myapp/info`, {
  headers: {
    'Authorization': `Bearer ${sandbox.token}`
  }
});

const info = await response.json();

curl https://sandbox.oblien.com/database/myapp/info \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN"

Response:

{
  "success": true,
  "database": "myapp",
  "size": 32768,
  "tables": ["users", "posts", "comments"],
  "tableCount": 3,
  "path": "/opt/databases/myapp.db",
  "created": "2025-10-27T10:00:00Z",
  "modified": "2025-10-27T12:30:00Z"
}

Delete Database

Delete a database and all its tables.

await sandbox.database.deleteDatabase({
  database: 'myapp'
});

await fetch(`${sandbox.url}/database/delete`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    database: 'myapp'
  })
});

curl -X POST https://sandbox.oblien.com/database/delete \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"database": "myapp"}'

Response:

{
  "success": true,
  "message": "Database deleted successfully",
  "database": "myapp"
}

Create Table

Create a new table with specified columns and constraints.

await sandbox.database.createTable({
  database: 'myapp',
  tableName: 'users',
  columns: [
    {
      name: 'id',
      type: 'INTEGER',
      primaryKey: true,
      autoIncrement: true
    },
    {
      name: 'name',
      type: 'TEXT',
      notNull: true
    },
    {
      name: 'email',
      type: 'TEXT',
      unique: true,
      notNull: true
    },
    {
      name: 'age',
      type: 'INTEGER'
    },
    {
      name: 'created_at',
      type: 'DATETIME',
      defaultValue: 'CURRENT_TIMESTAMP'
    }
  ]
});

Column Types:

INTEGER - Whole numbers
TEXT - String data
REAL - Floating point numbers
BLOB - Binary data
DATETIME - Date and time values

Column Options:

primaryKey (boolean) - Mark as primary key
autoIncrement (boolean) - Auto-increment (INTEGER only)
notNull (boolean) - NOT NULL constraint
unique (boolean) - UNIQUE constraint
defaultValue (any) - Default value

await fetch(`${sandbox.url}/database/myapp/tables/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tableName: 'users',
    columns: [
      {
        name: 'id',
        type: 'INTEGER',
        primaryKey: true,
        autoIncrement: true
      },
      {
        name: 'name',
        type: 'TEXT',
        notNull: true
      },
      {
        name: 'email',
        type: 'TEXT',
        unique: true,
        notNull: true
      }
    ]
  })
});

curl -X POST https://sandbox.oblien.com/database/myapp/tables/create \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tableName": "users",
    "columns": [
      {
        "name": "id",
        "type": "INTEGER",
        "primaryKey": true,
        "autoIncrement": true
      }
    ]
  }'

Response:

{
  "success": true,
  "message": "Table created successfully",
  "database": "myapp",
  "table": "users"
}

Insert Data

Insert a row into a table.

await sandbox.database.insertRow({
  database: 'myapp',
  table: 'users',
  data: {
    name: 'John Doe',
    email: 'john@example.com',
    age: 30
  }
});

await fetch(`${sandbox.url}/database/myapp/tables/users/insert`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      name: 'John Doe',
      email: 'john@example.com',
      age: 30
    }
  })
});

curl -X POST https://sandbox.oblien.com/database/myapp/tables/users/insert \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "age": 30
    }
  }'

Response:

{
  "success": true,
  "message": "Row inserted successfully",
  "insertedId": 1,
  "rowsAffected": 1
}

Query Data

Get data from a table with pagination, sorting, and filtering.

const result = await sandbox.database.getTableData({
  database: 'myapp',
  table: 'users',
  page: 1,
  limit: 10,
  sortBy: 'created_at',
  sortOrder: 'desc',
  where: {
    age: 30
  }
});

console.log(result.data);

Parameters:

database (string, required) - Database name
table (string, required) - Table name
page (number) - Page number (default: 1)
limit (number) - Results per page (default: 50)
sortBy (string) - Column to sort by
sortOrder (string) - 'asc' or 'desc'
where (object) - Filter conditions

const response = await fetch(`${sandbox.url}/database/myapp/tables/users/data`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    page: 1,
    limit: 10,
    sortBy: 'created_at',
    sortOrder: 'desc',
    where: { age: 30 }
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/database/myapp/tables/users/data \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 10,
    "sortBy": "created_at",
    "sortOrder": "desc"
  }'

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "age": 30,
      "created_at": "2025-10-27T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  }
}

Execute Custom Query

Execute raw SQL queries for complex operations.

const result = await sandbox.database.executeQuery({
  database: 'myapp',
  query: 'SELECT * FROM users WHERE age > ? AND name LIKE ?',
  params: [25, '%John%']
});

console.log(result.rows);

const response = await fetch(`${sandbox.url}/database/myapp/query`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'SELECT * FROM users WHERE age > ? AND name LIKE ?',
    params: [25, '%John%']
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/database/myapp/query \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE age > ?",
    "params": [25]
  }'

Response:

{
  "success": true,
  "rows": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "age": 30
    }
  ],
  "rowCount": 1
}

Complete Example

// Create database
await sandbox.database.createDatabase({ name: 'myapp' });

// Create table
await sandbox.database.createTable({
  database: 'myapp',
  tableName: 'users',
  columns: [
    { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
    { name: 'name', type: 'TEXT', notNull: true },
    { name: 'email', type: 'TEXT', unique: true }
  ]
});

// Insert data
await sandbox.database.insertRow({
  database: 'myapp',
  table: 'users',
  data: { name: 'John Doe', email: 'john@example.com' }
});

// Query data
const users = await sandbox.database.getTableData({
  database: 'myapp',
  table: 'users',
  limit: 10
});

console.log(users.data);

// Update data
await sandbox.database.updateRow({
  database: 'myapp',
  table: 'users',
  data: { name: 'John Smith' },
  where: { email: 'john@example.com' }
});

// Export to JSON
const json = await sandbox.database.exportTableToJSON('myapp', 'users');

// Create database
await fetch(`${sandbox.url}/database/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'myapp' })
});

// Create table
await fetch(`${sandbox.url}/database/myapp/tables/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tableName: 'users',
    columns: [
      { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
      { name: 'name', type: 'TEXT', notNull: true }
    ]
  })
});

// Insert and query as shown above

# Create database
curl -X POST https://sandbox.oblien.com/database/create \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "myapp"}'

# Create table
curl -X POST https://sandbox.oblien.com/database/myapp/tables/create \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tableName": "users",
    "columns": [
      {"name": "id", "type": "INTEGER", "primaryKey": true}
    ]
  }'

Best Practices

Use parameterized queries: Always use parameters (?) instead of string interpolation to prevent SQL injection
Index frequently queried columns: Create indexes on columns used in WHERE clauses
Use transactions for multiple operations: Wrap related operations in transactions for atomicity
Handle errors gracefully: Always wrap database operations in try-catch blocks
Backup before schema changes: Export database before making structural changes

Next Steps

Database Tables - Advanced table operations
Database Queries - Complex queries and transactions
Database Import/Export - Data migration

On this page