Discord Support Server
GrokDB is a high-performance, secure, and feature-rich SQLite database wrapper for Node.js applications. Built with TypeScript and powered by better-sqlite3, it provides a modern and type-safe interface for database operations.
- Node.js >= 16.0.0
- SQLite3
- Operating Systems:
- Linux (x64, arm64)
- macOS (x64, arm64)
- Windows (x64)
- 🚀 High-performance SQLite operations
- 🔒 Built-in encryption support
- 📝 Schema validation with Zod
- 🔄 Transaction support
- 🏗️ Advanced table relationships
- 🔍 Indexing support
- 🛡️ Type safety with TypeScript
- 💾 Automatic backups
- 🔐 Foreign key constraints
- 📊 Query builder with pagination
- 🔄 JSON field support
- 📦 Migration system
- 🎯 Event system
- 🗑️ Soft delete support
- 🖥️ Interactive CLI
npm install grokdbimport { GrokDB } from 'grokdb';
import { z } from 'zod';
// Create a database instance
const db = new GrokDB('myapp.db', {
encryptionKey: 'your-secret-key', // Optional
timeout: 5000, // Optional
readonly: false, // Optional
});
// Define a schema with relationships
db.createTable('users', {
id: {
type: 'INTEGER',
primary: true
},
email: {
type: 'TEXT',
unique: true,
notNull: true,
index: true
},
password: {
type: 'TEXT',
notNull: true,
encrypted: true // Automatically encrypted/decrypted
},
created_at: {
type: 'DATETIME',
default: 'CURRENT_TIMESTAMP'
}
});
db.createTable('posts', {
id: {
type: 'INTEGER',
primary: true
},
user_id: {
type: 'INTEGER',
notNull: true,
foreignKey: {
table: 'users',
column: 'id',
onDelete: 'CASCADE'
}
},
title: {
type: 'TEXT',
notNull: true
},
content: {
type: 'TEXT'
}
});
// Add schema validation
const userSchema = z.object({
email: z.string().email(),
password: z.string().min(8),
});
db.setValidator('users', userSchema);
// Basic CRUD Operations
// Create
const userId = db.insert('users', {
email: 'user@example.com',
password: 'securepass123'
});
// Read with pagination
const users = db.find('users',
{ /* where conditions */ },
{
limit: 10,
offset: 0,
orderBy: {
column: 'created_at',
direction: 'DESC'
}
}
);
// Update
db.update('users',
{ password: 'newpassword123' },
{ email: 'user@example.com' }
);
// Delete
db.delete('users', { email: 'user@example.com' });
// Using Transactions
const transaction = db.transaction();
try {
db.insert('users', { /* user data */ });
db.insert('posts', { /* post data */ });
transaction.commit();
} catch (error) {
transaction.rollback();
console.error('Transaction failed:', error);
}
// Backup database
db.backup('backup.db');
// Close connection
db.close();GrokDB supports automatic JSON serialization and deserialization:
// Define a table with JSON field
db.createTable('settings', {
id: { type: 'INTEGER', primary: true },
config: { type: 'TEXT', json: true } // Automatic JSON handling
});
// Insert JSON data
db.insert('settings', {
config: {
theme: 'dark',
notifications: true,
preferences: {
language: 'en',
timezone: 'UTC'
}
}
});
// Read JSON data (automatically parsed)
const settings = db.findOne('settings', { id: 1 });
console.log(settings.config.theme); // 'dark'
console.log(settings.config.preferences.language); // 'en'Manage database schema changes with migrations:
// Create a new migration
await db.createMigration('add_user_settings');
// Migration file example (migrations/20240224_add_user_settings.ts)
export default {
up: (db: GrokDB) => {
db.alterTable('users', {
settings: { type: 'TEXT', json: true }
});
},
down: (db: GrokDB) => {
db.dropColumn('users', 'settings');
}
};
// Run migrations
await db.migrate(); // Apply pending migrations
await db.migrate('down'); // Rollback migrationsListen for database events:
// Listen for insert events
db.on('users:insert', (data) => {
console.log(`New user created: ${data.id}`);
// Trigger notifications, update cache, etc.
});
// Listen for updates
db.on('users:update', ({ where, data }) => {
console.log(`User updated:`, data);
});
// Transaction events
db.on('transaction:commit', () => {
console.log('Transaction completed successfully');
});
db.on('transaction:rollback', () => {
console.log('Transaction rolled back');
});Implement soft delete functionality:
// Define table with soft delete
db.createTable('posts', {
id: { type: 'INTEGER', primary: true },
title: { type: 'TEXT' },
content: { type: 'TEXT' },
deleted_at: { type: 'DATETIME', softDelete: true } // Enable soft delete
});
// Soft delete a record
db.delete('posts', { id: 1 }); // Sets deleted_at timestamp
// Query excluding deleted records (default)
const activePosts = db.find('posts');
// Query including deleted records
const allPosts = db.find('posts', {}, { includeDeleted: true });Manage your database from the command line:
# Create a new migration
npx grokdb create-migration add_new_feature
# Run migrations
npx grokdb migrate
npx grokdb migrate --down # Rollback
# Start interactive CLI
npx grokdb cliInteractive CLI features:
- Execute SQL queries
- View table schemas
- Manage data
- Run migrations
- Export/import data
- Connection Management
try {
// Database operations
} finally {
db.close(); // Always close the connection
}- Error Handling
try {
const transaction = db.transaction();
// Operations
transaction.commit();
} catch (error) {
transaction.rollback();
console.error('Error:', error);
}- Type Safety
interface User {
id: number;
email: string;
password: string;
}
const users = db.find('users') as User[];- Validation
// Always set validators for tables with user input
db.setValidator('users', userSchema);- Indexing
// Add indexes for frequently queried columns
{
email: { type: 'TEXT', index: true }
}- Use transactions for multiple operations
- Create indexes for frequently queried columns
- Use appropriate column types
- Keep encrypted fields to a minimum
- Use prepared statements (automatic with FluxDB)
- Enable WAL mode for better concurrency (enabled by default)
- Use JSON fields judiciously
- Implement proper indexing strategies
- Monitor and optimize queries
- Regular database maintenance
- Automatic field encryption
- Input validation
- Prepared statements
- Type safety
- Foreign key constraints
- Schema validation
- Secure defaults
- Audit trails through events
- Access control patterns
- Data integrity checks
MIT
Contributions are welcome! Please feel free to submit a Pull Request.