Expo SQLite Eloquent ORM

Expo SQLite Eloquent ORM is a lightweight Object-Relational Mapping (ORM) wrapper for the expo-sqlite module, designed to provide a fluent and intuitive API for handling database operations in React Native applications. Inspired by Laravel's Eloquent, this library simplifies the process of interacting with SQLite databases by abstracting complex SQL queries into easy-to-understand JavaScript methods.

Features

• Fluent query builder for SQLite databases
• Easy-to-use API for defining models and performing CRUD operations
• Automatic casting of attributes to specified data types
• Support for relationships and eager loading
• Migration system for database versioning and setup

Installation

To install Expo SQLite Eloquent ORM, you need to have an Expo or React Native project set up. Then run:

1npm install expo-sqlite-eloquent-orm
2# or
3yarn add expo-sqlite-eloquent-orm

Run the Example App

• git clone expo-sqlite-eloquent-orm
• cd expo-sqlite-eloquent-orm/example
• npm run start
• Example code is all in the App.js file, https://github.com/theianjohnson/expo-sqlite-eloquent-orm/blob/main/example/App.js

Model Class API

Static Methods

Method	Description	Return Type	Parameters
table	Sets the table name for queries.	Model	name: string
select	Specifies the fields to select in a query.	Model	fields: string | string[]
join	Adds a join clause to the query.	Model	type: 'INNER' | 'LEFT' | 'RIGHT', table: string, firstKey: string, secondKey: string
where	Adds a where clause to the query.	Model	column: string, operatorOrValue: any, value?: any
orderBy	Adds an order by clause to the query.	Model	column: string, direction: 'ASC' | 'DESC'
limit	Sets a limit on the number of records returned.	Model	number: number
with	Specifies relations to include in the query results.	Model	relation: string
find	Finds a record by its ID.	Promise<Model | null>	id: number | string
insert	Inserts a new record into the database.	Promise<SQLResult>	data: Record<string, any>
seed	Seeds data into the database if the table is empty.	Promise<void>	data: Array<Record<string, any>>
executeSql	Executes a custom SQL query.	Promise<SQLResult>	sql: string, params: any[]

Instance Methods

Method	Description	Return Type	Parameters
insert	Instance method to insert a new record.	Promise<SQLResult>	data: Record<string, any>
save	Saves the current instance to the database.	Promise<SQLResult>	-
delete	Deletes the current instance from the database.	Promise<SQLResult>	-
get	Retrieves records based on the current query.	Promise<Model[]>	-
first	Retrieves the first record based on the current query.	Promise<Model | null>	-
update	Updates the current instance in the database.	Promise<SQLResult>	attributes: Partial<ModelAttributes>
hasOne	Defines a has-one relationship.	Promise<Model | null>	relatedModel: Model, foreignKey?: string, localKey: string = 'id'
hasMany	Defines a has-many relationship.	Promise<Model[]>	relatedModel: Model, foreignKey?: string, localKey: string = 'id'
belongsTo	Defines a belongs-to relationship.	Promise<Model | null>	relatedModel: Model, foreignKey: string, otherKey: string = 'id'
belongsToMany	Defines a belongs-to-many relationship.	Promise<Model[]>	relatedModel: typeof Model, joinTableName?: string, foreignKey?: string, otherKey?: string

Types and Interfaces

• Casts: Record of attribute types ('number' \| 'boolean' \| 'string' \| 'json').
• Clauses: Object representing different clauses in a query.
• ModelAttributes: Record of any type representing model attributes.
• SQLResult: Interface representing the result of an SQL query.

Note: Some methods are simplified for brevity. Consult the source code for detailed implementation.

Quick Start

To get started with expo-sqlite-eloquent-orm, you'll need to setup your initial migrations and define your models.

Running Migrations

expo-sqlite-eloquent-orm provides a migration system to manage your database schema and versioning. You can define migrations to create and modify tables in a structured manner.

To run migrations, you need to create migration files and then execute them. You can use the Migration class to handle migrations. Here's an example of how to create and run migrations:

