Lucid SQL ORM Documentation

You can override default type mappings and decorators by creating rules files. Rules can be defined at three levels:

1. Table-specific column rules: Highest priority. Targets a specific column in a specific table.
2. Table-specific type rules: Targets all columns of a specific database type within a specific table.
3. Global column rules: Targets a specific column name across all tables.
4. Global type rules: Targets all columns of a specific database type across all tables.
5. Default built-in mapping: The fallback behavior.

Rules are merged using a deep merge strategy; if you provide multiple files via rulesPaths, later files override earlier ones.

// config/schema_rules.ts
export default {
  // Global column name rules
  columns: {
    status: {
      tsType: 'UserStatus',
      decorator: '@column()',
      imports: [{ source: '#types/enums', namedImports: ['UserStatus'] }]
    }
  },

  // Global type rules
  types: {
    uuid: {
      tsType: 'string',
      decorator: '@column()',
      imports: []
    }
  },

  // Table-specific rules
  tables: {
    users: {
      columns: {
        email: {
          tsType: 'string',
          decorator: '@column({ isPrimary: true })',
          imports: []
        }
      }
    }
  }
}

You can define relationships in factories using .relation(name, callback). Once defined, you can use the .with() method to instantiate related models during creation.

• Has One / Has Many: Use .with('relationName') or .with('relationName', count).
• Belongs To: Use .with('relationName') to create the parent, or manually merge the foreign key.
• Many to Many: Use .with('relationName', count) and use the callback to provide pivotAttributes.
• Nested Relationships: You can chain .with() calls to create deep trees of data.

// Has Many example
export const UserFactory = Factory.define(User, ({ faker }) => {
  return { email: faker.internet.email() }
})
.relation('posts', () => PostFactory)
.build()

// Create user with 5 posts
const user = await UserFactory.with('posts', 5).create()

// Nested: User with posts, and each post has comments
const user = await UserFactory
  .with('posts', 2, (post) => {
    post.with('comments', 5)
  })
  .create()

// Many to Many with pivot data
const user = await UserFactory
  .with('roles', 2, (role) => {
    role.pivotAttributes({ expiresAt: DateTime.now().plus({ days: 30 }) })
  })
  .create()

SimplePaginator provides a lightweight pagination mechanism that does not calculate the total count of records, making it more performant for large datasets where you only need to know if a next page exists.

Properties

• all(): Returns all rows in the current page.
• perPage: Number of items per page.
• currentPage: Current page number.
• firstPage: Always 1.
• hasPages: Boolean indicating if there is more than one page.
• hasMorePages: Boolean indicating if there is a next page.
• isEmpty: Boolean indicating if there are no results.

Methods

• getUrl(page: number): Returns the URL for a specific page.
• getUrls(): Returns an object containing URLs for first, last, and optionally next and previous pages.
• getQueryString(page: number): Returns the query string for a specific page.
• toJSON(): Converts the paginator to a JSON object containing meta and data keys.

When you need to transform or migrate data as part of a schema change (e.g., moving data from an old column to a new one), use this.defer(). This ensures the data operations run after the schema changes are applied.

Example: Adding a status column and populating it based on an existing is_active boolean column, then dropping the old column.

export default class extends BaseSchema {
  protected tableName = 'users'

  async up() {
    // Add new column
    this.schema.alterTable(this.tableName, (table) => {
      table.string('status').defaultTo('active')
    })

    // Migrate data
    this.defer(async (db) => {
      const users = await db.from('users').select('*')

      for (const user of users) {
        await db.from('users')
          .where('id', user.id)
          .update({
            status: user.is_active ? 'active' : 'inactive'
          })
      }
    })

    // Drop old column
    this.schema.alterTable(this.tableName, (table) => {
      table.dropColumn('is_active')
    })
  }

  async down() {
    // ... reverse logic ...
  }
}