{"id":25567618,"url":"https://github.com/amsokol/ignite-go-client","last_synced_at":"2025-04-09T15:07:48.395Z","repository":{"id":57481284,"uuid":"125618146","full_name":"amsokol/ignite-go-client","owner":"amsokol","description":"Apache Ignite (GridGain) Go language client and SQL driver","archived":false,"fork":false,"pushed_at":"2022-11-16T13:49:33.000Z","size":342,"stargazers_count":65,"open_issues_count":13,"forks_count":19,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T15:07:45.207Z","etag":null,"topics":["apache-ignite","client","driver","go","golang","gridgain","ignite","sql"],"latest_commit_sha":null,"homepage":"https://apacheignite.readme.io/docs/binary-client-protocol","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amsokol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-17T10:25:01.000Z","updated_at":"2025-04-02T08:10:51.000Z","dependencies_parsed_at":"2023-01-22T08:30:55.188Z","dependency_job_id":null,"html_url":"https://github.com/amsokol/ignite-go-client","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amsokol%2Fignite-go-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amsokol%2Fignite-go-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amsokol%2Fignite-go-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amsokol%2Fignite-go-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amsokol","download_url":"https://codeload.github.com/amsokol/ignite-go-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248055284,"owners_count":21040157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache-ignite","client","driver","go","golang","gridgain","ignite","sql"],"created_at":"2025-02-20T23:32:40.118Z","updated_at":"2025-04-09T15:07:48.373Z","avatar_url":"https://github.com/amsokol.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ignite-go-client\n\n[![GoDoc](https://www.godoc.org/github.com/amsokol/ignite-go-client?status.svg)](https://www.godoc.org/github.com/amsokol/ignite-go-client)\n[![GitHub release](https://img.shields.io/github/release/amsokol/ignite-go-client.svg)](https://github.com/amsokol/ignite-go-client/releases)\n[![GitHub issues](https://img.shields.io/github/issues/amsokol/ignite-go-client.svg)](https://github.com/amsokol/ignite-go-client/issues)\n[![GitHub issues closed](https://img.shields.io/github/issues-closed/amsokol/ignite-go-client.svg)](https://github.com/amsokol/ignite-go-client/issues)\n[![Go Report Card](https://goreportcard.com/badge/amsokol/ignite-go-client)](http://goreportcard.com/report/amsokol/ignite-go-client)\n[![license](https://img.shields.io/github/license/amsokol/ignite-go-client.svg)](https://github.com/amsokol/ignite-go-client/blob/master/LICENSE)\n\n## Apache Ignite (GridGain) v2.5+ client for Go programming language\n\nThis library is production ready.\n\nVersion is less than v1.0 because not all functionality is implemented yet (see [Road map](#road-map) for details). But the implemented functionality is production ready.\n\n### Requirements\n\n- Apache Ignite v2.5+ (because of binary communication protocol is used)\n- go v1.9+\n\n### Road map\n\nProject status:\n\n1. Develop \"[Cache Configuration](https://apacheignite.readme.io/docs/binary-client-protocol-cache-configuration-operations)\" methods (Completed)\n2. Develop \"[Key-Value Queries](https://apacheignite.readme.io/docs/binary-client-protocol-key-value-operations)\" methods (Completed*)\n3. Develop \"[SQL and Scan Queries](https://apacheignite.readme.io/docs/binary-client-protocol-sql-operations)\" methods (Completed)\n4. Develop SQL driver (Completed)\n5. Develop \"[Binary Types](https://apacheignite.readme.io/docs/binary-client-protocol-binary-type-operations)\" methods (Not started)\n\n*Not all types are supported. See **[type mapping](#type-mapping)** for detail.\n\n### How to install\n\n```shell\ngo get -u github.com/amsokol/ignite-go-client/...\n```\n\n### How to use client\n\nImport client package:\n\n```go\nimport (\n    \"github.com/amsokol/ignite-go-client/binary/v1\"\n)\n```\n\nConnect to server:\n\n```go\nctx := context.Background()\n\n// connect\nc, err := ignite.Connect(ctx, ignite.ConnInfo{\n    Network: \"tcp\",\n    Host:    \"localhost\",\n    Port:    10800,\n    Major:   1,\n    Minor:   1,\n    Patch:   0,\n    // Credentials are only needed if they're configured in your Ignite server.\n    Username: \"ignite\",\n    Password: \"ignite\",\n    Dialer: net.Dialer{\n        Timeout: 10 * time.Second,\n    },\n    // Don't set the TLSConfig if your Ignite server\n    // isn't configured with any TLS certificates.\n    TLSConfig: \u0026tls.Config{\n        // You should only set this to true for testing purposes.\n        InsecureSkipVerify: true,\n    },\n})\nif err != nil {\n    t.Fatalf(\"failed connect to server: %v\", err)\n}\ndefer c.Close()\n\n```\n\nSee [example of Key-Value Queries](https://github.com/amsokol/ignite-go-client/blob/master/examples_test.go#L106) for more.\n\nSee [example of SQL Queries](https://github.com/amsokol/ignite-go-client/blob/master/examples_test.go#L181) for more.\n\nSee [\"_test.go\" files](https://github.com/amsokol/ignite-go-client/tree/master/binary/v1) for other examples.\n\n### How to use SQL driver\n\nImport SQL driver:\n\n```go\nimport (\n    \"database/sql\"\n\n    _ \"github.com/amsokol/ignite-go-client/sql\"\n)\n```\n\nConnect to server:\n\n```go\nctx := context.Background()\n\n// open connection\ndb, err := sql.Open(\"ignite\", \"tcp://localhost:10800/ExampleDB?version=1.1.0\u0026username=ignite\u0026password=ignite\"+\n    \"\u0026tls=yes\u0026tls-insecure-skip-verify=yes\u0026page-size=10000\u0026timeout=5000\")\nif err != nil {\n    t.Fatalf(\"failed to open connection: %v\", err)\n}\ndefer db.Close()\n\n```\n\nSee [example](https://github.com/amsokol/ignite-go-client/blob/master/examples_test.go#L16) for more.\n\nConnection URL format:\n\n```bash\nprotocol://host:port/cache?param1=value1\u0026param2=value2\u0026paramN=valueN\n```\n\n**URL parts:**\n\n| Name     | Mandatory | Description                                   | Default value |\n| -------- | --------- | --------------------------------------------- | ------------- |\n| protocol | no        | Connection protocol                           | tcp           |\n| host     | no        | Apache Ignite Cluster host name or IP address | 127.0.0.1     |\n| port     | no        | Max rows to return by query                   | 10800         |\n| cache    | yes       | Cache name                                    |               |\n\n**URL parameters (param1,...paramN):**\n\n| Name                     | Mandatory | Description                                                                     | Default value                     |\n| ------------------------ | --------- | ------------------------------------------------------------------------------- | --------------------------------- |\n| schema                   | no        | Database schema                                                                 | \"\" (PUBLIC schema is used)        |\n| version                  | no        | Binary protocol version in Semantic Version format                              | 1.0.0                             |\n| username                 | no        | Username                                                                        | no                                |\n| password                 | no        | Password                                                                        | no                                |\n| tls                      | no        | Connect using TLS                                                               | no                                |\n| tls-insecure-skip-verify | no        | Controls whether a client verifies the server's certificate chain and host name | no                                |\n| page-size                | no        | Query cursor page size                                                          | 10000                             |\n| max-rows                 | no        | Max rows to return by query                                                     | 0 (looks like it means unlimited) |\n| timeout                  | no        | Timeout in milliseconds to execute query                                        | 0 (disable timeout)               |\n| distributed-joins        | no        | Distributed joins (yes/no)                                                      | no                                |\n| local-query              | no        | Local query (yes/no)                                                            | no                                |\n| replicated-only          | no        | Whether query contains only replicated tables or not (yes/no)                   | no                                |\n| enforce-join-order       | no        | Enforce join order (yes/no)                                                     | no                                |\n| collocated               | no        | Whether your data is co-located or not (yes/no)                                 | no                                |\n| lazy-query               | no        | Lazy query execution (yes/no)                                                   | no                                |\n\n### How to run tests\n\n1. Download `Apache Ignite 2.7` from [official site](https://ignite.apache.org/download.cgi#binaries)\n2. Extract distributive to any folder\n3. Persistance mode is enabled to run tests. So you need to remove `\u003cpath_with_ignite\u003e\\work` folder each time to clean up test data before run tests.\n4. `cd` to `testdata` folder with `configuration-for-tests.xml` file\n5. Start Ignite server with `configuration-for-tests.xml` configuration file:\n\n```bash\n# For Windows:\n\u003cpath_with_ignite\u003e\\bin\\ignite.bat .\\configuration-for-tests.xml\n\n# For Linux:\n\u003cpath_with_ignite\u003e/bin/ignite.sh ./configuration-for-tests.xml\n```\n\n6. Activate cluster:\n\n```bash\n# For Windows:\n\u003cpath_with_ignite\u003e\\bin\\control.bat --activate --user ignite --password ignite\n\n# For Linux:\n\u003cpath_with_ignite\u003e/bin/control.bat --activate --user ignite --password ignite\n```\n\n7. Run tests into the root folder of this project:\n\n```bash\ngo test ./...\n```\n\n### Type mapping\n\n| Apache Ignite Type | Go language type                                                       |\n| ------------------ | ---------------------------------------------------------------------- |\n| byte               | byte                                                                   |\n| short              | int16                                                                  |\n| int                | int32                                                                  |\n| long               | int64, int                                                             |\n| float              | float32                                                                |\n| double             | float64                                                                |\n| char               | ignite.Char                                                            |\n| bool               | bool                                                                   |\n| String             | string                                                                 |\n| UUID (Guid)        | uuid.UUID ([UUID library from Google](https://github.com/google/uuid)) |\n| Date*              | ignite.Date / time.Time                                                |\n| byte array         | []byte                                                                 |\n| short array        | []int16                                                                |\n| int array          | []int32                                                                |\n| long array         | []int64                                                                |\n| float array        | []float32                                                              |\n| double array       | []float64                                                              |\n| char array         | []ignite.Char                                                          |\n| bool array         | []bool                                                                 |\n| String array       | []string                                                               |\n| UUID (Guid) array  | []uuid.UUID                                                            |\n| Date array*        | []ignite.Date / []time.Time                                            |\n| Object array       | Not supported. Need help.                                              |\n| Collection         | Not supported. Need help.                                              |\n| Map                | Not supported. Need help.                                              |\n| Enum               | Not supported. Need help.                                              |\n| Enum array         | Not supported. Need help.                                              |\n| Decimal            | Not supported. Need help.                                              |\n| Decimal array      | Not supported. Need help.                                              |\n| Timestamp          | time.Time                                                              |\n| Timestamp array    | []time.Time                                                            |\n| Time**             | ignite.Time / time.Time                                                |\n| Time array**       | []ignite.Time / []time.Time                                            |\n| NULL               | nil                                                                    |\n| Complex Object     | ignite.ComplexObject                                                   |\n\n**Note:** pointers (*byte, *int32, *string, *uuid.UUID, *[]time.Time, etc.) are supported also.\n\n*`Date` is outdated type. It's recommended to use `Timestamp` type.\nIf you still need `Date` type use `ignite.ToDate()` function when you **put** date:\n\n```go\nt := time.Date(2018, 4, 3, 14, 25, 32, int(time.Millisecond*123), time.UTC)\nerr := c.CachePut(\"CacheGet\", false, \"Date\", ignite.ToDate(t)) // ToDate() converts time.Time to ignite.Date\n...\n\nt, err = c.CacheGet(\"CacheGet\", false, \"Date\") // 't' is time.Time, you don't need any converting\n```\n\n**`Time` is outdated type. It's recommended to use `Timestamp` type.\nIf you still need `Time` type use `ignite.ToTime()` function when you **put** time:\n\n```go\nt := time.Date(1, 1, 1, 14, 25, 32, int(time.Millisecond*123), time.UTC)\nerr := c.CachePut(\"CacheGet\", false, \"Time\", ignite.ToTime(t)) // ToTime() converts time.Time to ignite.Time (year, month and day are ignored)\n...\n\nt, err = c.CacheGet(\"CacheGet\", false, \"Time\") // 't' is time.Time (where year=1, month=1 and day=1), you don't need any converting\n```\n\n### Example how to use **Complex Object** type\n\n```go\n// put complex object\nc1 := ignite.NewComplexObject(\"ComplexObject1\")\nc1.Set(\"field1\", \"value 1\")\nc1.Set(\"field2\", int32(2))\nc1.Set(\"field3\", true)\nc2 := ignite.NewComplexObject(\"ComplexObject2\")\nc2.Set(\"complexField1\", c1)\nif err := c.CachePut(cache, false, \"key\", c2); err != nil {\n    return err\n}\n...\n\n// get complex object\nv, err := c.CacheGet(cache, false, \"key\")\nif err != nil {\n    return err\n}\nc2 = v.(ignite.ComplexObject)\nlog.Printf(\"key=\\\"%s\\\", value=\\\"%#v\\\"\", \"key\", c2)\nv, _ = c2.Get(\"complexField1\")\nc1 = v.(ignite.ComplexObject)\nlog.Printf(\"key=\\\"%s\\\", value=\\\"%#v\\\"\", \"complexField1\", c1)\nv, _ = c1.Get(\"field1\")\nlog.Printf(\"key=\\\"%s\\\", value=\\\"%s\\\"\", \"field1\", v)\nv, _ = c1.Get(\"field2\")\nlog.Printf(\"key=\\\"%s\\\", value=%d\", \"field2\", v)\nv, _ = c1.Get(\"field3\")\nlog.Printf(\"key=\\\"%s\\\", value=%t\", \"field3\", v)\n```\n\n### SQL and Scan Queries supported operations\n\n| Operation                           | Status of implementation              |\n| ----------------------------------- | ------------------------------------- |\n| OP_QUERY_SQL                        | Done.                                 |\n| OP_QUERY_SQL_CURSOR_GET_PAGE        | Done.                                 |\n| OP_QUERY_SQL_FIELDS                 | Done.                                 |\n| OP_QUERY_SQL_FIELDS_CURSOR_GET_PAGE | Done.                                 |\n| OP_QUERY_SCAN                       | Done (without filter object support). |\n| OP_QUERY_SCAN_CURSOR_GET_PAGE       | Done (without filter object support). |\n| OP_RESOURCE_CLOSE                   | Done.                                 |\n\n### Error handling\n\nIn case of operation execution error you can get original status and error message from Apache Ignite server.\\\nExample:\n\n```go\nif err := client.CachePut(\"TestCache\", false, \"key\", \"value\"); err != nil {\n    // try to cast to *IgniteError type\n    original, ok := err.(*IgniteError)\n    if ok {\n        // log Apache Ignite status and message\n        log.Printf(\"[%d] %s\", original.IgniteStatus, original.IgniteMessage)\n    }\n    return err\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famsokol%2Fignite-go-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famsokol%2Fignite-go-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famsokol%2Fignite-go-client/lists"}