## File: cmd/gf/README.MD

English | [简体中文](README.zh_CN.MD)

# gf

`gf` is a powerful CLI tool for building [GoFrame](https://goframe.org) application with convenience.

## 1. Install

## 1) PreCompiled Binary

You can also install `gf` tool using pre-built binaries: <https://github.com/gogf/gf/releases>

1. `Mac` & `Linux`

   ```shell
    wget -O gf https://github.com/gogf/gf/releases/latest/download/gf_$(go env GOOS)_$(go env GOARCH) && chmod +x gf && ./gf install -y && rm ./gf
   ```

   > If you're using `zsh`, you might need rename your alias by command `alias gf=gf` to resolve the conflicts between `gf` and `git fetch`.

2. `Windows`
   Manually download, execute in command line it and then follow the instruction.

3. Database support

   |     DB     | builtin support |                                                                             remarks                                                                             |
   | :--------: | :-------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------: |
   |   mysql    |       yes       |                                                                                -                                                                                |
   |  mariadb   |       yes       |                                                                                -                                                                                |
   |    tidb    |       yes       |                                                                                -                                                                                |
   |   mssql    |       yes       |                                                                                -                                                                                |
   |   oracle   |       yes       |                                                                                -                                                                                |
   |   pgsql    |       yes       |                                                                                -                                                                                |
   |   sqlite   |       yes       |                                                                                -                                                                                |
   | sqlitecgo  |       no        | to support sqlite database on 32bit architecture systems, manually add package import to the [source codes](./internal/cmd/cmd_gen_dao.go) and do the building. |
   | clickhouse |       yes       |                                                                                -                                                                                |
   |     dm     |       no        |                              manually add package import to the [source codes](./internal/cmd/cmd_gen_dao.go) and do the building.                              |

## 2) Manually Install

```shell
go install github.com/gogf/gf/cmd/gf/v2@latest # latest version
go install github.com/gogf/gf/cmd/gf/v2@v2.5.5 # certain version(should be >= v2.5.5)
```

## 2. Commands

```shell
$ gf -h
USAGE
    gf COMMAND [OPTION]

COMMAND
    up         upgrade GoFrame version/tool to latest one in current project
    env        show current Golang environment variables
    fix        auto fixing codes after upgrading to new GoFrame version
    run        running go codes with hot-compiled-like feature
    gen        automatically generate go files for dao/do/entity/pb/pbentity
    tpl        template parsing and building commands
    init       create and initialize an empty GoFrame project
    pack       packing any file/directory to a resource file, or a go file
    build      cross-building go project for lots of platforms
    docker     build docker image for current GoFrame project
    install    install gf binary to system (might need root/admin permission)
    version    show version information of current binary
    doc        download https://pages.goframe.org/ to run locally

OPTION
    -y, --yes       all yes for all command without prompt ask
    -v, --version   show version information of current binary
    -d, --debug     show internal detailed debugging information
    -h, --help      more information about this command

ADDITIONAL
    Use "gf COMMAND -h" for details about a command.
```

## 3. FAQ

### 1). Command `gf run` returns `pipe: too many open files`

Please use `ulimit -n 65535` to enlarge your system configuration for max open files for current terminal shell session, and then `gf run`.

---

## File: contrib/registry/polaris/README.MD

# GoFrame Polaris Registry

English | [简体中文](README_ZH.MD)

Use `PolarisMesh` as service registration, discovery management and heartbeat reporting.

## Installation

```
go get -u -v github.com/gogf/gf/contrib/registry/polaris/v2
```

suggested using `go.mod`:

```
require github.com/gogf/gf/contrib/registry/polaris/v2 latest
```

## Example

### Reference example

[server](../../../example/registry/polaris/server/server.go)

```go
package main

import (
    "github.com/polarismesh/polaris-go/pkg/config"
    
    "github.com/gogf/gf/contrib/registry/polaris/v2"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
    "github.com/gogf/gf/v2/net/gsvc"
)

func main() {
    conf := config.NewDefaultConfiguration([]string{"183.47.111.80:8091"})
    
    // TTL egt 2*time.Second
    gsvc.SetRegistry(polaris.NewWithConfig(conf, polaris.WithTTL(10)))
    
    s := g.Server(`hello.svc`)
    s.BindHandler("/", func(r *ghttp.Request) {
        g.Log().Info(r.Context(), `request received`)
        r.Response.Write(`Hello world`)
    })
    s.Run()
}
```

[client](../../../example/registry/polaris/client/client.go)

```go
package main

import (
    "fmt"
    "time"
    
    "github.com/polarismesh/polaris-go/pkg/config"
    
    "github.com/gogf/gf/contrib/registry/polaris/v2"
    
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/gsvc"
    "github.com/gogf/gf/v2/os/gctx"
)

func main() {
    conf := config.NewDefaultConfiguration([]string{"183.47.111.80:8091"})
    
    gsvc.SetRegistry(polaris.NewWithConfig(conf, polaris.WithTTL(10)))
    
    for i := 0; i < 100; i++ {
        res, err := g.Client().Get(gctx.New(), `http://hello.svc/`)
        if err != nil {
            panic(err)
        }
        fmt.Println(res.ReadAllString())
        res.Close()
        time.Sleep(time.Second)
    }
}
```

## License

`GoFrame Polaris` is licensed under the [MIT License](../../../LICENSE), 100% free and open-source, forever.

---

## File: contrib/registry/polaris/README_ZH.MD

# GoFrame Polaris Registry

[English](README.MD) | 简体中文

使用`PolarisMesh`作为服务注册、发现管理和心跳上报。

## 安装

```
go get -u -v github.com/gogf/gf/contrib/registry/polaris/v2
```

suggested using `go.mod`:

```
require github.com/gogf/gf/contrib/registry/polaris/v2 latest
```

## Golang版本限制

```
golang version >= 1.20
```

## 示例

### 引用示例

[服务端](example/registry/polaris/server/main.go)

```go
package main

