DuckDB.Dart

DuckDB.Dart is the native Dart API for DuckDB, enabling developers to harness the power of DuckDB in Dart-based applications across Apple, iOS, Android, Linux, and Windows platforms.

DuckDB Overview

DuckDB is a high-performance analytical database system known for its speed, reliability, and ease of use. It supports a comprehensive SQL dialect, offering features such as:

Arbitrary and nested correlated subqueries
Window functions
Collations
Complex types (arrays, structs)

For more information on DuckDB's goals and capabilities, visit the Why DuckDB page.

Usage Examples

Here are some common use cases for DuckDB.Dart:

Querying a Database

import 'package:dart_duckdb/dart_duckdb.dart';

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

  connection.execute('''
    CREATE TABLE users (id INTEGER, name VARCHAR, age INTEGER);
    INSERT INTO users VALUES (1, 'Alice', 30), (2, 'Bob', 25);
  ''');

  final result = connection.query("SELECT * FROM users WHERE age > 28").fetchAll();

  for (final row in result) {
    print(row);
  }

  connection.close();
  db.close();
}

Queries on background Isolates

import 'package:dart_duckdb/dart_duckdb.dart';

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

  await Isolate.spawn(backgroundTask, db.transferrable);

  connection.close();
  db.close();
}

void backgroundTask(TransferableDatabase transferableDb) {
  final connection = duckdb.connectWithTransferred(transferableDb);
  // Access database ...
  // fetch is needed to send the data back to the main isolate
}

Contributing

We welcome contributions to DuckDB.Dart! If you have suggestions for improvements or bug fixes, please follow these steps:

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

Support and Contact

If you encounter any issues or have questions, please check our issue tracker

Building DuckDB.Dart from Source

Install Dependencies

Install fvm, Getting Started

Install any platform dependencies for DuckDB. Here are the DuckDB Building Instructions. Also, the github workflows are the best examples to learn from.

Build DuckDB

Run make from this project to build/patch duckdb.

MacOS Universal

To build for MacOS:

make macos

iOS (Requires iOS SDK)

To build for an iOS device:

make ios_device

To build for an iOS simulator:

make ios_simulator

Android (Requires Android NDK)

To build for Android:

make android

Windows (Requires MINGW64)

cd windows && ./getduck.ps1

Linux

To build for Linux:

make linux

Build DuckDB.Dart

make build

Maintaining DuckDB.Dart

Upgrading DuckDB Versions e.g. 0.9.1 to 0.9.2

To upgrade DuckDB to a newer version, follow these steps:

Clone the DuckDB repository:

git clone https://github.com/duckdb/duckdb && cd duckdb

Fetch the latest tags:
```
git fetch --tags
```
Checkout the old tag (e.g., v0.9.1):
```
git checkout tags/v0.9.1
```

Apply your previous changes:

git apply ../changes.patch
git add . && git commit -m 'Apply previous changes'

Rebase to the new tag (e.g., v0.9.2):
```
git rebase tags/v0.9.2
```

Create an updated patch file:

git diff tags/v0.9.2 > ../changes.patch