|
| 1 | +# Getting started using Valkey |
| 2 | + |
| 3 | +Add Valkey to your project, manage the connections, and send commands. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +### Adding Valkey as a dependency |
| 8 | + |
| 9 | +Add Valkey-Swift as a dependency to your project and targets that use it. |
| 10 | + |
| 11 | +You can use the `add-dependency` command: |
| 12 | + |
| 13 | +```bash |
| 14 | +swift package add-dependency \ |
| 15 | + https://github.com/valkey-io/valkey-swift --branch main |
| 16 | +``` |
| 17 | +<!-- switch above to `--from: 0.1.0` after tagging an initial release --> |
| 18 | + |
| 19 | +or edit Package.swift directly: |
| 20 | +```swift |
| 21 | +dependencies: [ |
| 22 | + .package(url: "https://github.com/valkey-io/valkey-swift", |
| 23 | + branch: "main"), |
| 24 | +] |
| 25 | +``` |
| 26 | +<!-- switch above to `from: "0.1.0"` after tagging an initial release --> |
| 27 | + |
| 28 | +And for the relevant target or targets. |
| 29 | +The following example shows how to add to Valkey as a dependency to the target `MyApp`: |
| 30 | + |
| 31 | +```bash |
| 32 | +swift package add-target-dependency \ |
| 33 | + Valkey MyApp --package valkey-swift |
| 34 | +``` |
| 35 | + |
| 36 | +You can also edit the dependencies for that target directly in Package.swift: |
| 37 | +```swift |
| 38 | +dependencies: [ |
| 39 | + .product(name: "Valkey", package: "valkey-swift"), |
| 40 | +] |
| 41 | +``` |
| 42 | + |
| 43 | +> Note: If you are building an executable for macOS, Valkey has a minimum platform dependency you need to accomodate. |
| 44 | +> For example, you may want to add a minimum platform requirement to your project: |
| 45 | +> |
| 46 | +> ```swift |
| 47 | +> platforms: [.macOS(.v15)], |
| 48 | +> ``` |
| 49 | +
|
| 50 | +Import Valkey in the swift files to use it: |
| 51 | +
|
| 52 | +```swift |
| 53 | +import Valkey |
| 54 | +``` |
| 55 | +
|
| 56 | +### Enabling connections to a Valkey server |
| 57 | + |
| 58 | +``ValkeyClient`` and ``ValkeyClusterClient`` use a connection pool that requires a background root task to run all the maintenance work required to establish connections and maintain the cluster state. |
| 59 | +You can either run them using a Task group, for example: |
| 60 | + |
| 61 | +```swift |
| 62 | +let valkeyClient = ValkeyClient(.hostname("localhost", port: 6379), logger: logger) |
| 63 | +try await withThrowingTaskgroup(of: Void.self) { group in |
| 64 | + group.addTask { |
| 65 | + // run connection pool in the background |
| 66 | + try await valkeyClient.run() |
| 67 | + } |
| 68 | + // use valkey client |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Or you can use [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) to manage the connection manager. |
| 73 | + |
| 74 | +```swift |
| 75 | +let valkeyClient = ValkeyClient(.hostname("localhost", port: 6379), logger: logger) |
| 76 | + |
| 77 | +let services: [Service] = [valkeyClient, webserver, other-service] |
| 78 | +let serviceGroup = ServiceGroup( |
| 79 | + services: services, |
| 80 | + gracefulShutdownSignals: [.sigint], |
| 81 | + cancellationSignals: [.sigterm], |
| 82 | + logger: logger |
| 83 | +) |
| 84 | +try await serviceGroup.run() |
| 85 | +``` |
| 86 | + |
| 87 | +### Sending commands |
| 88 | + |
| 89 | +Once you have your connection pool up and running the client is ready to use, you can call commands on the client. |
| 90 | +Valkey-client uses a connection from the connection pool for each call: |
| 91 | + |
| 92 | +```swift |
| 93 | +try await valkeyClient.set(key: "foo", value: "bar") |
| 94 | +let value = try await valkeyClient.get(key: "foo") |
| 95 | +``` |
| 96 | + |
| 97 | +You can ask for a single connection and run multiple commands using it: |
| 98 | + |
| 99 | +```swift |
| 100 | +try await valkeyClient.withConnection { connection in |
| 101 | + try await connection.set(key: "foo", value: "bar") |
| 102 | + let value = try await connection.get(key: "foo") |
| 103 | +} |
| 104 | +``` |
0 commit comments