import (
    "github.com/polarismesh/polaris-go/pkg/config"
    
    "github.com/gogf/gf/contrib/registry/polaris/v2"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
    "github.com/gogf/gf/v2/net/gsvc"
)

func main() {
    conf := config.NewDefaultConfiguration([]string{"183.47.111.80:8091"})
    
    // TTL egt 2*time.Second
    gsvc.SetRegistry(polaris.NewWithConfig(conf, polaris.WithTTL(10)))
    
    s := g.Server(`hello.svc`)
    s.BindHandler("/", func(r *ghttp.Request) {
        g.Log().Info(r.Context(), `request received`)
        r.Response.Write(`Hello world`)
    })
    s.Run()
}

```

[客户端](example/registry/polaris/client/main.go)

```go
package main

import (
    "fmt"
    "time"
    
    "github.com/polarismesh/polaris-go/pkg/config"
    
    "github.com/gogf/gf/contrib/registry/polaris/v2"
    
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/gsvc"
    "github.com/gogf/gf/v2/os/gctx"
)

func main() {
    conf := config.NewDefaultConfiguration([]string{"183.47.111.80:8091"})
    
    gsvc.SetRegistry(polaris.NewWithConfig(conf, polaris.WithTTL(10)))
    
    for i := 0; i < 100; i++ {
        res, err := g.Client().Get(gctx.New(), `http://hello.svc/`)
        if err != nil {
            panic(err)
        }
        fmt.Println(res.ReadAllString())
        res.Close()
        time.Sleep(time.Second)
    }
}

```

## 协议

`GoFrame Polaris` 使用非常友好的 [MIT](../../../LICENSE) 开源协议进行发布，永久`100%`开源免费。

---

## File: contrib/registry/nacos/README.MD

# GoFrame Nacos Registry

Use `nacos` as service registration and discovery management.

## Installation

```
go get -u -v github.com/gogf/gf/contrib/registry/nacos/v2
```

suggested using `go.mod`:

```
require github.com/gogf/gf/contrib/registry/nacos/v2 latest
```

## Example

### Reference example

[server](../../../example/registry/nacos/http/server/main.go)

```go
package main

import (
	"github.com/gogf/gf/contrib/registry/nacos/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
	"github.com/gogf/gf/v2/net/gsvc"
)

func main() {
	gsvc.SetRegistry(nacos.New(`127.0.0.1:8848`).
        SetClusterName("DEFAULT").
        SetGroupName("DEFAULT_GROUP"))

	s := g.Server(`hello.svc`)
	s.BindHandler("/", func(r *ghttp.Request) {
		g.Log().Info(r.Context(), `request received`)
		r.Response.Write(`Hello world`)
	})
	s.Run()
}
```

[client](../../../example/registry/nacos/http/client/main.go)

```go
package main

