Close Menu

sqlitepersistentobject

SQLitePersistentObject – Documentation

Welcome to the documentation for SQLitePersistentObject! Here you will find detailed information on how to use this powerful library to work with SQLite databases in your iOS or macOS applications.

Table of Contents

  1. Installation
  2. Usage
  3. Model Structure
  4. Database Operations
  5. Querying
  6. Relationships
  7. Migrations
  8. Advanced Usage
  9. FAQ

Installation

To integrate SQLitePersistentObject into your project, you can use CocoaPods. Simply add the following line to your Podfile:

pod 'SQLitePersistentObject'

Then, run pod install to install the library.

Usage

Before you begin using SQLitePersistentObject, make sure you import the library with:

import SQLitePersistentObject

Model Structure

To work with SQLitePersistentObject, you need to create a model class that extends SQModel. Below is an example of how to structure your model:


class Person: SQModel {
    @objc var id = 0
    @objc var name: NSString = ""
    @objc var age = 0

    override class func tableName() -> String {
        return "people"
    }

    override class func tableVersion() -> Int {
        return 1
    }

    override class func primaryKeyColumn() -> String {
        return "id"
    }
}

In the example above, we define a model called Person with three properties: id, name, and age. The tableName() method specifies the name of the corresponding database table. The tableVersion() method indicates the version of the table, and the primaryKeyColumn() method declares the primary key column.

Database Operations

SQLitePersistentObject provides convenient methods to perform database operations such as inserting, updating, and deleting records. Here are some common operations:

Insert


let person = Person()
person.name = "John Doe"
person.age = 25
person.insert()

The code above creates a new Person object, sets its properties, and inserts the record into the database.

Update


if let person = Person().get(primaryKeyValue: 1) {
    person.name = "Jane Smith"
    person.update()
}

This code retrieves a Person object with primary key value 1, updates the name property, and updates the corresponding record in the database.

Delete


if let person = Person().get(primaryKeyValue: 1) {
    person.delete()
}

Here, we retrieve a Person object and delete the associated record from the database.

Querying

SQLitePersistentObject provides various methods to query the database. Here are some examples:

Get All Records


let allPeople = Person().allObjects()

This code retrieves all records from the Person table and returns an array of Person objects.

Custom Queries


let query = SQQuery(tableName: Person.tableName())
query.select(columns: ["name", "age"])
query.where(condition: "age >= 18")
query.orderBy(column: "name", ascending: true)
let adults = Person().getObjectsWithQuery(query: query)

In this example, we create a custom query using SQQuery. We select specific columns, set a condition for the age, and order the results by name. The getObjectsWithQuery() method executes the query and returns an array of Person objects.

Relationships

SQLitePersistentObject supports relationships between tables. You can define relationships using the SQRelation class. Here’s an example:


class Company: SQModel {
    // Properties...
  
    lazy var employees: SQRelation<Person> = {
        let relation = SQRelation<Person>(source: self,
                  destination: Person.self,
                  joinCondition: "company_id = \(self.id)")
        return relation
    }()
}

In this case, the Company model has a employees property that represents the relationship between the two tables. The joinCondition specifies how the tables are linked.

Migrations

SQLitePersistentObject supports migrations to manage changes to your database schema over time. To define a migration, subclass SQMigration. Here’s an example:


class MyMigration: SQMigration {
    override class func migrateDatabase() {
        let migrationBlock: (FMDatabase) -> Void = { database in
            // Perform your migration tasks here...
        }
        self.executeMigrationBlock(migrationBlock)
    }
}

In the example above, we define a migration class that includes a migrateDatabase() method. Inside this method, you can write code to handle the necessary schema changes.

Advanced Usage

SQLitePersistentObject offers additional features and customization options. Below are some more advanced topics:

Creating Indexes


class Person: SQModel {
    // Properties...
  
    override class func indexedProperties() -> [String] {
        return ["name"]
    }
}

In this example, we define an index on the name property of the Person model. This allows for faster lookup times when querying based on the indexed property.

Defining Default Values


class Person: SQModel {
    // Properties...
  
    override class func defaultValues() -> [String: Any] {
        return ["age": 18]
    }
}

Here, we set a default value of 18 for the age property of the Person model. If no value is provided during object creation, it will default to 18.

FAQ

Here are some frequently asked questions about SQLitePersistentObject:

Q: How do I handle migrations when using SQLitePersistentObject?

A: SQLitePersistentObject provides a built-in migration system. You can subclass SQMigration to define your migrations, and the library will handle applying them when necessary.

Q: How can I improve performance when querying large datasets?

A: You can create indexes on properties that are frequently used in queries to enhance performance. Additionally, consider optimizing your SQL queries to make them more efficient.

Q: Can I use SQLitePersistentObject in my macOS application?

A: Yes, SQLitePersistentObject is compatible with both iOS and macOS platforms.

Conclusion

This concludes the documentation for SQLitePersistentObject. We hope you find it helpful for working with SQLite databases in your iOS or macOS projects.