Swift

The Swift SDK for SurrealDB lets you connect to a database and query it from your application. This guide covers connecting, authenticating, and running your first queries.

1. Install the SDK

Follow the installation guide to add the SDK to your project. Once installed, import the SDK.

import SurrealDB

2. Connect to SurrealDB

Create a client for your endpoint and connect. The SurrealHTTPClient is the simplest starting point for most applications.

Supported connection protocols include:

• •

  HTTP (http://, https://) using SurrealHTTPClient for short-lived stateless connections, the simplest way to get started

• •

  WebSocket (ws://, wss://) using the WebSocket client for long-lived stateful connections, required for live queries

let client = try SurrealHTTPClient(endpoint: "http://localhost:8000")
try await client.connect()
defer { Task { await client.close() } }

After connecting, use signin to authenticate and use to select the namespace and database you want to work with. Most operations require both.

let tokens = try await client.signin(.root(username: "root", password: "root"))
try await client.use(namespace: "myapp", database: "mydb")

3. Inserting data into SurrealDB

The Swift SDK is model-first. The @SurrealModel macro generates SurrealModel conformance, the surrealTable name, and a type-safe Fields namespace used to build predicates.

@SurrealModel("person")
struct Person: Codable, Sendable {
    let id: String?
    let name: String
    let age: Int
}

Once you have a model, use create to insert a record.

let created: [Person] = try await client.create(
    Person(id: nil, name: "Ada", age: 30)
)

4. Retrieving data from SurrealDB

Selecting records

Use select to retrieve all records of a table, or narrow the results with a type-safe predicate built from the model's Fields namespace.

// Select all records of a table
let people = try await client.select(Person.self)

// Select with a type-safe predicate
let adults = try await client.select(
    Person.self,
    where: Person.Fields.age >= 18,
    limit: 20,
    start: 0
)

Running SurrealQL queries

For more advanced use cases, use queryRaw to run SurrealQL statements directly. Use bound parameters to safely pass dynamic values.

let results: [RPCQueryResult] = try await client.queryRaw(
    "SELECT * FROM person WHERE age > $minAge LIMIT $limit;",
    bindings: [
        "minAge": .int(18),
        "limit": .int(50)
    ]
)

for row in results {
    if row.status == .ok {
        print(row.result)
    }
}

5. Closing the connection

Always close the connection when you are done to release resources. The idiomatic Swift pattern is to defer the close immediately after connecting, as shown in step 2.

await client.close()

Next steps

You have learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There is a lot more you can do with the SDK, including updating and deleting records, authentication, live queries, and transactions.