Rope

Rope provides a convenient, easy-to-use, type-safe access to PostgreSQL for server-side Swift 3.
It uses the thread-safe, highly performant libpq library.

How to Use

Rope is so simple, you just need to learn 3 methods:

• connect() to create a connection
• query() to run a query
• rows() to turn a query result into a two-dimensional array

// credential struct as helper
let creds = RopeCredentials(host: "localhost", port: 5432,  dbName: "mydb",
                            user: "foo", password: "bar")

// establish connection using the struct, returns nil on error
guard let db = try? Rope.connect(credentials: creds) else {
	print("Could not connect to Postgres")
	return
}

// run INSERT query, it returns nil on a syntax or connection error
// the insert is SQL-injection safe due to the use of dollar params!
let text = "Hello World"
guard let _ = try? db.query("INSERT INTO my_table (my_text) VALUES($1)')", params: [text]) else {
	print("Could not insert \(text) into database");
	return
}

// run SELECT query, it returns nil on a syntax or connection error
guard let res = try? db.query("SELECT id, my_text FROM my_table") else {
	print("Could not fetch id & my_text from database")
	return
}

// execute statements with params (SQL-injection safe)  
guard let res = try? db.query("SELECT * FROM my_table WHERE my_text=$1", params: ["Hello World"]) else {
    print("Could not fetch id & my_text from database")
    return
}

// handle errors with a do/catch 
do {
    let res = try db.query("SELECT id, my_text FROM my_table")
} catch {
    // Error handling
}

// turn result into 2-dimensional array
if let rows = res?.rows() {
    for row in rows {
        let id = row["id"] as? Int
        let myText = row["my_text"] as? String
    }
}

Postgres Types to Swift Conversion

• serial, bigserial, smallint, integer, and bigint are returned as Int
• real and double precision are returned as Float
• char, varchar, and text are returned as String
• json is converted to a Dictionary of [String: Any?]
• the boolean type is returned as Bool
• date, timestamp are returned as Date

Running Unit Tests

Rope’s unit tests require a running Postgres 9.x database and you can either provide the database credentials via environment variables, or via CLI arguments or use the built-in default values.

Using Defaults

All tests run without any additional configuration if your database has the following setup:

• host: "localhost"
• port: 5432
• database name: "rope"
• user: "postgres"
• password: ""

Using Environment Variables

You can easily provide the database credentials via environment variables. Please see the RopeTestCredentials.swift file. Please also see the unit tests about how to use RopeCredentials to establish a connection.

For environment variables in Xcode, please enter the following info via Edit Scheme > Arguements using Environment Variables or Arguments Passend On Launch:

• DATABASE_HOST
• DATABASE_PORT
• DATABASE_NAME
• DATABASE_USER
• DATABASE_PASSWORD

Using CLI Arguments

swift build DATABASE_HOST=mydatabase_host DATABASE_PORT=mydatabase_port DATABASE_NAME=mydatabase_dbname DATABASE_USER=mydatabase_user DATABASE_PASSWORD=mydatabase_very_secure_password

To run tests simple type swift test in your CLI.

Source Code Linting

The source code is formatted using SwiftLint and all commits & PRs need to be without any SwiftLint warnings or errors.

Contributing

Rope is maintained by Thomas Catterall (@swizzlr), Johannes Erhardt (@johanneserhardt), Sebastian Kreutzberger (@skreutzberger).

Contributions are more than welcomed. You can either work on existing Github issues or discuss with us your ideas in a new Github issue. Thanks 🙌

License

Rope is released under the Apache 2.0 License.