dart_duckdb 1.2.2

DuckDB for macOS, iOS, Android, Linux, and Windows

DuckDB.dart

Welcome to DuckDB.dart, the native Dart interface to DuckDB, a high-performance analytical database system. With DuckDB.dart, you can harness the power of DuckDB in your Dart applications across multiple platforms, including Apple (macOS, iOS), Android, Linux, and Windows, delivering seamless integration and top-tier performance for your analytical workloads.

---

Table of Contents

• Introduction
• Why DuckDB.dart?
• Features
• Installation
• Getting Started
  • Basic Usage
  • Querying Data
• Advanced Examples
  • Querying a Parquet File
  • Using Window Functions
  • Working with CSV Files
• Platform Support
• API Documentation
• Contributing
• License
• FAQ

---

Introduction

DuckDB.dart is the Dart interface to DuckDB, an in-process SQL OLAP database management system designed for high-performance analytical queries. Whether you're building mobile apps with Flutter, desktop software, or server-side solutions, DuckDB.dart enables fast, efficient, and versatile data analysis without requiring external database servers.

For an in-depth introduction, watch the DuckCon #5 talk from Seattle 2024: "Quack attack: Bringing DuckDB to the Dart side."

---

Why DuckDB.dart?

DuckDB.dart is an excellent choice for Dart developers needing a powerful embedded database. Here's why:

• Performance: Powered by DuckDB's vectorized query engine for lightning-fast analytical queries.
• Portability: Runs effortlessly across multiple platforms with no additional setup.
• Ease of Use: Provides a simple, Dart-native API that's intuitive for developers.
• Self-Contained: Includes DuckDB binaries, eliminating external dependencies.
• Advanced SQL: Supports a rich SQL dialect, including window functions and complex queries.

Choose DuckDB.dart for a lightweight, high-performance database solution tailored to Dart.

Features

• Native Dart API: Integrates seamlessly with Dart for a natural developer experience.
• Cross-Platform Support: Works on Apple (macOS, iOS), Android, Linux, and Windows.
• Batteries Included: Ships with DuckDB binaries—no external installations needed.
• High-Performance Queries: Leverages DuckDB's vectorized engine for optimal speed.
• Nonblocking I/O: Uses dedicated background isolates per connection for efficient, zero-copy query results.
• Direct File Access: Query CSV, JSON, Parquet, and other formats without importing data.
• Comprehensive SQL Dialect: Supports advanced SQL features like window functions and collations.

---

Installation

DuckDB.dart is available on pub.dev. Add it to your project as follows:

For Flutter Projects

Run this command:

$ flutter pub add dart_duckdb

This updates your pubspec.yaml:

dependencies:
  dart_duckdb: ^1.2.0

For Dart Projects

Run this command:

$ dart pub add dart_duckdb

This updates your pubspec.yaml:

dependencies:
  dart_duckdb: ^1.2.0

Download the latest duckdb release from duckdb.org.

In your dart code, tell the framework where the duckdb binary.

  open.overrideFor(
      OperatingSystem.macOS, 'path/to/libduckdb.dylib');

Import it

Now you can use the package:

import 'package:dart_duckdb/dart_duckdb.dart';

---

Getting Started

Basic Usage

Here's a simple example to start using DuckDB.dart:

import 'package:dart_duckdb/dart_duckdb.dart';

void main() {
  final db = duckdb.open(":memory:");
  final conn = db.connect();

  conn.execute("CREATE TABLE users (id INTEGER, name VARCHAR)");
  conn.execute("INSERT INTO users VALUES (1, 'Alice')");

  final result = conn.query("SELECT * FROM users");
  for (final row in result.fetchAll()) {
    print(row);
  }

  conn.close();
  db.close();
}

This demonstrates opening a database, creating a table, inserting data, querying it, and closing resources.

Querying Data

Execute SQL queries and process results easily:

final result = conn.query("SELECT id, name FROM users WHERE id > 0");
for (final row in result.fetchAll()) {
  print('ID: ${row['id']}, Name: ${row['name']}');
}

--

Advanced Examples

Querying a Parquet File

Query Parquet files directly without loading them into the database:

final result = conn.query("SELECT * FROM 'data/large_dataset.parquet' LIMIT 10");
for (final row in result.fetchAll()) {
    print(row);
}

Using Window Functions

Perform advanced analytics with window functions:

conn.execute("CREATE TABLE sales (id INTEGER, amount DECIMAL, date DATE)");
conn.execute("INSERT INTO sales VALUES (1, 100.0, '2023-01-01'), (2, 150.0, '2023-01-02'), (3, 200.0, '2023-01-03')");

final result = conn.query("""
  SELECT id, amount, date,
         SUM(amount) OVER (ORDER BY date) AS running_total
  FROM sales
""");
for (final row in result.fetchAll()) {
  print('ID: ${row['id']}, Amount: ${row['amount']}, Date: ${row['date']}, Running Total: ${row['running_total']}');
}

Working with CSV Files

Query CSV files directly:

final result = conn.query("SELECT * FROM 'data/sales_data.csv' WHERE quantity > 10");
for (final row in result.fetchAll()) {
  print(row);
}

Explore more examples in the examples directory.

---

Platform Support

DuckDB.dart supports the following platforms:

• 🍎 Apple (macOS, iOS)
• 🤖 Android
• 🐧 Linux
• 🪟 Windows

Note: Web support is currently not available but is planned for future releases.

See platform-specific details in the Building Instructions

---

API Documentation

For detailed API information, visit the API Documentation.

---

If you have any questions, feedback or ideas, feel free to create an issue. If you enjoy this project, I'd appreciate your 🌟 on GitHub.

---

FAQ

Q: Does DuckDB.dart support Flutter web?
A: Not yet, but web support is planned.

Q: Can it handle large datasets?
A: Yes, DuckDB excels at processing large datasets efficiently, including direct file queries.

Q: Is it production-ready?
A: Yes, built on the stable DuckDB engine, it's suitable for production use.

Q: How do I report a bug?
A: Open an issue on the GitHub issue tracker.

---

Sponsors

DuckDB.dart is proudly Sponsored by TigerEye 🐅

---

Contributing

We'd love your contributions! Here's how to get started:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with descriptive messages.
4. Push your changes to your fork.
5. Submit a pull request with a detailed description of your changes.