import (
	"fmt"
	"time"

	"github.com/gogf/gf/contrib/registry/nacos/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/gsel"
	"github.com/gogf/gf/v2/net/gsvc"
	"github.com/gogf/gf/v2/os/gctx"
)

func main() {
	gsvc.SetRegistry(nacos.New(`127.0.0.1:8848`))
	gsel.SetBuilder(gsel.NewBuilderRoundRobin())

	client := g.Client()
	for i := 0; i < 100; i++ {
		res, err := client.Get(gctx.New(), `http://hello.svc/`)
		if err != nil {
			panic(err)
		}
		fmt.Println(res.ReadAllString())
		res.Close()
		time.Sleep(time.Second)
	}
}
```

## License

`GoFrame Nacos` is licensed under the [MIT License](../../../LICENSE), 100% free and open-source, forever.

---

## File: contrib/registry/file/README.MD

# GoFrame File Registry


Use `file` as service registration and discovery management.


## Installation
```
go get -u -v github.com/gogf/gf/contrib/registry/file/v2
```
suggested using `go.mod`:
```
require github.com/gogf/gf/contrib/registry/file/v2 latest
```


## Example

### Reference example

[server](../../../example/registry/file/server/server.go)
```go
package main

import (
	"github.com/gogf/gf/contrib/registry/file/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
	"github.com/gogf/gf/v2/net/gsvc"
	"github.com/gogf/gf/v2/os/gfile"
)

func main() {
	gsvc.SetRegistry(file.New(gfile.Temp("gsvc")))

	s := g.Server(`hello.svc`)
	s.BindHandler("/", func(r *ghttp.Request) {
		g.Log().Info(r.Context(), `request received`)
		r.Response.Write(`Hello world`)
	})
	s.Run()
}

```

[client](../../../example/registry/file/client/client.go)
```go
package main

import (
	"fmt"
	"time"

	"github.com/gogf/gf/contrib/registry/file/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/gsvc"
	"github.com/gogf/gf/v2/os/gctx"
	"github.com/gogf/gf/v2/os/gfile"
)

func main() {
	gsvc.SetRegistry(file.New(gfile.Temp("gsvc")))

	client := g.Client()
	for i := 0; i < 100; i++ {
		res, err := client.Get(gctx.New(), `http://hello.svc/`)
		if err != nil {
			panic(err)
		}
		fmt.Println(res.ReadAllString())
		res.Close()
		time.Sleep(time.Second)
	}
}

```

---

## File: contrib/registry/etcd/README.MD

# GoFrame Etcd Registry


Use `etcd` as service registration and discovery management.


## Installation
```
go get -u -v github.com/gogf/gf/contrib/registry/etcd/v2
```
suggested using `go.mod`:
```
require github.com/gogf/gf/contrib/registry/etcd/v2 latest
```


## Example

### Reference example

[server](../../../example/registry/etcd/http/server/server.go)
```go
package main

import (
	"github.com/gogf/gf/contrib/registry/etcd/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
	"github.com/gogf/gf/v2/net/gsvc"
)

func main() {
	gsvc.SetRegistry(etcd.New(`127.0.0.1:2379`))

	s := g.Server(`hello.svc`)
	s.BindHandler("/", func(r *ghttp.Request) {
		g.Log().Info(r.Context(), `request received`)
		r.Response.Write(`Hello world`)
	})
	s.Run()
}
```

[client](../../../example/registry/etcd/http/client/client.go)
```go
package main

import (
	"fmt"
	"time"

	"github.com/gogf/gf/contrib/registry/etcd/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/gsel"
	"github.com/gogf/gf/v2/net/gsvc"
	"github.com/gogf/gf/v2/os/gctx"
)

func main() {
	gsvc.SetRegistry(etcd.New(`127.0.0.1:2379`))
	gsel.SetBuilder(gsel.NewBuilderRoundRobin())

	client := g.Client()
	for i := 0; i < 100; i++ {
		res, err := client.Get(gctx.New(), `http://hello.svc/`)
		if err != nil {
			panic(err)
		}
		fmt.Println(res.ReadAllString())
		res.Close()
		time.Sleep(time.Second)
	}
}
```

## License

`GoFrame etcd` is licensed under the [MIT License](../../../LICENSE), 100% free and open-source, forever.

---

## File: contrib/registry/consul/README.MD

# GoFrame Consul Registry

Use `consul` as service registration and discovery management.

## Installation
```bash
go get -u github.com/gogf/gf/contrib/registry/consul/v2
```
suggested using `go.mod`:
```bash
require github.com/gogf/gf/contrib/registry/consul/v2 latest
```

## Example

### HTTP Server
```go
package main

