# hive_ce 2.15.0
Hive Community Edition - A spiritual continuation of Hive v2
## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'hive_ce:2.15.0'
```
Published: 2025-10-14T13:23:08.999719Z
Expected archive SHA-256: e3a9d2608350ca5ae1fcaa594bbc24c443cf8e67cd16b89ec258fb0bcccb0847
Available in cache; verification: upstream_checksum
## Direct dependencies
- crypto: ^3.0.0
- isolate_channel: ^0.2.1
- json_annotation: ^4.9.0
- meta: ^1.14.0
- web: >=0.5.0 <2.0.0
## Package README (untrusted upstream documentation)
Fast, Enjoyable & Secure NoSQL Database
Hive is a lightweight and blazing fast key-value database written in pure Dart. Inspired by [Bitcask](https://en.wikipedia.org/wiki/Bitcask).
## Tutorial
For a quick tutorial, see [this wonderful post](https://onlyflutter.com/how-to-add-a-local-database-using-hive-in-flutter) by [Tijn van den Eijnde](https://x.com/TijnvdEijnde)
## Features
- 🚀 Cross platform: mobile, desktop, browser
- ⚡ Great performance (see [benchmark](#benchmark))
- ❤️ Simple, powerful, & intuitive API
- 🔒 Strong encryption built in
- 🎈 **NO** native dependencies
- 🔋 Batteries included
## New features in Hive CE
Hive CE is a spiritual continuation of Hive v2 with the following new features:
- Hive CE Inspector DevTools extension
- Quickly and easily inspect the content of Hive boxes
- Isolate support through `IsolatedHive`
- Flutter web WASM support
- Automatic type adapter generation using the `GenerateAdapters` annotation
- No more manually adding annotations to every type and field
- Generate adapters for classes outside the current package
- A `HiveRegistrar` extension that lets you register all your generated adapters in one call
- Extends the maximum type ID from `223` to `65439`
- Support for constructor parameter defaults
- Support for Sets
- A built in Duration adapter
- Freezed support
- Support for generating adapters with classes that use named imports
## Benchmark
This is a comparison of the time to complete a given number of write operations and the resulting database file size:
| Operations | Hive CE Time | IsolatedHive Time | Hive CE Size | Hive v4 Time | Hive v4 Size |
| ---------- | ------------ | ----------------- | ------------ | ------------ | ------------ |
| 10 | 0.00 s | 0.00 s | 0.00 MB | 0.00 s | 1.00 MB |
| 100 | 0.00 s | 0.01 s | 0.01 MB | 0.01 s | 1.00 MB |
| 1000 | 0.02 s | 0.03 s | 0.11 MB | 0.06 s | 1.00 MB |
| 10000 | 0.13 s | 0.25 s | 1.10 MB | 0.64 s | 5.00 MB |
| 100000 | 1.40 s | 2.64 s | 10.97 MB | 7.26 s | 30.00 MB |
| 1000000 | 19.94 s | 41.50 s | 109.67 MB | 84.87 s | 290.00 MB |
Database size in Hive v4 is directly affected by the length of field names in model classes which is not ideal. Also Hive v4 is much slower than Hive CE for large numbers of operations.
IsolatedHive is slower than Hive, but it is much faster than Hive v4 and you still get the benefit of multiple isolate support.
The benchmark was performed on an M3 Max MacBook Pro. You can [see the benchmark code here](../benchmarks/storage/bin/bench.dart).
## Migration guides
- [Hive v2 to Hive CE](https://github.com/IO-Design-Team/hive_ce/blob/main/hive/MIGRATION.md#v2-to-ce)
- [Transitive Hive dependencies](https://github.com/IO-Design-Team/hive_ce/blob/main/hive/MIGRATION.md#transitive-hive-dependencies)
- [Migrating to `GenerateAdapters`](https://github.com/IO-Design-Team/hive_ce/blob/main/hive/MIGRATION.md#generate-adapters)
- [Add fields to objects](https://github.com/IO-Design-Team/hive_ce/blob/main/hive/MIGRATION.md#add-fields)
## Getting Started
Hive CE requires Dart 3. Ensure that you have the following in your `pubspec.yaml` file:
```yaml
environment:
sdk: ^3.0.0
```
## Usage
You can use Hive just like a map. It is not necessary to await `Futures`.
```dart
import 'package:hive_ce/hive.dart';
void example() {
final box = Hive.box('myBox');
box.put('name', 'David');
final name = box.get('name');
print('Name: $name');
}
```
## Guides
Hive CE Inspector
When your app is running in debug mode, you can use the Hive CE Inspector to inspect boxes:
1. Press `Ctrl+Shift+P`
2. Select `Dart: Open DevTools`
3. Select `Open DevTools in Web Browser`
4. Navigate to the `hive_ce` tab
There are some requirements for using the inspector:
- All types you wish to view in the inspector must have type adapters generated by a `GenerateAdapters` annotation
- For any types not handled by `GenerateAdapters`, only raw binary data will be shown
- This means types annotated with `HiveType` and types using custom type adapters will not be deserialized
- Hive schemas (`hive_adapters.g.yaml`) are used to deserialize data
- All necessary Hive schemas must be in the `lib` folder of a project open in the IDE workspace
- This should work by default for most projects. Otherwise, you may need to copy the necessary Hive schemas into an open project's `lib` folder.
IsolatedHive (isolate support)
`IsolatedHive` allows you to safely use `Hive` in a multi-isolate environment by maintaining its own separate isolate for `Hive` operations
Here are some common examples of multi-isolate scenarios:
- A Flutter desktop app with multiple windows
- Running background tasks with [flutter_workmanager](https://pub.dev/packages/workmanager), [background_fetch](https://pub.dev/packages/background_fetch), etc
- Push notification processing
`IsolatedHive` has a very similar API to `Hive`, but there are some key differences:
- The `init` call takes an `isolateNameServer` parameter
- Most methods are asynchronous due to isolate communication
- `IsolatedHive` does not support `HiveObject` or `HiveList`
- Isolate communication does add some overhead. See the benchmarks above.
NOTE: On web, `IsolatedHive` directly calls `Hive` since web does not support isolates
### Usage
```dart
import 'package:hive_ce/hive.dart';
import 'stub_ins.dart';
void main() async {
await IsolatedHive.init('.', isolateNameServer: StubIns());
final box = await IsolatedHive.openBox('box');
await box.put('key', 'value');
print(await box.get('key')); // reading is async
}
```
IMPORTANT: If you are using `IsolatedHive`, you MUST use it everywhere in place of the normal `Hive` interface
NOTE: It is possible to use `IsolatedHive` without an `IsolateNameServer`, BUT THIS IS UNSAFE. The `IsolateNameServer` is what allows `IsolatedHive` to locate and communicate with a single backend isolate.
Additional notes:
- With Flutter, use `IsolatedHive.initFlutter` from `hive_ce_flutter` to initialize `IsolatedHive` with Flutter's `IsolateNameServer`
- There is also an `IsolatedHive.registerAdapters` method if you use `hive_ce_generator` to generate adapters
### Example
See an example of a multi-window Flutter app using `IsolatedHive` [here](https://github.com/Rexios80/hive_ce_multiwindow)
Store objects
Hive not only supports primitives, lists, and maps but also any Dart object you like. You need to generate type adapters before you can store custom objects.
### Create model classes
```dart
import 'package:hive_ce/hive.dart';
class Person extends HiveObject {
Person({required this.name, required this.age});
String name;
int age;
}
```
### Create a `GenerateAdapters` annotation
Usually this is placed in `lib/hive/hive_adapters.dart`
```dart
import 'package:hive_ce/hive.dart';
import 'person.dart';
@GenerateAdapters([AdapterSpec()])
part 'hive_adapters.g.dart';
```
### Update `pubspec.yaml`
```yaml
dev_dependencies:
build_runner: latest
hive_ce_generator: latest
```
### Run `build_runner`
```bash
dart pub run build_runner build --delete-conflicting-outputs
```
This will generate the following:
- TypeAdapters for the specified AdapterSpecs
- TypeAdapters for all explicitly defined HiveTypes
- A `hive_adapters.g.dart` file containing all adapters generated from the `GenerateAdapters` annotation
- A `hive_adapters.g.yaml` file
- A `hive_registrar.g.dart` file containing an extension method to register all generated adapters
All of the generated files should be checked into version control. These files are explained in more detail below.
### Use the Hive registrar
The Hive Registrar allows you to register all generated TypeAdapters in one call
```dart
import 'dart:io';
import 'package:hive_ce/hive.dart';
import 'package:your_package/hive/hive_registrar.g.dart';
void main() {
Hive
..init(Directory.current.path)
..registerAdapters();
}
```
### Using HiveObject methods
Extending `HiveObject` is optional but it provides handy methods like `save()` and `delete()`.
```dart
import 'package:hive_ce/hive.dart';
import 'person.dart';
void example() async {
final box = await Hive.openBox('myBox');
final person = Person(name: 'Dave', age: 22);
await box.add(person);
print(box.getAt(0)); // Dave - 22
person.age = 30;
await person.save();
print(box.getAt(0)); // Dave - 30
}
```
### About `hive_adapters.g.yaml`
The Hive schema is a generated yaml file that contains the information necessary to incrementally update the generated TypeAdapters as your model classes evolve.
**IMPORTANT**: There will be a lot of churn in this file during initial development. Make sure to delete `hive_adapters.g.yaml` and regenerate before the first real deployment of your application to reclaim unused field indices.
Some migrations may require manual modifications to the Hive schema file. One example is class/field renaming. Without manual intervention, the generator will see both an added and removed class/field. To resolve this, manually rename the class/field in the schema.
### Explicitly defining HiveTypes
The old method of defining HiveTypes is still supported, but should be unnecessary now that Hive CE supports constructor parameter defaults. If you have a use-case that `GenerateAdapters` does not support, please [create an issue on GitHub](https://github.com/IO-Design-Team/hive_ce/issues/new).
Unfortunately it is not possible for `GenerateAdapters` to handle private fields. You can use `@protected` instead if necessary.
BoxCollection
`BoxCollections` are a set of boxes which can be similarly used as normal boxes, except of that
they dramatically improve speed on web. They support opening and closing all boxes of a collection
at once and more efficiently store data in indexed DB on web.
Aside, they also expose Transactions which can be used to speed up tremendous numbers of database
transactions on web.
On `dart:io` platforms, there is no performance gain by BoxCollections or Transactions. Only
BoxCollections might be useful for some box hierarchy and development experience.
Custom objects must be json serializable in order to be used with BoxCollections.
```dart
import 'package:hive_ce/hive.dart';
import 'hive_cipher_impl.dart';
void example() async {
// Create a box collection
final collection = await BoxCollection.open(
// Name of your database
'MyFirstFluffyBox',
// Names of your boxes
{'cats', 'dogs'},
// Path where to store your boxes (Only used in Flutter / Dart IO)
path: './',
// Key to encrypt your boxes (Only used in Flutter / Dart IO)
key: HiveCipherImpl(),
);
// Open your boxes. Optional: Give it a type.
final catsBox = await collection.openBox
Hive ❤️ Flutter
Hive was written with Flutter in mind. It is a perfect fit if you need a lightweight datastore for your app. After adding the required dependencies and initializing Hive, you can use Hive in your project:
```dart
import 'package:hive_ce/hive.dart';
import 'package:hive_ce_flutter/hive_flutter.dart';
class SettingsPage extends StatelessWidget {
@override
Widget build(BuildContext context) {
return ValueListenableBuilder(
valueListenable: Hive.box('settings').listenable(),
builder: (context, box, widget) {
return Switch(
value: box.get('darkMode'),
onChanged: (val) {
box.put('darkMode', val);
}
);
},
);
}
}
```
Boxes are cached and therefore fast enough to be used directly in the `build()` method of Flutter widgets.
## Changelog
## 2.15.0
- Adds `ignoredFields` parameter to `AdapterSpec` for excluding specific fields from type adapter generation (by [@rezam92](https://github.com/rezam92) in [#229](https://github.com/IO-Design-Team/hive_ce/pull/229))
## 2.14.0
- Adds the ability to override type adapters by type (by [@sportismygame](https://github.com/sportismygame) in [#217](https://github.com/IO-Design-Team/hive_ce/pull/217))
- Fixes some `Future` handling issues
## 2.13.3
- Adds copy to clipboard functionality to the inspector
## 2.13.2
- Removes the print statement from the inspector
## 2.13.1
- Fixes the first column header not showing in the inspector
## 2.13.0
- Adds the Hive CE Inspector DevTools extension
## 2.12.0
- Notify with the value of a deleted frame instead of `null`
- Improves adapter of same type warning
## 2.11.4
- Handles exception thrown during compaction on some platforms
- Updates documentation for `IsolatedHive`
## 2.11.3
- Prints warning when writing integers greater than 2^53
## 2.11.2
- Fixes web compatibility check
- Fixes `deleteFromDisk` not completing on web
## 2.11.1
- Allows boxes of primitive iterables
## 2.11.0
- Isolate support through `IsolatedHive`
- Warning messages for potentially unsafe isolate usage
- Updates suggested placement of `GenerateAdapters` annotation
- Fixes custom objects in `BoxCollection`. Custom objects must now be json serializable.
- Adds much more information to the unknown typeId error message
- Supports `freezed` default values
- Enforces that boxes of type `Map` _must_ be `Map`
- Enforces that boxes of type `Iterable` _must_ be `Iterable`
- Adds `reservedTypeIds` to `GenerateAdapters` annotation
## 2.10.1
- Fixes `HiveObject` disposal in lazy boxes
## 2.10.0
- Raises the maximum type ID from 223 to 65439
## 2.9.0
- Prints a warning when writing `int` or `List` types in a WASM environment
- Only emits print statements when assertions are enabled (aka debug mode)
## 2.8.0+3
- Updates the commit hash for the transitive Hive dependencies workaround
## 2.8.0+2
- Adds workaround for transitive Hive dependencies to README
## 2.8.0+1
- Adds tutorial link to README
## 2.8.0
- Adds `GenerateAdapters` annotation and relevant documentation
## 2.7.0+1
- Adds a storage benchmark to compare Hive CE with Hive v4
## 2.7.0
- No longer reinitializes `Hive` when opening a `BoxCollection`
## 2.6.0
- Adds `TargetKind.parameter` to `HiveField` to support `freezed`
## 2.5.0+2
- Adds documentation for adding new fields (@vizakenjack)
- Updates README badges
## 2.5.0+1
- Documentation updates for `HiveField` in support of `hive_ce_generator` changes
## 2.5.0
- Adds `Target` annotations to `HiveField` and `HiveType` to prevent invalid usage
- Bumps `analyzer` to `^6.5.0` to deal with deprecations
- Bumps `meta` to `^1.14.0` for `TargetKind.enumValue`
## 2.4.4
- Loosens constraint on `web`
## 2.4.3
- Loosens constraint on `meta`
## 2.4.2
- Only shows the adapter with same type warning if the adapters have different type ids
## 2.4.1
- Upgrades `package:web` to `1.0.0`
## 2.4.0+1
- Adds a guide to migrate from `hive`
- Adds documentation for the new `HiveRegistrar` extension created by `hive_ce_generator`
## 2.4.0
- Adds support for Sets
- Adds a built in `DurationAdapter`
- Adds a warning if attempting to register multiple adapters for the same type
## 2.3.0
- The first release of Hive Community Edition
- Supports Flutter web WASM compilation
- Fixes analysis issues