SwiftLMDB
SwiftLMDB is an opinionated wrapper around the LMDB key/value database.
The wrapper abstracts away the C API and some of its concepts. Instead you get a clean Swift API that makes it easy to store arbitrary values in a fast and embedded database.
The only requirement is that keys and values can be converted to Data
. To assert this, keys and values must conform to the DataConvertible
protocol.
Fundamental Swift value types are supported out of the box.
Features
- [x] Small and lightweight
- [x] Fast
- [x] Unit tested
- [x] Xcode documentation
- [x] Cross platform
SwiftLMDB has been tested on iOS and macOS, however it should also run on Linux. Feel free to test it out.
Requirements
- iOS 8.0+ or macOS 10.10+
- Swift 5.0+
Installation
Swift Package Manager
Add SwiftLMDB as a dependency in your Package.swift
file.
dependencies: [
.package(url: "https://github.com/agisboye/SwiftLMDB.git", from: "2.0.0")
]
Carthage
To integrate LMDB into your Xcode project using Carthage, specify it in your Cartfile
:
github "agisboye/SwiftLMDB"
Run carthage update
to build the framework and drag SwiftLMDB.framework
into your Xcode project.
Usage
Start by importing the module.
import SwiftLMDB
Creating a database
Databases are contained within an environment. An environment may contain multiple databases, each identified by their name.
let environment: Environment
let database: Database
do {
// The folder in which the environment is opened must already exist.
try FileManager.default.createDirectory(at: envURL, withIntermediateDirectories: true, attributes: nil)
environment = try Environment(path: envURL.path, flags: [], maxDBs: 32)
database = try environment.openDatabase(named: "db1", flags: [.create])
} catch {
print(error)
}
Put a value
Any value conforming to DataConvertible
can be inserted with any key conforming to DataConvertible
.
try database.put(value: "Hello world!", forKey: "key1")
Get a value
When you need to get back a value from the database, you specify the expected type (the type of the value you put in) and the key. This returns an optional of the type that you specify.
if let value = try database.get(type: String.self, forKey: "key1") { // String?
// String
}
Delete a value
try database.deleteValue(forKey: "key1")
Check if a key exists
try database.exists(key: "key1") // Bool
Empty
Removes all entries from the database.
try database.empty()
database.count == 0 // true
Drop
Removes all entries from the database and deletes the database from the environment. The database can no longer be used after calling this method and should be discarded.
try database.drop()
Contributing
Contributions are very welcome. Open an issue or submit a pull request.
License
SwiftLMDB is available under the MIT license. See the LICENSE file for more info. LMDB is licensen under the OpenLDAP Public License.
Github
link |
Stars: 33 |
Help us keep the lights on
Dependencies
Releases
2.0.0 - Aug 29, 2019
This release brings the library up to date with the latest LMDB release (0.9.24). It also bumps the Swift version to 5 and updates the Package.swift
manifest so that the library can be installed using Swift Package Manager.
The API has been cleaned up a little bit (mostly naming).
1.1.1 - Jan 24, 2018
Breaking changes:
- The URL conformance to
DataConvertible
has been removed because the required initializer is only available on macOS 10.11+. There is no convenient way of changing the deployment target in the package manifest. If you rely on URL conforming toDataConvertible
, and your deployment target is macOS 10.11+, you can implement the conformance yourself in an extension. See the implementation here.
1.1.0 - Sep 9, 2017
- Changes the way various types are persisted to make them implementation agnostic as well as make the databases portable across systems of different endianess (#13). Thanks to @regexident.
Breaking changes: Certain types including numbers, Bool, Date are stored differently in this version, making it incompatible with databases created with previous versions of the library.