Skip to main content

​
Overview

The APPSQL class is the primary interface for ServiceSQL. It manages the connection to your Google Spreadsheet and provides access to query builders, models, schemas, and other features.

​
Initialization

​
init()

Initialize APPSQL as a singleton instance. 
const db = APPSQL.init({ spreadsheetId: 'your-spreadsheet-id' });
​
config
object
required
Configuration object for APPSQL
​
config.spreadsheetId
string
required
The ID of the Google Spreadsheet to use as database
​
return
APPSQL
Returns the singleton APPSQL instance
init() follows the singleton pattern. Calling it multiple times returns the same instance.

​
getInstance()

Get the existing APPSQL singleton instance. 
const db = APPSQL.getInstance();
​
return
APPSQL
Returns the existing APPSQL instance
Throws an error if init() has not been called first.

​
Core Methods

​
table()

Create a query builder for a specific sheet/table. 
const users = db.table('Users')
  .where('status', 'active')
  .orderBy('created_at', 'desc')
  .get();
​
sheetName
string
required
Name of the sheet to query
​
return
QueryBuilder
Returns a new QueryBuilder instance for the specified sheet

​
model()

Register and configure a Model class with the database. 
class User extends Model {
  static tableName = 'Users';
  static _timestamps = true;
  static _fillable = ['name', 'email', 'status'];
}

const UserModel = db.model(User);

// Now you can use the model
const user = User.find(1);
​
ModelClass
class
required
A Model class to register with the database
​
return
class
Returns the registered Model class with database connection configured

​
What model() Does

  1. Links the database connection: Assigns app, driver, and _db to the Model class
  2. Resolves table name: Uses tableName, table, or the class name as the table
  3. Calls boot(): Executes the Model’s boot() method once for initialization
  4. Enables queries: Allows the Model to execute database queries
class Product extends Model {
  static tableName = 'Products';
  static _primaryKey = 'id';
  static _timestamps = true;
  static _fillable = ['name', 'price', 'stock'];
  static _casts = {
    price: 'float',
    stock: 'integer'
  };
  
  static boot() {
    console.log('Product model booted');
  }
}

// Register the model
db.model(Product);

// Now you can use it
const product = Product.create({
  name: 'Laptop',
  price: 999.99,
  stock: 50
});

​
Additional Features

​
schema()

Access schema management features for creating and modifying sheets. 
const schema = db.schema();
​
return
Schema
Returns a Schema builder instance

​
gmail()

Access Gmail integration features. 
const gmail = db.gmail();
​
return
GmailBuilder
Returns a GmailBuilder instance for email operations

​
triggers()

Manage Apps Script triggers. 
const triggers = db.triggers();
​
return
TriggerBuilder
Returns a TriggerBuilder instance

​
cache()

Access caching utilities. 
const cache = db.cache();
​
return
CacheBuilder
Returns a CacheBuilder instance for caching operations

​
utils()

Access utility functions. 
const utils = db.utils();
​
return
Utils
Returns a Utils instance with helper methods

​
db()

Create a table instance directly. 
const table = db.db('Users', ['id', 'name', 'email']);
​
name
string
required
Name of the table
​
columns
array
default:"[]"
Array of column names
​
return
Table
Returns a Table instance

​
Complete Example

// Initialize the database
const db = APPSQL.init({ 
  spreadsheetId: '1abc...xyz' 
});

// Define a model
class User extends Model {
  static tableName = 'Users';
  static _timestamps = true;
  static _fillable = ['name', 'email', 'role'];
}

// Register the model
db.model(User);

// Use the model
const activeUsers = User
  .where('status', 'active')
  .orderBy('created_at', 'desc')
  .get();

// Or use the query builder directly
const orders = db.table('Orders')
  .where('status', 'pending')
  .where('total', '>', 100)
  .get();

// In other files, get the instance
const db2 = APPSQL.getInstance();
const products = db2.table('Products').all();

​
Properties

​
spreadsheetId
Spreadsheet
The opened Google Spreadsheet instance
​
driver
SheetDriver
The underlying driver that handles sheet operations
​
instance
APPSQL
Static property holding the singleton instance

Build docs developers (and LLMs) love

Get started for freeTalk to us