Lightweight SDK for bridging base44 applications with Azure PostgreSQL Flexible Server
npm install summit1A lightweight JavaScript SDK for bridging base44 applications with Azure PostgreSQL Flexible Server. Summit1 provides a seamless interface for manipulating external PostgreSQL data using familiar base44 SDK patterns.
Summit1 enables base44 applications to interact with external Azure PostgreSQL databases as naturally as they handle native data. The SDK mirrors the base44 SDK's calling conventions, making it intuitive for developers already familiar with base44.
- base44-Compatible API: Familiar entity-based access patterns
- Full CRUD Operations: Create, Read, Update, Delete with filtering, sorting, and pagination
- Bulk Operations: Efficient batch create and delete operations
- Data Transformation: Automatic conversion between PostgreSQL and base44 data formats
- Connection Pooling: Built-in connection pool for optimal performance
- SSL/TLS Support: Secure connections with certificate validation
- Type Safety: Proper handling of PostgreSQL data types (JSON, arrays, dates, etc.)
- Error Handling: Comprehensive error management with detailed messages
- Transaction Support: ACID-compliant operations for data integrity
``bash`
npm install summit1
`javascript
import { createClient } from 'summit1';
const summit1 = createClient({
host: 'somedb.postgres.database.azure.com',
user: 'your_username',
password: 'your_password',
database: 'your_database',
port: 5432,
ssl: { rejectUnauthorized: false }
});
`
`javascript
// Create a record
const user = await summit1.entities.users.create({
name: 'John Doe',
email: 'john@example.com',
age: 30
});
// Read a record
const foundUser = await summit1.entities.users.get(user.id);
// List all records
const allUsers = await summit1.entities.users.list();
// Filter records
const activeUsers = await summit1.entities.users.filter({
status: 'active'
});
// Update a record
const updatedUser = await summit1.entities.users.update(user.id, {
age: 31
});
// Delete a record
await summit1.entities.users.delete(user.id);
`
#### createClient(config)
Creates a new Summit1 client with database connection.
Parameters:
- config (Object): Configuration objecthost
- (string, required): Azure PostgreSQL host addressuser
- (string, required): Database usernamepassword
- (string, required): Database passworddatabase
- (string): Database name (default: "postgres")port
- (number): Database port (default: 5432)sslCert
- (string): Path to SSL certificate filessl
- (object): Custom SSL configuration
Returns:
- Client object with entities property and utility methods
Example:
`javascript`
const summit1 = createClient({
host: 'mydb.postgres.database.azure.com',
user: 'admin',
password: 'securepassword',
database: 'myapp',
sslCert: './certs/baltimore-cybertrust-root.pem'
});
Entities are accessed via summit1.entities.tableName, where tableName is your PostgreSQL table name.
#### create(data)
Creates a new record.
Parameters:
- data (Object): Record data
Returns:
- Promise
Example:
`javascript`
const task = await summit1.entities.tasks.create({
title: 'Complete documentation',
status: 'pending',
priority: 'high'
});
#### get(id)
Retrieves a single record by ID.
Parameters:
- id (string|number): Record ID
Returns:
- Promise
Example:
`javascript`
const task = await summit1.entities.tasks.get(123);
#### list(options)
Lists records with optional filtering, sorting, and pagination.
Parameters:
- options (Object):filter
- (Object): Filter criteriasort
- (string|Array): Sort specification (e.g., "created_at:desc" or ["status:asc", "priority:desc"])limit
- (number): Maximum records to returnoffset
- (number): Number of records to skipselect
- (Array
Returns:
- Promise
Example:
`javascript`
const tasks = await summit1.entities.tasks.list({
filter: { status: 'pending' },
sort: 'priority:desc',
limit: 10,
offset: 0,
select: ['id', 'title', 'priority']
});
#### filter(filters, options)
Filters records matching criteria.
Parameters:
- filters (Object): Filter criteriaoptions
- (Object): Additional options (sort, limit, offset, select)
Returns:
- Promise
Example:
`javascript`
const tasks = await summit1.entities.tasks.filter({
status: 'pending',
priority: 'high'
}, {
sort: 'created_at:desc'
});
#### update(id, data)
Updates a record.
Parameters:
- id (string|number): Record IDdata
- (Object): Fields to update
Returns:
- Promise
Example:
`javascript`
const updated = await summit1.entities.tasks.update(123, {
status: 'completed'
});
#### delete(id)
Deletes a single record.
Parameters:
- id (string|number): Record ID
Returns:
- Promise
Example:
`javascript`
await summit1.entities.tasks.delete(123);
#### deleteMany(filters)
Deletes multiple records matching criteria.
Parameters:
- filters (Object): Filter criteria
Returns:
- Promise
Example:
`javascript`
const result = await summit1.entities.tasks.deleteMany({
status: 'completed',
priority: 'low'
});
console.log('Deleted', result.count, 'records');
#### bulkCreate(records)
Creates multiple records in a single transaction.
Parameters:
- records (Array
Returns:
- Promise
Example:
`javascript`
const tasks = await summit1.entities.tasks.bulkCreate([
{ title: 'Task 1', status: 'pending' },
{ title: 'Task 2', status: 'in-progress' },
{ title: 'Task 3', status: 'pending' }
]);
#### query(sql, params)
Executes a raw SQL query (use with caution).
Parameters:
- sql (string): SQL queryparams
- (Array): Query parameters
Returns:
- Promise
Example:
`javascript
const results = await summit1.entities.tasks.query(
SELECT status, COUNT(*) as count
FROM tasks
GROUP BY status);`
#### count(filters)
Counts records matching criteria.
Parameters:
- filters (Object): Filter criteria
Returns:
- Promise
Example:
`javascript`
const total = await summit1.entities.tasks.count();
const pending = await summit1.entities.tasks.count({ status: 'pending' });
Summit1 supports various filter operators for advanced querying:
`javascript
// Equality
await summit1.entities.users.filter({ status: 'active' });
// Not equal
await summit1.entities.users.filter({ status: { $ne: 'inactive' } });
// Greater than / Less than
await summit1.entities.products.filter({ price: { $gt: 100 } });
await summit1.entities.products.filter({ price: { $lt: 500 } });
// Greater than or equal / Less than or equal
await summit1.entities.products.filter({ rating: { $gte: 4.0 } });
await summit1.entities.products.filter({ quantity: { $lte: 10 } });
// IN operator
await summit1.entities.users.filter({ id: [1, 2, 3, 4, 5] });
// LIKE operator
await summit1.entities.articles.filter({ title: { $like: '%tutorial%' } });
// Multiple conditions
await summit1.entities.tasks.filter({
status: 'pending',
priority: 'high',
due_date: { $lt: '2024-12-31' }
});
`
Summit1 automatically transforms PostgreSQL data types to JavaScript-friendly formats:
- Dates: PostgreSQL DATE, TIMESTAMP, TIMESTAMPTZ → ISO stringBOOLEAN
- Boolean: PostgreSQL → JavaScript booleanJSON
- JSON/JSONB: PostgreSQL , JSONB → JavaScript objectBYTEA
- Arrays: PostgreSQL arrays → JavaScript arrays
- Binary: PostgreSQL → Base64 encoded stringNULL
- NULL: PostgreSQL → JavaScript null
`javascript
// PostgreSQL stores: TIMESTAMP, JSONB, BYTEA, ARRAY
const record = await summit1.entities.sample.create({
created_at: new Date(), // → ISO string
config: { theme: 'dark' }, // → JSON object
file_data: Buffer.from('data'), // → Base64 string
tags: ['tag1', 'tag2'] // → JavaScript array
});
console.log(typeof record.created_at); // 'string'
console.log(typeof record.config); // 'object'
console.log(typeof record.file_data); // 'string'
console.log(Array.isArray(record.tags)); // true
`
Summit1 uses a connection pool by default with these settings:
- Max connections: 20
- Idle timeout: 30 seconds
- Connection timeout: 2 seconds
Always close connections when done:
`javascript`
try {
// Use the client
const users = await summit1.entities.users.list();
} finally {
await summit1.close();
}
For advanced operations, access the underlying pool:
`javascript`
const pool = summit1.getPool();
console.log('Total connections:', pool.totalCount);
console.log('Idle connections:', pool.idleCount);
For Azure PostgreSQL, always use SSL:
`javascript`
const summit1 = createClient({
host: 'mydb.postgres.database.azure.com',
user: 'username',
password: 'password',
ssl: {
ca: fs.readFileSync('./certs/baltimore-cybertrust-root.pem'),
rejectUnauthorized: true // Set to true in production
}
});
Store sensitive configuration in environment variables:
`javascript`
const summit1 = createClient({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME
});
Summit1 uses parameterized queries to prevent SQL injection:
`javascript
// Safe - parameters are escaped
await summit1.entities.users.filter({ name: userInput });
// Avoid raw queries with user input
// Instead, use the built-in methods
`
Summit1 provides descriptive error messages:
`javascript`
try {
const user = await summit1.entities.users.create(data);
} catch (error) {
console.error('Failed to create user:', error.message);
if (error.message.includes('duplicate key')) {
console.error('User already exists');
} else if (error.message.includes('foreign key')) {
console.error('Invalid reference');
}
}
1. Use connection pooling: Already enabled by default
2. Select specific fields: Reduce data transfer with select optionlimit
3. Use pagination: Always use and offset for large datasetsbulkCreate
4. Bulk operations: Use instead of multiple create calls
5. Filter efficiently: Add indexes on frequently filtered columns
See the /examples directory for comprehensive examples:
- 01-initialization.js: Client initialization patterns02-crud-operations.js
- : Complete CRUD examples03-data-transformation.js`: Data type handling examples
-
MIT
For issues and questions, please refer to the documentation or contact the admin@echos.health.