1import { Migration } from 'expo-sqlite-eloquent-orm';
2
3// Define your migration scripts
4const migrations = {
5  '1699486848_init': `
6    CREATE TABLE IF NOT EXISTS users (
7      id INTEGER PRIMARY KEY AUTOINCREMENT,
8      name TEXT,
9      email TEXT
10    );
11  `,
12  '1699486885_updating_users_table': `
13    ALTER TABLE users ADD COLUMN active BOOLEAN;
14  `,
15};
16
17// Run migrations
18try { 
19  await Migration.runMigrations(migrations);
20} catch(error) {
21  console.error('Error running migrations:', error);
22}

Defining Models

Create models by extending the Model class. Specify your table name and any casts for attributes:

1import { Model } from 'expo-sqlite-eloquent-orm';
2
3class User extends Model {
4  static tableName = 'users';
5  static casts = {
6    id: 'number',
7    active: 'boolean',
8    // other attributes...
9  };
10  // Define relationships, custom methods, etc.
11}

Querying

Utilize model methods to perform queries:

1// Retrieve a user by ID
2const user = await User.find(1);
3
4// Get all users with a specific attribute
5const activeUsers = await User.where('active', '=', true).get();
6
7// Chain query methods for more complex queries
8const specificUsers = await User.select(['id', 'name'])
9                                .where('active', '=', true)
10                                .orderBy('name', 'DESC')
11                                .limit(10)
12                                .get();
13
14

Inserting Records

To insert new records into the database, create a new instance of your model with the desired attributes, and then call the save method:

1// Create a new user instance
2const newUser = new User({
3  name: 'John Doe',
4  email: 'john@example.com',
5  active: true
6});
7
8// Insert the new user into the database
9await newUser.save();

Updating Records

To update an existing record, retrieve the model instance, set the new attribute values, and then call the save method:

1// Retrieve a user by ID
2const user = await User.find(1);
3
4// Update attributes
5user.name = 'Jane Doe';
6user.email = 'jane.doe@example.com';
7
8// Save the changes to the database
9await user.save();

Deleting Records

To delete a record from the database, retrieve the model instance and then call the delete method:

1// Retrieve a user by ID
2const user = await User.find(1);
3
4// Delete the user from the database
5await user.delete();
6
7// Delete all inactive users
8await User.where('active', '=', false).delete();

Relationships

expo-sqlite-eloquent-orm supports defining and using relationships between models, making it easy to work with related data.

One-to-One Relationship

To define a one-to-one relationship between two models, you can use the hasOne method on the model that declares the relationship. For example, if you have a User model and a Profile model where each user has one profile:

1class User extends Model {
2  // ...
3  
4  async profile() {
5    return this.hasOne(Profile, 'userId');
6  }
7}
8
9class Profile extends Model {
10  // ...
11}
12
13const user = await User.find(1);
14
15// Automatically loaded
16const userProfile = user.profile;

One-to-Many Relationship

To define a one-to-many relationship, use the hasMany method. For instance, if each User can have multiple Post records:

1class User extends Model {
2  // ...
3  
4  async posts() {
5    return this.hasMany(Post, 'userId');
6  }
7}
8
9class Post extends Model {
10  // ...
11}
12
13const user = await User.find(1);
14
15// Automatically loaded
16const userPosts = user.posts;

Many-to-One Relationship

To define a many-to-one relationship, use the belongsTo method. For example, if each Post belongs to a single User:

1class Post extends Model {
2  // ...
3  
4  async user() {
5    return this.belongsTo(User, 'userId');
6  }
7}
8
9class User extends Model {
10  // ...
11}
12
13const post = await Post.find(1);
14
15// Automatically loaded
16const postUser = await post.user;

To Do

[] Fix where('column', null) to accept actual null and just string 'null' [] Fix Typescript errors when defining models, ie "Class static side 'typeof Person' incorrectly extends base class static side 'typeof Model'." [] Many to many attach/detach methods [] Update .with() to accept an array of relationships [] Add .from() that proxies to .table()? [] Update .table() to accept an array of relationships (for joins) [] Add .query() for raw query with params [] Add .create() that returns the created model (https://laravel.com/docs/10.x/eloquent#inserts) [] whereRaw [] Bulk eager loading, currently eager loading is n+1 [] Reactivity? Caching with automatic invalidation?