Declarative SQLite (Core)

The foundation of the Declarative SQLite ecosystem. This package provides all the core functionality for declarative schema definition, data manipulation, and streaming queries for Dart applications.

For Flutter-specific features, see declarative_sqlite_flutter.

Features

• Declarative Schema: Define your database schema using a fluent, easy-to-read builder API. Your schema is your single source of truth.
• Automatic Migrations: The library automatically detects schema changes and generates and applies the necessary migration scripts. No more manual ALTER TABLE statements.
• Type-Safe Queries: Build complex SQL queries with type safety and autocompletion using a powerful query builder.
• Streaming Queries: Create reactive queries that automatically emit new results when underlying data changes, perfect for building responsive UIs.
• LWW Columns: Built-in support for Last-Writer-Wins (LWW) columns using Hybrid Logical Clock (HLC) timestamps for conflict resolution.
• File Management: Integrated support for attaching and managing files linked to database records, with garbage collection for orphaned files.

Getting Started

Add the package to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  # Core library
  declarative_sqlite: ^1.0.2
  # Flutter integration package
  declarative_sqlite_flutter: ^1.0.2
  # Standard SQLite plugin for Flutter (Android/iOS)
  sqflite: ^2.3.3

Example Usage (Flutter)

import 'package:flutter/material.dart';
import 'package:declarative_sqlite_flutter/declarative_sqlite_flutter.dart';

// 1. Define your database schema
void buildSchema(SchemaBuilder builder) {
  builder.table('users', (table) {
    table.guid('id');
    table.text('name');
    table.integer('age');
    table.key(['id']).primary();
  });
}

void main() {
  runApp(
    // 2. Wrap your app with DatabaseProvider
    DatabaseProvider(
      databaseName: 'my_app.db',
      schema: buildSchema,
      child: const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: const HomeScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    // 3. Access the database from any descendant widget
    final database = DatabaseProvider.of(context);
    
    return Scaffold(
      appBar: AppBar(title: const Text('Declarative SQLite Demo')),
      body: Column(
        children: [
          ElevatedButton(
            onPressed: () async {
              // 4. Insert data
              await database.insert('users', {
                'id': 'a1b2c3d4',
                'name': 'Alice',
                'age': 30,
              });
            },
            child: const Text('Add User'),
          ),
          // 5. Use QueryListView for reactive data display
          Expanded(
            child: QueryListView<DbRecord>(
              query: (q) => q.from('users').where('age').isGreaterThan(25),
              mapper: (row, db) => DbRecord(row, 'users', db),
              itemBuilder: (context, user) {
                return ListTile(
                  title: Text(user.getValue('name')!),
                  subtitle: Text('Age: ${user.getValue('age')}'),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

For more detailed examples and API documentation, please refer to our official documentation.