From eaf0112a1af7e9eb8c2d867b616534f615bd50fd Mon Sep 17 00:00:00 2001 From: Oleg Jukovec Date: Sun, 11 Feb 2024 19:54:14 +0300 Subject: [PATCH 1/4] doc: add the migration guide to v2.0.0 --- MIGRATION.md | 300 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 252 +++++++------------------------------------ 2 files changed, 336 insertions(+), 216 deletions(-) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 00000000..1f07639a --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,300 @@ +# Migration guide + +## Migration from v1.x.x to v2.x.x + +* [Major changes](#major-changes) +* [Main package](#main-package) + * [Go version](#go-version) + * [msgpack/v5](#msgpackv5) + * [Call = Call17](#call--call17) + * [IPROTO constants](#iproto-constants) + * [Request interface](#request-interface) + * [Request changes](#request-changes) + * [Response interface](#response-interface) + * [Response changes](#response-changes) + * [Future type](#future-type) + * [Protocol types](#protocol-types) + * [Connector interface](#connector-interface) + * [Connect function](#connect-function) + * [Connection schema](#connection-schema) + * [Schema type](#schema-type) +* [datetime package](#datetime-package) +* [decimal package](#decimal-package) +* [multi package](#multi-package) +* [pool package](#pool-package) +* [crud package](#crud-package) +* [test_helpers package](#test_helpers-package) + +### Major changes + +* The `go_tarantool_call_17` build tag is no longer needed, since by default + the `CallRequest` is `Call17Request`. +* The `go_tarantool_msgpack_v5` build tag is no longer needed, since only the + `msgpack/v5` library is used. +* The `go_tarantool_ssl_disable` build tag is no longer needed, since the + connector is no longer depends on `OpenSSL` by default. You could use the + external library [go-tlsdialer](https://github.com/tarantool/go-tlsdialer) to + create a connection with the `ssl` transport. +* Required Go version is `1.20` now. +* The `Connect` function became more flexible. It now allows to create a + connection with cancellation and a custom `Dialer` implementation. +* It is required to use `Request` implementation types with the `Connection.Do` + method instead of `Connection.` methods. +* The `connection_pool` package renamed to `pool`. + +The basic code for the `v1.12.2` release: +```Go +package tarantool + +import ( + "fmt" + + "github.com/tarantool/go-tarantool" +) + +func main() { + opts := tarantool.Opts{User: "guest"} + conn, err := tarantool.Connect("127.0.0.1:3301", opts) + if err != nil { + fmt.Println("Connection refused:", err) + return + } + + resp, err := conn.Insert(999, []interface{}{99999, "BB"}) + if err != nil { + fmt.Println("Error:", err) + fmt.Println("Code:", resp.Code) + } else { + fmt.Println("Data:", resp.Data) + } +} +``` + +At now became: +```Go +package tarantool + +import ( + "context" + "fmt" + "time" + + "github.com/tarantool/go-tarantool/v2" +) + +func main() { + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + dialer := tarantool.NetDialer{ + Address: "127.0.0.1:3301", + User: "guest", + } + opts := tarantool.Opts{ + Timeout: time.Second, + } + + conn, err := tarantool.Connect(ctx, dialer, opts) + if err != nil { + fmt.Println("Connection refused:", err) + return + } + + data, err := conn.Do( + tarantool.NewInsertRequest(999).Tuple([]interface{}{99999, "BB"})).Get() + if err != nil { + fmt.Println("Error:", err) + } else { + fmt.Println("Data:", data) + } +} +``` + +### Main package + +#### Go version + +Required Go version is updated from `1.13` to `1.20`. + +#### msgpack/v5 + +At now the `msgpack/v5` library is used for the `msgpack` encoding/decondig. + +Most function names and argument types in `msgpack/v5` and `msgpack.v2` +have not changed (in our code, we noticed changes in `EncodeInt`, `EncodeUint` +and `RegisterExt`). But there are a lot of changes in a logic of encoding and +decoding. On the plus side the migration seems easy, but on the minus side you +need to be very careful. + +First of all, `EncodeInt8`, `EncodeInt16`, `EncodeInt32`, `EncodeInt64` +and `EncodeUint*` analogues at `msgpack/v5` encode numbers as is without loss of +type. In `msgpack.v2` the type of a number is reduced to a value. + +Secondly, a base decoding function does not convert numbers to `int64` or +`uint64`. It converts numbers to an exact type defined by MessagePack. The +change makes manual type conversions much more difficult and can lead to +runtime errors with an old code. We do not recommend to use type conversions +and give preference to `*Typed` functions (besides, it's faster). + +There are also changes in the logic that can lead to errors in the old code, +[as example](https://github.com/vmihailenco/msgpack/issues/327). Although in +`msgpack/v5` some functions for the logic tuning were added (see +[UseLooseInterfaceDecoding](https://pkg.go.dev/github.com/vmihailenco/msgpack/v5#Decoder.UseLooseInterfaceDecoding), [UseCompactInts](https://pkg.go.dev/github.com/vmihailenco/msgpack/v5#Encoder.UseCompactInts) etc), it is still impossible +to achieve full compliance of behavior between `msgpack/v5` and `msgpack.v2`. +So we don't go this way. We use standard settings if it possible. + +#### Call = Call17 + +Call requests uses `IPROTO_CALL` instead of `IPROTO_CALL_16`. + +So now `Call` = `Call17` and `NewCallRequest` = `NewCall17Request`. A result +of the requests is an array instead of array of arrays. + +#### IPROTO constants + +* IPROTO constants have been moved to a separate package [go-iproto](https://github.com/tarantool/go-iproto). +* `PushCode` constant is removed. To check whether the current response is + a push response, use `IsPush()` method of the response iterator instead. +* `ErrorNo` constant is added to indicate that no error has occurred while + getting the response. It should be used instead of the removed `OkCode`. + See `ExampleErrorNo`. + +#### Request interface + +* The method `Code() uint32` replaced by the `Type() iproto.Type`. +* `Response` method added to the `Request` interface. + +#### Request changes + +* Requests `Update`, `UpdateAsync`, `UpdateTyped`, `Upsert`, `UpsertAsync` no +longer accept `ops` argument (operations) as an `interface{}`. `*Operations` +needs to be passed instead. +* `Op` struct for update operations made private. +* Removed `OpSplice` struct. +* `Operations.Splice` method now accepts 5 arguments instead of 3. +* `UpdateRequest` and `UpsertRequest` structs no longer accept `interface{}` +for an `ops` field. `*Operations` needs to be used instead. + +#### Response interface + +* `Response` is now an interface. +* Response header stored in a new `Header` struct. It could be accessed via + `Header()` method. + +#### Response changes + +* `ResponseIterator` interface now has `IsPush()` method. + It returns true if the current response is a push response. +* For each request type, a different response type is created. They all + implement a `Response` interface. `SelectResponse`, `PrepareResponse`, + `ExecuteResponse`, `PushResponse` are a part of a public API. + `Pos()`, `MetaData()`, `SQLInfo()` methods created for them to get specific + info. Special types of responses are used with special requests. + +#### Future type + +* Method `Get` now returns response data instead of the actual response. +* New method `GetResponse` added to get an actual response. +* `Future` constructors now accept `Request` as their argument. +* Methods `AppendPush` and `SetResponse` accepts response `Header` and data + as their arguments. +* Method `Err` was removed because it was causing improper error handling. + You need to check an error from `Get`, `GetTyped` or `GetResponse` with + an addition check of a value `Response.Header().Error`, see `ExampleErrorNo`. + +#### Connector interface + +* Operations `Ping`, `Select`, `Insert`, `Replace`, `Delete`, `Update`, + `Upsert`, `Call`, `Call16`, `Call17`, `Eval`, `Execute` of a `Connector` + return response data instead of an actual responses. +* New interface `Doer` is added as a child-interface instead of a `Do` method. + +#### Connect function + +`connection.Connect` no longer return non-working connection objects. This +function now does not attempt to reconnect and tries to establish a connection +only once. Function might be canceled via context. Context accepted as first +argument, and user may cancel it in process. + +Now you need to pass `Dialer` as the second argument instead of URI. +If you were using a non-SSL connection, you need to create `NetDialer`. +For SSL-enabled connections, use `OpenSSLDialer` from the +[go-tlsdialer](https://github.com/tarantool/go-tlsdialer) package. + +Please note that the options for creating a connection are now stored in +corresponding `Dialer`, not in `Opts`. + +#### Connection schema + +* Removed `Schema` field from the `Connection` struct. Instead, new + `GetSchema(Doer)` function was added to get the actual connection + schema on demand. +* `OverrideSchema(*Schema)` method replaced with the `SetSchema(Schema)`. + +#### Protocol types + +* `iproto.Feature` type used instead of `ProtocolFeature`. +* `iproto.IPROTO_FEATURE_` constants used instead of local ones. + +#### Schema type + +* `ResolveSpaceIndex` function for `SchemaResolver` interface split into two: +`ResolveSpace` and `ResolveIndex`. `NamesUseSupported` function added into the +interface to get information if the usage of space and index names in requests +is supported. +* `Schema` structure no longer implements `SchemaResolver` interface. +* `Spaces` and `SpacesById` fields of the `Schema` struct store spaces by value. +* `Fields` and `FieldsById` fields of the `Space` struct store fields by value. +`Index` and `IndexById` fields of the `Space` struct store indexes by value. +* `Fields` field of the `Index` struct store `IndexField` by value. + +### datetime package + +Now you need to use objects of the Datetime type instead of pointers to it. A +new constructor `MakeDatetime` returns an object. `NewDatetime` has been +removed. + +### decimal package + +Now you need to use objects of the Decimal type instead of pointers to it. A +new constructor `MakeDecimal` returns an object. `NewDecimal` has been removed. + +### multi package + +The subpackage has been deleted. You could use `pool` instead. + +### pool package + +* The `connection_pool` subpackage has been renamed to `pool`. +* The type `PoolOpts` has been renamed to `Opts`. +* `pool.Connect` and `pool.ConnectWithOpts` now accept context as the first + argument, which user may cancel in process. If it is canceled in progress, + an error will be returned and all created connections will be closed. +* `pool.Connect` and `pool.ConnectWithOpts` now accept `[]pool.Instance` as + the second argument instead of a list of addresses. Each instance is + associated with a unique string name, `Dialer` and connection options which + allows instances to be independently configured. +* `pool.Connect`, `pool.ConnectWithOpts` and `pool.Add` add instances into + the pool even it is unable to connect to it. The pool will try to connect to + the instance later. +* `pool.Add` now accepts context as the first argument, which user may cancel + in process. +* `pool.Add` now accepts `pool.Instance` as the second argument instead of + an address, it allows to configure a new instance more flexible. +* `pool.GetPoolInfo` has been renamed to `pool.GetInfo`. Return type has been + changed to `map[string]ConnectionInfo`. +* Operations `Ping`, `Select`, `Insert`, `Replace`, `Delete`, `Update`, `Upsert`, + `Call`, `Call16`, `Call17`, `Eval`, `Execute` of a `Pooler` return + response data instead of an actual responses. + +### crud package + +* `crud` operations `Timeout` option has `crud.OptFloat64` type + instead of `crud.OptUint`. +* A slice of a custom type could be used as tuples for `ReplaceManyRequest` and + `InsertManyRequest`, `ReplaceObjectManyRequest`. +* A slice of a custom type could be used as objects for `ReplaceObjectManyRequest` + and `InsertObjectManyRequest`. + +### test_helpers package + +* Renamed `StrangerResponse` to `MockResponse`. diff --git a/README.md b/README.md index b784b344..db0885fb 100644 --- a/README.md +++ b/README.md @@ -26,16 +26,8 @@ faster than other packages according to public benchmarks. * [Documentation](#documentation) * [API reference](#api-reference) * [Walking\-through example](#walking-through-example) - * [Migration to v2](#migration-to-v2) - * [datetime package](#datetime-package) - * [decimal package](#decimal-package) - * [multi package](#multi-package) - * [pool package](#pool-package) - * [crud package](#crud-package) - * [msgpack.v5](#msgpackv5) - * [Call = Call17](#call--call17) - * [IPROTO constants](#iproto-constants) - * [Request interface](#request-interface) + * [Example with encrypting traffic](#example-with-encrypting-traffic) +* [Migration guide](#migration-guide) * [Contributing](#contributing) * [Alternative connectors](#alternative-connectors) @@ -110,27 +102,28 @@ import ( ) func main() { - ctx, cancel := context.WithTimeout(context.Background(), - 500 * time.Millisecond) + ctx, cancel := context.WithTimeout(context.Background(), time.Second) defer cancel() - dialer := tarantool.NetDialer { + dialer := tarantool.NetDialer{ Address: "127.0.0.1:3301", User: "guest", } opts := tarantool.Opts{ Timeout: time.Second, } + conn, err := tarantool.Connect(ctx, dialer, opts) if err != nil { fmt.Println("Connection refused:", err) + return } - data, err := conn.Do(tarantool.NewInsertRequest(999). - Tuple([]interface{}{99999, "BB"}), - ).Get() + + data, err := conn.Do( + tarantool.NewInsertRequest(999).Tuple([]interface{}{99999, "BB"})).Get() if err != nil { - fmt.Println("Error", err) + fmt.Println("Error:", err) } else { - fmt.Printf("Data: %v", data) + fmt.Println("Data:", data) } } ``` @@ -138,15 +131,19 @@ func main() { **Observation 1:** The line "`github.com/tarantool/go-tarantool/v2`" in the `import(...)` section brings in all Tarantool-related functions and structures. -**Observation 2:** The line starting with "`dialer :=`" creates dialer for +**Observation 2:** The line starting with "`ctx, cancel :=`" creates a context +object for `Connect()`. The `Connect()` call will return an error when a +timeout expires before the connection is established. + +**Observation 3:** The line starting with "`dialer :=`" creates dialer for `Connect()`. This structure contains fields required to establish a connection. -**Observation 3:** The line starting with "`opts :=`" sets up the options for +**Observation 4:** The line starting with "`opts :=`" sets up the options for `Connect()`. In this example, the structure contains only a single value, the timeout. The structure may also contain other settings, see more in [documentation][godoc-opts-url] for the "`Opts`" structure. -**Observation 4:** The line containing "`tarantool.Connect`" is essential for +**Observation 5:** The line containing "`tarantool.Connect`" is essential for starting a session. There are three parameters: * a context, @@ -158,19 +155,19 @@ There will be only one attempt to connect. If multiple attempts needed, between each try. Example could be found in the [example_test](./example_test.go), name - `ExampleConnect_reconnects`. -**Observation 5:** The `err` structure will be `nil` if there is no error, +**Observation 6:** The `err` structure will be `nil` if there is no error, otherwise it will have a description which can be retrieved with `err.Error()`. -**Observation 6:** The `Insert` request, like almost all requests, is preceded +**Observation 7:** The `Insert` request, like almost all requests, is preceded by the method `Do` of object `conn` which is the object that was returned by `Connect()`. ### Example with encrypting traffic -For SSL-enabled connections, use `OpenSSLDialer` from the [`go-tlsdialer`](https://github.com/tarantool/go-tlsdialer) -package. +For SSL-enabled connections, use `OpenSSLDialer` from the +[go-tlsdialer](https://github.com/tarantool/go-tlsdialer) package. -Here is small example with importing `go-tlsdialer` and using the +Here is small example with importing the `go-tlsdialer` library and using the `OpenSSLDialer`: ```go @@ -186,7 +183,9 @@ import ( ) func main() { - sslDialer := tlsdialer.OpenSSLDialer{ + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + dialer := tlsdialer.OpenSSLDialer{ Address: "127.0.0.1:3013", User: "test", Password: "test", @@ -198,20 +197,18 @@ func main() { Timeout: time.Second, } - ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond) - defer cancel() - conn, err := tarantool.Connect(ctx, sslDialer, opts) + conn, err := tarantool.Connect(ctx, dialer, opts) if err != nil { - fmt.Printf("Connection refused: %s", err) + fmt.Println("Connection refused:", err) + return } - data, err := conn.Do(tarantool.NewInsertRequest(999). - Tuple([]interface{}{99999, "BB"}), - ).Get() + data, err := conn.Do( + tarantool.NewInsertRequest(999).Tuple([]interface{}{99999, "BB"})).Get() if err != nil { - fmt.Printf("Error: %s", err) + fmt.Println("Error:", err) } else { - fmt.Printf("Data: %v", data) + fmt.Println("Data:", data) } } ``` @@ -219,187 +216,10 @@ func main() { Note that [traffic encryption](https://www.tarantool.io/en/doc/latest/enterprise/security/#encrypting-traffic) is only available in Tarantool Enterprise Edition 2.10 or newer. -### Migration to v2 - -The article describes migration from go-tarantool to go-tarantool/v2. - -#### Go version - -Required Go version is set to `1.20`. - -#### datetime package - -Now you need to use objects of the Datetime type instead of pointers to it. A -new constructor `MakeDatetime` returns an object. `NewDatetime` has been -removed. - -#### decimal package - -Now you need to use objects of the Decimal type instead of pointers to it. A -new constructor `MakeDecimal` returns an object. `NewDecimal` has been removed. - -#### multi package - -The subpackage has been deleted. You could use `pool` instead. - -#### pool package - -* The `connection_pool` subpackage has been renamed to `pool`. -* The type `PoolOpts` has been renamed to `Opts`. -* `pool.Connect` and `pool.ConnectWithOpts` now accept context as the first - argument, which user may cancel in process. If it is canceled in progress, - an error will be returned and all created connections will be closed. -* `pool.Connect` and `pool.ConnectWithOpts` now accept `[]pool.Instance` as - the second argument instead of a list of addresses. Each instance is - associated with a unique string name, `Dialer` and connection options which - allows instances to be independently configured. -* `pool.Connect`, `pool.ConnectWithOpts` and `pool.Add` add instances into - the pool even it is unable to connect to it. The pool will try to connect to - the instance later. -* `pool.Add` now accepts context as the first argument, which user may cancel - in process. -* `pool.Add` now accepts `pool.Instance` as the second argument instead of - an address, it allows to configure a new instance more flexible. -* `pool.GetPoolInfo` has been renamed to `pool.GetInfo`. Return type has been - changed to `map[string]ConnectionInfo`. -* Operations `Ping`, `Select`, `Insert`, `Replace`, `Delete`, `Update`, `Upsert`, - `Call`, `Call16`, `Call17`, `Eval`, `Execute` of a `Pooler` return - response data instead of an actual responses. - -#### crud package - -* `crud` operations `Timeout` option has `crud.OptFloat64` type - instead of `crud.OptUint`. -* A slice of a custom type could be used as tuples for `ReplaceManyRequest` and - `InsertManyRequest`, `ReplaceObjectManyRequest`. -* A slice of a custom type could be used as objects for `ReplaceObjectManyRequest` - and `InsertObjectManyRequest`. - -#### test_helpers package - -Renamed `StrangerResponse` to `MockResponse`. - -#### msgpack.v5 - -Most function names and argument types in `msgpack.v5` and `msgpack.v2` -have not changed (in our code, we noticed changes in `EncodeInt`, `EncodeUint` -and `RegisterExt`). But there are a lot of changes in a logic of encoding and -decoding. On the plus side the migration seems easy, but on the minus side you -need to be very careful. - -First of all, `EncodeInt8`, `EncodeInt16`, `EncodeInt32`, `EncodeInt64` -and `EncodeUint*` analogues at `msgpack.v5` encode numbers as is without loss of -type. In `msgpack.v2` the type of a number is reduced to a value. +## Migration guide -Secondly, a base decoding function does not convert numbers to `int64` or -`uint64`. It converts numbers to an exact type defined by MessagePack. The -change makes manual type conversions much more difficult and can lead to -runtime errors with an old code. We do not recommend to use type conversions -and give preference to `*Typed` functions (besides, it's faster). - -There are also changes in the logic that can lead to errors in the old code, -[as example](https://github.com/vmihailenco/msgpack/issues/327). Although in -`msgpack.v5` some functions for the logic tuning were added (see -[UseLooseInterfaceDecoding](https://pkg.go.dev/github.com/vmihailenco/msgpack/v5#Decoder.UseLooseInterfaceDecoding), [UseCompactInts](https://pkg.go.dev/github.com/vmihailenco/msgpack/v5#Encoder.UseCompactInts) etc), it is still impossible -to achieve full compliance of behavior between `msgpack.v5` and `msgpack.v2`. So -we don't go this way. We use standard settings if it possible. - -#### Call = Call17 - -Call requests uses `IPROTO_CALL` instead of `IPROTO_CALL_16`. - -So now `Call` = `Call17` and `NewCallRequest` = `NewCall17Request`. A result -of the requests is an array instead of array of arrays. - -#### IPROTO constants - -* IPROTO constants have been moved to a separate package [go-iproto](https://github.com/tarantool/go-iproto). -* `PushCode` constant is removed. To check whether the current response is - a push response, use `IsPush()` method of the response iterator instead. -* `ErrorNo` constant is added to indicate that no error has occurred while - getting the response. It should be used instead of the removed `OkCode`. - -#### Request changes - -* The method `Code() uint32` replaced by the `Type() iproto.Type`. -* `Op` struct for update operations made private. -* Removed `OpSplice` struct. -* `Operations.Splice` method now accepts 5 arguments instead of 3. -* Requests `Update`, `UpdateAsync`, `UpdateTyped`, `Upsert`, `UpsertAsync` no -longer accept `ops` argument (operations) as an `interface{}`. `*Operations` -needs to be passed instead. -* `UpdateRequest` and `UpsertRequest` structs no longer accept `interface{}` -for an `ops` field. `*Operations` needs to be used instead. -* `Response` method added to the `Request` interface. - -#### Response changes - -* `Response` is now an interface. -* Response header stored in a new `Header` struct. It could be accessed via - `Header()` method. -* `ResponseIterator` interface now has `IsPush()` method. - It returns true if the current response is a push response. -* For each request type, a different response type is created. They all - implement a `Response` interface. `SelectResponse`, `PrepareResponse`, - `ExecuteResponse`, `PushResponse` are a part of a public API. - `Pos()`, `MetaData()`, `SQLInfo()` methods created for them to get specific info. - Special types of responses are used with special requests. - -#### Future changes - -* Method `Get` now returns response data instead of the actual response. -* New method `GetResponse` added to get an actual response. -* `Future` constructors now accept `Request` as their argument. -* Methods `AppendPush` and `SetResponse` accepts response `Header` and data - as their arguments. -* Method `Err` was removed because it was causing improper error handling. You - You need to check an error from `Get`, `GetTyped` or `GetResponse` with - an addition check of a value `Response.Header().Error`, see `ExampleErrorNo`. - -#### Connector changes - -* Operations `Ping`, `Select`, `Insert`, `Replace`, `Delete`, `Update`, `Upsert`, - `Call`, `Call16`, `Call17`, `Eval`, `Execute` of a `Connector` return - response data instead of an actual responses. -* New interface `Doer` is added as a child-interface instead of a `Do` method. - -#### Connect function - -`connection.Connect` no longer return non-working connection objects. This function -now does not attempt to reconnect and tries to establish a connection only once. -Function might be canceled via context. Context accepted as first argument, -and user may cancel it in process. - -Now you need to pass `Dialer` as the second argument instead of URI. -If you were using a non-SSL connection, you need to create `NetDialer`. -For SSL-enabled connections, use `OpenSSLDialer` from the `go-tlsdialer` -package. -Please note that the options for creating a connection are now stored in -corresponding `Dialer`, not in `Opts`. - -#### Connection schema - -* Removed `Schema` field from the `Connection` struct. Instead, new - `GetSchema(Doer)` function was added to get the actual connection - schema on demand. -* `OverrideSchema(*Schema)` method replaced with the `SetSchema(Schema)`. - -#### Protocol changes - -* `iproto.Feature` type used instead of `ProtocolFeature`. -* `iproto.IPROTO_FEATURE_` constants used instead of local ones. - -#### Schema changes - -* `ResolveSpaceIndex` function for `SchemaResolver` interface split into two: -`ResolveSpace` and `ResolveIndex`. `NamesUseSupported` function added into the -interface to get information if the usage of space and index names in requests -is supported. -* `Schema` structure no longer implements `SchemaResolver` interface. -* `Spaces` and `SpacesById` fields of the `Schema` struct store spaces by value. -* `Fields` and `FieldsById` fields of the `Space` struct store fields by value. -`Index` and `IndexById` fields of the `Space` struct store indexes by value. -* `Fields` field of the `Index` struct store `IndexField` by value. +You can review the changes between major versions in the +[migration guide](./MIGRATION.md). ## Contributing From e7fbc2b7b60b3a106d5e02c883a2fa7ce7d7ded9 Mon Sep 17 00:00:00 2001 From: Oleg Jukovec Date: Sun, 11 Feb 2024 20:02:50 +0300 Subject: [PATCH 2/4] doc: add external types imports to main examples Closes #352 --- MIGRATION.md | 6 ++++++ README.md | 21 +++++++++++++++------ 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 1f07639a..fdd4893d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -50,6 +50,9 @@ import ( "fmt" "github.com/tarantool/go-tarantool" + _ "github.com/tarantool/go-tarantool/v2/datetime" + _ "github.com/tarantool/go-tarantool/v2/decimal" + _ "github.com/tarantool/go-tarantool/v2/uuid" ) func main() { @@ -80,6 +83,9 @@ import ( "time" "github.com/tarantool/go-tarantool/v2" + _ "github.com/tarantool/go-tarantool/v2/datetime" + _ "github.com/tarantool/go-tarantool/v2/decimal" + _ "github.com/tarantool/go-tarantool/v2/uuid" ) func main() { diff --git a/README.md b/README.md index db0885fb..71f52671 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,9 @@ import ( "time" "github.com/tarantool/go-tarantool/v2" + _ "github.com/tarantool/go-tarantool/v2/datetime" + _ "github.com/tarantool/go-tarantool/v2/decimal" + _ "github.com/tarantool/go-tarantool/v2/uuid" ) func main() { @@ -131,19 +134,22 @@ func main() { **Observation 1:** The line "`github.com/tarantool/go-tarantool/v2`" in the `import(...)` section brings in all Tarantool-related functions and structures. -**Observation 2:** The line starting with "`ctx, cancel :=`" creates a context +**Observation 2:** Unused import lines are required to initialize encoders and +decoders for external `msgpack` types. + +**Observation 3:** The line starting with "`ctx, cancel :=`" creates a context object for `Connect()`. The `Connect()` call will return an error when a timeout expires before the connection is established. -**Observation 3:** The line starting with "`dialer :=`" creates dialer for +**Observation 4:** The line starting with "`dialer :=`" creates dialer for `Connect()`. This structure contains fields required to establish a connection. -**Observation 4:** The line starting with "`opts :=`" sets up the options for +**Observation 5:** The line starting with "`opts :=`" sets up the options for `Connect()`. In this example, the structure contains only a single value, the timeout. The structure may also contain other settings, see more in [documentation][godoc-opts-url] for the "`Opts`" structure. -**Observation 5:** The line containing "`tarantool.Connect`" is essential for +**Observation 6:** The line containing "`tarantool.Connect`" is essential for starting a session. There are three parameters: * a context, @@ -155,10 +161,10 @@ There will be only one attempt to connect. If multiple attempts needed, between each try. Example could be found in the [example_test](./example_test.go), name - `ExampleConnect_reconnects`. -**Observation 6:** The `err` structure will be `nil` if there is no error, +**Observation 7:** The `err` structure will be `nil` if there is no error, otherwise it will have a description which can be retrieved with `err.Error()`. -**Observation 7:** The `Insert` request, like almost all requests, is preceded +**Observation 8:** The `Insert` request, like almost all requests, is preceded by the method `Do` of object `conn` which is the object that was returned by `Connect()`. @@ -179,6 +185,9 @@ import ( "time" "github.com/tarantool/go-tarantool/v2" + _ "github.com/tarantool/go-tarantool/v2/datetime" + _ "github.com/tarantool/go-tarantool/v2/decimal" + _ "github.com/tarantool/go-tarantool/v2/uuid" "github.com/tarantool/go-tlsdialer" ) From 35df250621f187eaf26dc060fb78c290b3dcb1f9 Mon Sep 17 00:00:00 2001 From: Oleg Jukovec Date: Sun, 11 Feb 2024 21:49:26 +0300 Subject: [PATCH 3/4] doc: update pkg.go.dev links --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 71f52671..f5c53339 100644 --- a/README.md +++ b/README.md @@ -245,8 +245,8 @@ There are two other connectors available from the open source community: See feature comparison in the [documentation][tarantool-doc-connectors-comparison]. [tarantool-site]: https://tarantool.io/ -[godoc-badge]: https://pkg.go.dev/badge/github.com/tarantool/go-tarantool.svg -[godoc-url]: https://pkg.go.dev/github.com/tarantool/go-tarantool +[godoc-badge]: https://pkg.go.dev/badge/github.com/tarantool/go-tarantool/v2.svg +[godoc-url]: https://pkg.go.dev/github.com/tarantool/go-tarantool/v2 [actions-badge]: https://github.com/tarantool/go-tarantool/actions/workflows/testing.yml/badge.svg [actions-url]: https://github.com/tarantool/go-tarantool/actions/workflows/testing.yml [coverage-badge]: https://coveralls.io/repos/github/tarantool/go-tarantool/badge.svg?branch=master @@ -261,5 +261,5 @@ See feature comparison in the [documentation][tarantool-doc-connectors-compariso [go-tarantool]: https://github.com/tarantool/go-tarantool [tarantool-doc-data-model-url]: https://www.tarantool.io/en/doc/latest/book/box/data_model/ [tarantool-doc-box-space-url]: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/ -[godoc-opts-url]: https://pkg.go.dev/github.com/tarantool/go-tarantool#Opts +[godoc-opts-url]: https://pkg.go.dev/github.com/tarantool/go-tarantool/v2#Opts [tarantool-doc-connectors-comparison]: https://www.tarantool.io/en/doc/latest/book/connectors/#go-feature-comparison From abcc5ac46842e0cbcb96f5a8da4bfeb600d46fa8 Mon Sep 17 00:00:00 2001 From: Oleg Jukovec Date: Sun, 11 Feb 2024 20:12:28 +0300 Subject: [PATCH 4/4] Release 2.0.0 Overview There are a lot of changes in the new major version. The main ones: * The `go_tarantool_call_17` build tag is no longer needed, since by default the `CallRequest` is `Call17Request`. * The `go_tarantool_msgpack_v5` build tag is no longer needed, since only the `msgpack/v5` library is used. * The `go_tarantool_ssl_disable` build tag is no longer needed, since the connector is no longer depends on `OpenSSL` by default. You could use the external library go-tlsdialer[1] to create a connection with the `ssl` transport. * Required Go version is `1.20` now. * The `Connect` function became more flexible. It now allows to create a connection with cancellation and a custom `Dialer` implementation. * It is required to use `Request` implementation types with the `Connection.Do` method instead of `Connection.` methods. * The `connection_pool` package renamed to `pool`. See the migration guide[2] for more details. Breaking changes connection_pool renamed to pool (#239). Use msgpack/v5 instead of msgpack.v2 (#236). Call/NewCallRequest = Call17/NewCall17Request (#235). Change encoding of the queue.Identify() UUID argument from binary blob to plain string. Needed for upgrade to Tarantool 3.0, where a binary blob is decoded to a varbinary object (#313). Use objects of the Decimal type instead of pointers (#238). Use objects of the Datetime type instead of pointers (#238). `connection.Connect` no longer return non-working connection objects (#136). This function now does not attempt to reconnect and tries to establish a connection only once. Function might be canceled via context. Context accepted as first argument. `pool.Connect` and `pool.Add` now accept context as the first argument, which user may cancel in process. If `pool.Connect` is canceled in progress, an error will be returned. All created connections will be closed. `iproto.Feature` type now used instead of `ProtocolFeature` (#337). `iproto.IPROTO_FEATURE_` constants now used instead of local `Feature` constants for `protocol` (#337). Change `crud` operations `Timeout` option type to `crud.OptFloat64` instead of `crud.OptUint` (#342). Change all `Upsert` and `Update` requests to accept `*tarantool.Operations` as `ops` parameters instead of `interface{}` (#348). Change `OverrideSchema(*Schema)` to `SetSchema(Schema)` (#7). Change values, stored by pointers in the `Schema`, `Space`, `Index` structs, to be stored by their values (#7). Make `Dialer` mandatory for creation a single connection (#321). Remove `Connection.RemoteAddr()`, `Connection.LocalAddr()`. Add `Addr()` function instead (#321). Remove `Connection.ClientProtocolInfo`, `Connection.ServerProtocolInfo`. Add `ProtocolInfo()` function instead, which returns the server protocol info (#321). `NewWatcher` checks the actual features of the server, rather than relying on the features provided by the user during connection creation (#321). `pool.NewWatcher` does not create watchers for connections that do not support it (#321). Rename `pool.GetPoolInfo` to `pool.GetInfo`. Change return type to `map[string]ConnectionInfo` (#321). `Response` is now an interface (#237). All responses are now implementations of the `Response` interface (#237). `SelectResponse`, `ExecuteResponse`, `PrepareResponse`, `PushResponse` are part of a public API. `Pos()`, `MetaData()`, `SQLInfo()` methods created for them to get specific info. Special types of responses are used with special requests. `IsPush()` method is added to the response iterator (#237). It returns the information if the current response is a `PushResponse`. `PushCode` constant is removed. Method `Get` for `Future` now returns response data (#237). To get the actual response new `GetResponse` method has been added. Methods `AppendPush` and `SetResponse` accept response `Header` and data as their arguments. `Future` constructors now accept `Request` as their argument (#237). Operations `Ping`, `Select`, `Insert`, `Replace`, `Delete`, `Update`, `Upsert`, `Call`, `Call16`, `Call17`, `Eval`, `Execute` of a `Connector` and `Pooler` return response data instead of an actual responses (#237). `pool.Connect`, `pool.ConnetcWithOpts` and `pool.Add` use a new type `pool.Instance` to determinate connection options (#356). `pool.Connect`, `pool.ConnectWithOpts` and `pool.Add` add connections to the pool even it is unable to connect to it (#372). Required Go version from `1.13` to `1.20` (#378). multi subpackage is removed (#240). msgpack.v2 support is removed (#236). pool/RoundRobinStrategy is removed (#158). DeadlineIO is removed (#158). UUID_extId is removed (#158). IPROTO constants are removed (#158). Code() method from the Request interface is removed (#158). `Schema` field from the `Connection` struct is removed (#7). `OkCode` and `PushCode` constants is removed (#237). SSL support is removed (#301). `Future.Err()` method is removed (#382). New features Type() method to the Request interface (#158). Enumeration types for RLimitAction/iterators (#158). IsNullable flag for Field (#302). Meaningful description for read/write socket errors (#129). Support `operation_data` in `crud.Error` (#330). Support `fetch_latest_metadata` option for crud requests with metadata (#335). Support `noreturn` option for data change crud requests (#335). Support `crud.schema` request (#336, #351). Support `IPROTO_WATCH_ONCE` request type for Tarantool version >= 3.0.0-alpha1 (#337). Support `yield_every` option for crud select requests (#350). Support `IPROTO_FEATURE_SPACE_AND_INDEX_NAMES` for Tarantool version >= 3.0.0-alpha1 (#338). It allows to use space and index names in requests instead of their IDs. `GetSchema` function to get the actual schema (#7). Support connection via an existing socket fd (#321). `Header` struct for the response header (#237). It can be accessed via `Header()` method of the `Response` interface. `Response` method added to the `Request` interface (#237). New `LogAppendPushFailed` connection log constant (#237). It is logged when connection fails to append a push response. `ErrorNo` constant that indicates that no error has occurred while getting the response (#237). `AuthDialer` type for creating a dialer with authentication (#301). `ProtocolDialer` type for creating a dialer with `ProtocolInfo` receiving and check (#301). `GreetingDialer` type for creating a dialer, that fills `Greeting` of a connection (#301). New method `Pool.DoInstance` to execute a request on a target instance in a pool (#376). Bugfixes Race condition at roundRobinStrategy.GetNextConnection() (#309). Incorrect decoding of an MP_DECIMAL when the `scale` value is negative (#314). Incorrect options (`after`, `batch_size` and `force_map_call`) setup for crud.SelectRequest (#320). Incorrect options (`vshard_router`, `fields`, `bucket_id`, `mode`, `prefer_replica`, `balance`) setup for crud.GetRequest (#335). Splice update operation accepts 3 arguments instead of 5 (#348). Unable to use a slice of custom types as a slice of tuples or objects for `crud.*ManyRequest/crud.*ObjectManyRequest` (#365). Testing More linters on CI (#310). Added an ability to mock connections for tests (#237). Added new types `MockDoer`, `MockRequest` to `test_helpers`. Fixed flaky decimal/TestSelect (#300). Fixed tests with crud 1.4.0 (#336). Fixed tests with case sensitive SQL (#341). Renamed `StrangerResponse` to `MockResponse` (#237). Other All Connection., Connection.Typed and Connection.Async methods are now deprecated. Instead you should use requests objects + Connection.Do() (#241). All ConnectionPool., ConnectionPool.Typed and ConnectionPool.Async methods are now deprecated. Instead you should use requests objects + ConnectionPool.Do() (#241). box.session.push() usage is deprecated: Future.AppendPush() and Future.GetIterator() methods, ResponseIterator and TimeoutResponseIterator types (#324). 1. https://github.com/tarantool/go-tlsdialer 2. https://github.com/tarantool/go-tarantool/blob/master/MIGRATION.md --- CHANGELOG.md | 51 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b964384..30aa750f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,20 +10,47 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release. ### Added +### Changed + +### Fixed + +## [2.0.0] - 2024-02-12 + +There are a lot of changes in the new major version. The main ones: + +* The `go_tarantool_call_17` build tag is no longer needed, since by default + the `CallRequest` is `Call17Request`. +* The `go_tarantool_msgpack_v5` build tag is no longer needed, since only the + `msgpack/v5` library is used. +* The `go_tarantool_ssl_disable` build tag is no longer needed, since the + connector is no longer depends on `OpenSSL` by default. You could use the + external library [go-tlsdialer](https://github.com/tarantool/go-tlsdialer) to + create a connection with the `ssl` transport. +* Required Go version is `1.20` now. +* The `Connect` function became more flexible. It now allows to create a + connection with cancellation and a custom `Dialer` implementation. +* It is required to use `Request` implementation types with the `Connection.Do` + method instead of `Connection.` methods. +* The `connection_pool` package renamed to `pool`. + +See the [migration guide](./MIGRATION.md) for more details. + +### Added + - Type() method to the Request interface (#158) - Enumeration types for RLimitAction/iterators (#158) - IsNullable flag for Field (#302) - More linters on CI (#310) - Meaningful description for read/write socket errors (#129) -- Support `operation_data` in `crud.Error` (#330) +- Support `operation_data` in `crud.Error` (#330) - Support `fetch_latest_metadata` option for crud requests with metadata (#335) - Support `noreturn` option for data change crud requests (#335) - Support `crud.schema` request (#336, #351) -- Support `IPROTO_WATCH_ONCE` request type for Tarantool +- Support `IPROTO_WATCH_ONCE` request type for Tarantool version >= 3.0.0-alpha1 (#337) - Support `yield_every` option for crud select requests (#350) - Support `IPROTO_FEATURE_SPACE_AND_INDEX_NAMES` for Tarantool - version >= 3.0.0-alpha1 (#338). It allows to use space and index names + version >= 3.0.0-alpha1 (#338). It allows to use space and index names in requests instead of their IDs. - `GetSchema` function to get the actual schema (#7) - Support connection via an existing socket fd (#321) @@ -37,12 +64,12 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release. - Ability to mock connections for tests (#237). Added new types `MockDoer`, `MockRequest` to `test_helpers`. - `AuthDialer` type for creating a dialer with authentication (#301) -- `ProtocolDialer` type for creating a dialer with `ProtocolInfo` receiving and +- `ProtocolDialer` type for creating a dialer with `ProtocolInfo` receiving and check (#301) - `GreetingDialer` type for creating a dialer, that fills `Greeting` of a connection (#301) - New method `Pool.DoInstance` to execute a request on a target instance in - a pool (#376). + a pool (#376) ### Changed @@ -54,22 +81,22 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release. decoded to a varbinary object (#313). - Use objects of the Decimal type instead of pointers (#238) - Use objects of the Datetime type instead of pointers (#238) -- `connection.Connect` no longer return non-working - connection objects (#136). This function now does not attempt to reconnect - and tries to establish a connection only once. Function might be canceled +- `connection.Connect` no longer return non-working + connection objects (#136). This function now does not attempt to reconnect + and tries to establish a connection only once. Function might be canceled via context. Context accepted as first argument. `pool.Connect` and `pool.Add` now accept context as the first argument, which user may cancel in process. If `pool.Connect` is canceled in progress, an error will be returned. All created connections will be closed. - `iproto.Feature` type now used instead of `ProtocolFeature` (#337) -- `iproto.IPROTO_FEATURE_` constants now used instead of local `Feature` +- `iproto.IPROTO_FEATURE_` constants now used instead of local `Feature` constants for `protocol` (#337) - Change `crud` operations `Timeout` option type to `crud.OptFloat64` instead of `crud.OptUint` (#342) -- Change all `Upsert` and `Update` requests to accept `*tarantool.Operations` +- Change all `Upsert` and `Update` requests to accept `*tarantool.Operations` as `ops` parameters instead of `interface{}` (#348) - Change `OverrideSchema(*Schema)` to `SetSchema(Schema)` (#7) -- Change values, stored by pointers in the `Schema`, `Space`, `Index` structs, +- Change values, stored by pointers in the `Schema`, `Space`, `Index` structs, to be stored by their values (#7) - Make `Dialer` mandatory for creation a single connection (#321) - Remove `Connection.RemoteAddr()`, `Connection.LocalAddr()`. @@ -103,7 +130,7 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release. `pool.Instance` to determinate connection options (#356) - `pool.Connect`, `pool.ConnectWithOpts` and `pool.Add` add connections to the pool even it is unable to connect to it (#372) -- Required Go version from `1.11` to `1.20` (#378) +- Required Go version updated from `1.13` to `1.20` (#378) ### Deprecated