mingru (WIP)


Convert mingru-models to Go code.

All APIs are subject to change before 1.0.0

Goals:

- No performance penalty at runtime, mingru is an SQL builder, not an ORM
- Strongly typed models, models are defined in TypeScript not Go
- Currently focuses on Go and MySQL/MariaDB

---

NOTE: The documentation below is outdated!!! We are working on a brand new documentation site. Stay tuned.

---

A quick example

$3

Models are defined in mingru-models. Let's create a simple user model user.ts:

``ts
// ----------- User table model (user.ts) -----------
import * as mm from 'mingru-models';

class User extends mm.Table {
id = mm.pk();
name = mm.varChar(100);
sig = mm.text().nullable;
age = mm.int();
}

export default mm.table(User);
`

$3

Create another file (userTA.ts) for table actions and import the user table (user.ts) we just defined above:

`ts
// ----------- User table actions (userTA.ts) -----------
import * as mm from 'mingru-models';
import user from './user';

export class UserTA extends mm.TableActions {
// Select a user by ID.
selectUser = mm.selectRow(user.id, user.name, user.sig).byID();
// Select all users and order by their names.
selectAllUsers = mm.selectRows(user.id, user.name, user.sig).orderByAsc(user.name);
// Select a single user signature field by ID.
selectUserSig = mm.selectField(user.sig).byID();

// Update a user by ID.
updateUser = mm.updateOne().setParams(user.name, user.sig).byID();

// Update all user signatures to an empty string.
updateAllSigToEmpty = mm.unsafeUpdateAll().set(user.sig, mm.sql'');

// Delete a user by ID.
deleteByID = mm.deleteOne().byID();

// Delete all users by a specified name.
deleteByName = mm.deleteSome().whereSQL(user.name.isEqualToParam());

// Delete all users.
deleteAll = mm.unsafeDeleteAll();

// Insert a new user.
insertUser = mm
.insertOne()
.set(user.sig, mm.sql'Default signature!')
.setParams(user.name, user.age);
}

export default mm.tableActions(user, UserTA);
`

$3

Install mingru-tsconfig:

`sh
yarn add mingru-tsconfig -D
`

Set extends to mingru-tsconfig in your local tsconfig.json:

`json
{
"extends": "mingru-tsconfig"
}
`

Create a mingru.ts file, which will start the build process to generate Go and SQL code.

`ts
import * as mr from 'mingru';
// Import table actions.
import userTA from './userTA';
// Import tables if you need to generate CREATE TABLE SQL files.
import user from './user';

(async () => {
const dialect = new mr.MySQL();
// Build Go code to '../da/ directory.
const builder = new mr.Builder(dialect, './data_access_layer/', {
// Clean build directory on each build.
cleanBuild: true,
});

const actions = [userTA];
const tables = [user];
// Start the build process by calling the build method.
await builder.buildAsync(async () => {
// Generate Go source files.
await builder.buildActionsAsync(actions);
// Generate CREATE TABLE SQL files.
await builder.buildCreateTableSQLFilesAsync(tables);
});
})();
``

It's also recommended to use ts-node and add a build command to package.json scripts section:

`json
{
"scripts": {
"build": "ts-node mingru.ts"
}
}
`

Now you can build your project using yarn build.

Below is the code generated by mingru:

$3

`go
func main() {
// Open a DB connection on localhost.
db, err := sql.Open("mysql", "root:123456@/test")
if err != nil {
panic(err)
}

// Select all user profiles.
users, err := da.User.SelectAllUserProfiles(db)
if err != nil {
panic(err)
}

// Loop through the result.
for _, user := range users {
fmt.Printf("ID: %v, Name: %v, Sig: %v\n", user.ID, user.Name, user.Sig)
}
}
`

$3

For a more detailed and runnable example, visit mingru-go-example

Advanced Topics

$3

MySQL doesn't allow you to use a non-constant value as a default value for a column because CREATE TABLE doesn't allow it. mingru supports arbitrary default values for both CREATE and UPDATE actions by simply passing default values into generated SQL.

$3

#### limit

Pagination can be achieved by calling limit following a call to selectRows:

`ts
selectUsersWithLimit = mm.selectRows(user.id, user.name).limit();
`

Implementations should expose arguments to set the underlying SQL LIMIT and OFFSET values, here is the Go method signature generated by mingru from the action above:

`go
func (mrTable UserAGType) SelectUsersWithLimit(mrQueryable mingru.Queryable, limit int, offset int, max int) ([]SelectUsersWithLimitResult, int, error)
`

#### selectPage

Pagination can also be done via selectPage method, selectPage usually generates a method built upon the SQL LIMIT and OFFSET clauses but exposes higher level arguments thus provides more convenience:

`ts
selectPagedUsers = mm.selectPage(user.id, user.name);
`

mingru converts the action above to the following Go func:

`go
func (mrTable UserAGType) SelectPagedUsers(mrQueryable mingru.Queryable, page int, pageSize int) ([]SelectPagedUsersResult, bool, error)
`

Notice the limit and offset arguments are gone, page and pageSize are exposed instead. Also the second return value changed from rowsFetched(int) to hasNextPage(bool`).