import (
    "context"
    
    "github.com/gogf/gf/contrib/registry/consul/v2"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
    "github.com/gogf/gf/v2/net/gsvc"
)

func main() {
    registry, err := consul.New(consul.WithAddress("127.0.0.1:8500"))
    if err != nil {
        g.Log().Fatal(context.Background(), err)
    }
    gsvc.SetRegistry(registry)

    s := g.Server("hello.svc")
    s.BindHandler("/", func(r *ghttp.Request) {
        g.Log().Info(r.Context(), "request received")
        r.Response.Write("Hello world")
    })
    s.Run()
}
```

### HTTP Client
```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/gogf/gf/contrib/registry/consul/v2"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/gsel"
    "github.com/gogf/gf/v2/net/gsvc"
    "github.com/gogf/gf/v2/os/gctx"
)

func main() {
    registry, err := consul.New(consul.WithAddress("127.0.0.1:8500"))
    if err != nil {
        g.Log().Fatal(context.Background(), err)
    }
    gsvc.SetRegistry(registry)
    gsel.SetBuilder(gsel.NewBuilderRoundRobin())

    client := g.Client()
    for i := 0; i < 100; i++ {
        res, err := client.Get(gctx.New(), "http://hello.svc/")
        if err != nil {
            panic(err)
        }
        fmt.Println(res.ReadAllString())
        res.Close()
        time.Sleep(time.Second)
    }
}
```

## Configuration Options

The registry supports the following configuration options:

- `WithAddress(address string)`: Sets the Consul server address (default: "127.0.0.1:8500")
- `WithToken(token string)`: Sets the ACL token for Consul authentication

## Features

- Service registration with TTL health check
- Service discovery with health status filtering
- Service metadata support
- Watch support for service changes
- Consul ACL token support

## Requirements

- Go 1.18 or higher
- Consul 1.0 or higher

## License

`GoFrame Consul` is licensed under the [MIT License](../../../LICENSE), 100% free and open-source, forever.

---

## File: contrib/registry/zookeeper/README.MD

# GoFrame Etcd Registry

Use `zookeeper` as service registration and discovery management.

## Installation
```
go get -u -v github.com/gogf/gf/contrib/registry/zookeeper/v2
```
suggested using `go.mod`:
```
require github.com/gogf/gf/contrib/registry/zookeeper/v2 latest
```

```go
package main

import (
	"github.com/gogf/gf/contrib/registry/zookeeper/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/ghttp"
	"github.com/gogf/gf/v2/net/gsvc"
)

func main() {
	gsvc.SetRegistry(zookeeper.New(
		[]string{"127.0.0.1:2181"}, zookeeper.WithRootPath("/gogf"),
    ))
	
	s := g.Server(`hello.svc`)
	s.BindHandler("/", func(r *ghttp.Request) {
		g.Log().Info(r.Context(), `request received`)
		r.Response.Write(`Hello world`)
	})
	s.Run()
}
```

```go
package main

import (
	"fmt"
	"time"

	"github.com/gogf/gf/contrib/registry/zookeeper/v2"
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/net/gsel"
	"github.com/gogf/gf/v2/net/gsvc"
	"github.com/gogf/gf/v2/os/gctx"
)

func main() {
	gsvc.SetRegistry(zookeeper.New(
		[]string{"127.0.0.1:2181"}, zookeeper.WithRootPath("/gogf"),
	))
	gsel.SetBuilder(gsel.NewBuilderRoundRobin())

	client := g.Client()
	for i := 0; i < 100; i++ {
		res, err := client.Get(gctx.New(), `http://hello.svc/`)
		if err != nil {
			panic(err)
		}
		fmt.Println(res.ReadAllString())
		res.Close()
		time.Sleep(time.Second)
	}
}
```

## License

`GoFrame zookeeper` is licensed under the [MIT License](../../../LICENSE), 100% free and open-source, forever.