# asyncsql4lua

**Repository Path**: greatwallisme/asyncsql4lua

## Basic Information

- **Project Name**: asyncsql4lua
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 0
- **Created**: 2025-07-31
- **Last Updated**: 2025-09-01

## Categories & Tags

**Categories**: database-dev

**Tags**: None

## README

# ASYNCSQL4LUA

## Project Overview
This project is inspired by [LuaSQL](https://lunarmodules.github.io/luasql/), which is a SQL library for Lua implemented in C. In this project, I'm implementing a similar library for Lua, but using Rust as the backend. This is an async SQL library for Lua implemented as a Rust dynamic library. It provides async database operations through Lua coroutines using mlua, sqlx and tiberius, supporting SQLite, MySQL, PostgreSQL and MsSQL.

## Build Commands

- `cargo build --release` - Build the Rust library (outputs `.so` file)
- `cp target/release/libasyncsql4lua.so lua/asyncsql4lua.so` - Copy the built library to Lua directory  
- `cd lua && lua sqlite.lua` - Run SQLite test
- `cd lua && lua mysql.lua` - Run MySQL test
- `cd lua && lua postgres.lua` - Run PostgreSQL test
- `cd lua && lua mssql.lua` - Run Microsoft SQL Server test

## Architecture

The project consists of:

### Rust Side (`src/`)
- **Core**: `src/lib.rs` - Module initialization and Lua interface setup
- **Database abstraction**: `src/database.rs` - Trait defining common database interface
- **Database implementations**:
  - `src/sqlite.rs` - SQLite implementation
  - `src/mysql.rs` - MySQL implementation
  - `src/postgres.rs` - PostgreSQL implementation
  - `src/mssql.rs` - Microsoft SQL Server implementation
- **Utilities**:
  - `src/value_helper.rs` - Type conversion from SQL to Lua values
  - `src/env.rs` - Global Tokio runtime setup

### Lua Side (`lua/`)
- **Wrapper scripts**:
  - `sqlite.lua` - SQLite coroutine wrapper
  - `mysql.lua` - MySQL coroutine wrapper
  - `postgres.lua` - PostgreSQL coroutine wrapper
  - `mssql.lua` - Microsoft SQL Server coroutine wrapper

## Key Components

### Database Interface Pattern
Each database implements the `DataBase` trait (`src/database.rs:7-12`) with:
- `connect()` - Establish database connection
- `execute()` - Execute SQL without results
- `query()` - Execute SQL and return results as Lua tables

### Async Pattern
- Rust async methods are exposed to Lua via mlua's async methods
- Lua uses `coroutine.wrap` pattern to handle async operations synchronously
- All database operations run on a global Tokio runtime (`src/env.rs`)

### Type Conversion
- `value_helper.rs` handles conversion from SQL types to Lua values
- Each database has specific type mapping functions (sqlite2lua, mysql2lua, postgres2lua, mssql2lua)

## Usage Pattern

Lua usage follows this pattern:
```lua
local sqlite = require("asyncsql4lua").sqlite

-- Must be called within coroutines using coroutine.wrap
local function connect(database)
    local inner_fn = coroutine.wrap(function()
        sqlite:connect(database)
    end)
    while true do
        if inner_fn() == nil then break end
    end
end
```

## Development Notes

- The `.so` file is automatically placed in `lua/` directory after build
- Each database type has identical API surface but different connection parameters
- SQLite uses file-based connections, MySQL/PostgreSQL/MsSQL use network connections
- Type conversion handles NULL values as Lua nil
- All SQL results are returned as 1-indexed Lua tables

## Future Work
- [ ] Continue to improve related functional details (for postgres, mssql execute method currently cannot return last_insert_id)
- [ ] Implement ORM at Lua level by referencing the [4DaysORM](https://github.com/itdxer/4DaysORM) project

## License
This project is licensed under Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)