Repository: calcite-avatica-go Updated Branches: refs/heads/master c7a5668af -> b697c2150
Update readme and move documentation into website markdown documents Project: http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/repo Commit: http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/commit/bb7b70cb Tree: http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/tree/bb7b70cb Diff: http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/diff/bb7b70cb Branch: refs/heads/master Commit: bb7b70cb7dfa6002d0bbe94c468c469b3ae40f48 Parents: c7a5668 Author: Francis Chuang <francis.chu...@boostport.com> Authored: Fri Aug 11 21:35:32 2017 +1000 Committer: Francis Chuang <francischu...@apache.org> Committed: Tue Apr 17 11:25:22 2018 +1000 ---------------------------------------------------------------------- README.md | 150 ++-------------------------- site/README.md | 31 ++++++ site/go_client_reference.md | 206 +++++++++++++++++++++++++++++++++++++++ site/go_history.md | 56 +++++++++++ 4 files changed, 299 insertions(+), 144 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/blob/bb7b70cb/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 7a42090..eb6d0e5 100644 --- a/README.md +++ b/README.md @@ -18,153 +18,15 @@ limitations under the License. --> # Apache Avatica/Phoenix SQL Driver +======= [![GoDoc](https://godoc.org/github.com/apache/calcite-avatica-go?status.png)](https://godoc.org/github.com/apache/calcite-avatica-go) [![Build Status](https://travis-ci.org/apache/calcite-avatica-go.svg?branch=master)](https://travis-ci.org/apache/calcite-avatica-go) -An Apache Avatica/Phoenix driver for Go's [database/sql](http://golang.org/pkg/database/sql) package +Apache Calcite's Avatica Go is a Go [database/sql](https://golang.org/pkg/database/sql/) driver for the Avatica server. -## Getting started -Install using your dependency management tool (we recommend [dep](https://github.com/golang/dep)!): +Avatica is a sub-project of [Apache Calcite](https://calcite.apache.org). -``` -$ dep ensure -add github.com/apache/calcite-avatica-go -``` +For more details, see the [home page](https://calcite.apache.org/avatica/go_client_reference.html). -## Usage - -The Phoenix/Avatica driver implements Go's `database/sql/driver` interface, so, import Go's -`database/sql` package and the driver: - -``` -import "database/sql" -import _ "github.com/apache/calcite-avatica-go" - -db, err := sql.Open("avatica", "http://localhost:8765") -``` - -Then simply use the database connection to query some data, for example: - -``` -rows := db.Query("SELECT COUNT(*) FROM test") -``` - -### DSN (Data Source Name) - -The DSN has the following format (optional parts are marked by square brackets): - -``` -http://[username:password@]address:port[/schema][?parameter1=value&...parameterN=value] -``` - -In other words, the scheme (http), address and port is mandatory, but the schema and parameters are optional. - -#### username -This is the JDBC username that is passed directly to the backing database. It is *NOT* used for authenticating -against Avatica. - -#### password -This is the JDBC password that is passed directly to the backing database. It is *NOT* used for authenticating -against Avatica. - -#### schema -The `schema` path sets the default schema to use for this connection. For example, if you set it to `myschema`, -then executing the query `SELECT * FROM my_table` will have the equivalence of `SELECT * FROM myschema.my_table`. -If schema is set, you can still work on tables in other schemas by supplying a schema prefix: -`SELECT * FROM myotherschema.my_other_table`. - -The following parameters are supported: - -#### authentication -The authentication type to use when authenticating against Avatica. Valid values are `BASIC` for HTTP Basic authentication, -`DIGEST` for HTTP Digest authentication, and `SPNEGO` for Kerberos with SPNEGO authentication. - -#### avaticaUser -The user to use when authenticating against Avatica. This parameter is required if `authentication` is `BASIC` or `DIGEST`. - -#### avaticaPassword -The password to use when authenticating against Avatica. This parameter is required if `authentication` is `BASIC` or `DIGEST`. - -#### principal -The Kerberos principal to use when authenticating against Avatica. It should be in the form `primary/instance@realm`, where -the instance is optional. This parameter is required if `authentication` is `SPNEGO` and you want the driver to perform the -Kerberos login. - -#### keytab -The path to the Kerberos keytab to use when authenticating against Avatica. This parameter is required if `authentication` -is `SPNEGO` and you want the driver to perform the Kerberos login. - -#### krb5Conf -The path to the Kerberos configuration to use when authenticating against Avatica. This parameter is required if `authentication` -is `SPNEGO` and you want the driver to perform the Kerberos login. - -#### krb5CredentialsCache -The path to the Kerberos credential cache file to use when authenticating against Avatica. This parameter is required if -`authentication` is `SPNEGO` and you have logged into Kerberos already and want the driver to use the existing credentials. - -#### location - -The `location` will be set as the location of unserialized `time.Time` values. It must be a valid timezone. -If you want to use the local timezone, use `Local`. By default, this is set to `UTC`. - -#### maxRowsTotal - -The `maxRowsTotal` parameter sets the maximum number of rows to return for a given query. By default, this is set to -`-1`, so that there is no limit on the number of rows returned. - -#### frameMaxSize - -The `frameMaxSize` parameter sets the maximum number of rows to return in a frame. Depending on the number of rows -returned and subject to the limits of `maxRowsTotal`, a query result set can contain rows in multiple frames. These -additional frames are then fetched on a as-needed basis. `frameMaxSize` allows you to control the number of rows -in each frame to suit your application's performance profile. By default this is set to `-1`, so that there is no limit -on the number of rows in a frame. - -#### transactionIsolation - -Setting `transactionIsolation` allows you to set the isolation level for transactions using the connection. The value -should be a positive integer analogous to the transaction levels defined by the JDBC specification. The default value -is `0`, which means transactions are not supported. This is to deal with the fact that Calcite/Avatica works with -many types of backends, with some backends having no transaction support. If you are using Apache Phoenix 4.7 onwards, -we recommend setting it to `4`, which is the maximum isolation level supported. - -The supported values for `transactionIsolation` are: - -| Value | JDBC Constant | Description | -| ----- | ------------------------------ | -------------------------------------------------------------------------------- | -| 0 | none | Transactions are not supported | -| 1 | `TRANSACTION_READ_UNCOMMITTED` | Dirty reads, non-repeatable reads and phantom reads may occur. | -| 2 | `TRANSACTION_READ_COMMITTED` | Dirty reads are prevented, but non-repeatable reads and phantom reads may occur. | -| 4 | `TRANSACTION_REPEATABLE_READ` | Dirty reads and non-repeatable reads are prevented, but phantom reads may occur. | -| 8 | `TRANSACTION_SERIALIZABLE` | Dirty reads, non-repeatable reads, and phantom reads are all prevented. | - -### time.Time support - -The following Phoenix/Avatica datatypes are automatically converted to and from `time.Time`: -`TIME`, `DATE` and `TIMESTAMP`. - -It is important to understand that avatica and the underlying database ignores the timezone. If you save a `time.Time` -to the database, the timezone is ignored and vice-versa. This is why you need to make sure the `location` parameter -in your DSN is set to the same value as the location of the `time.Time` values you are inserting into the database. - -We recommend using `UTC`, which is the default value of `location`. - -## Version compatibility -| Driver Version | Phoenix Version | Calcite-Avatica Version | -| --------------- | ----------------- | ----------------------- | -| 1.x.x | >= 4.8.0 | >= 1.8.0 | -| 2.x.x | >= 4.8.0 | >= 1.8.0 | - -## Development - -To run tests, but skip tests in the vendor directory (to avoid running tests for the dependencies), run: - -``` -go test -v ./... -``` - -#### Updating protocol buffer definitions -To update the procotol buffer definitions, update `CALCITE_VER` in `gen-protobuf.bat` and `gen-protobuf.sh` to match -the version included by Phoenix and then run the appropriate script for your platform. - -## License -The driver is licensed under the Apache 2 license. See the [LICENSE](LICENSE.md) and [NOTICE](NOTICE.md) files for more information. \ No newline at end of file +Release notes for all published versions are available on the [history +page](https://calcite.apache.org/avatica/docs/go_history.html). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/blob/bb7b70cb/site/README.md ---------------------------------------------------------------------- diff --git a/site/README.md b/site/README.md new file mode 100644 index 0000000..72f7dc9 --- /dev/null +++ b/site/README.md @@ -0,0 +1,31 @@ +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +# Apache Calcite Avatica Go site + +This directory contains the code for the web pages documenting the Calcite Avatica Go client. + +It is symlinked and built by the [Avatica web site](https://calcite.apache.org/avatica), +a sub-directory of the +[Apache Calcite web site](https://calcite.apache.org). + +## Pushing to site + +The web pages are symlinked by the Apache Calcite Avatica project and pushes should be done from the +Apache Calcite Avatica repository. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/blob/bb7b70cb/site/go_client_reference.md ---------------------------------------------------------------------- diff --git a/site/go_client_reference.md b/site/go_client_reference.md new file mode 100644 index 0000000..fa875b3 --- /dev/null +++ b/site/go_client_reference.md @@ -0,0 +1,206 @@ +--- +layout: docs +title: Go Client Reference +sidebar_title: Go Client Reference +permalink: /docs/go_client_reference.html +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +The Avatica Go client is an Avatica driver for Go's +[database/sql](https://golang.org/pkg/database/sql/)package. + +It also works with the Phoenix Query Server from the Apache +Phoenix project, as the Phoenix Query Server uses Avatica under the +hood. + +## Getting Started +Install using your dependency management tool (we recommend [dep](https://github.com/golang/dep)!): + +~~~~~~ +$ dep ensure -add github.com/apache/calcite-avatica-go +~~~~~~ + +## Usage + +The Avatica Go driver implements Go's `database/sql/driver` interface, so, import Go's +`database/sql` package and the driver: + +~~~~~~go +import "database/sql" +import _ "github.com/apache/calcite-avatica-go" + +db, err := sql.Open("avatica", "http://localhost:8765") +~~~~~~ + +Then simply use the database connection to query some data, for example: + +~~~~~~go +rows := db.Query("SELECT COUNT(*) FROM test") +~~~~~~ + +## DSN (Data Source Name) + +The DSN has the following format (optional parts are marked by square brackets): + +~~~~~~ +http://[username:password@]address:port[/schema][?parameter1=value&...parameterN=value] +~~~~~~ + +In other words, the scheme (http), address and port are mandatory, but the schema and parameters are optional. + +{% comment %} +It's a shame that we have to embed HTML to get the anchors but the normal +header tags from kramdown screw up the definition list. We lose the pretty +on-hover images for the permalink, but oh well. +{% endcomment %} + +<strong><a name="username" href="#username">username</a></strong> +This is the JDBC username that is passed directly to the backing database. It is *NOT* used for authenticating +against Avatica. + +<strong><a name="password" href="#password">password</a></strong> +This is the JDBC password that is passed directly to the backing database. It is *NOT* used for authenticating +against Avatica. + +<strong><a name="schema" href="#schema">schema</a></strong> +The `schema` path sets the default schema to use for this connection. For example, if you set it to `myschema`, +then executing the query `SELECT * FROM my_table` will have the equivalence of `SELECT * FROM myschema.my_table`. +If schema is set, you can still work on tables in other schemas by supplying a schema prefix: +`SELECT * FROM myotherschema.my_other_table`. + +The parameters references the options used by the Java implementation as much as possible. +The following parameters are supported: + +<strong><a name="authentication" href="#authentication">authentication</a></strong> +The authentication type to use when authenticating against Avatica. Valid values are `BASIC` for HTTP Basic authentication, +`DIGEST` for HTTP Digest authentication, and `SPNEGO` for Kerberos with SPNEGO authentication. + +<strong><a name="avaticaUser" href="#avaticaUser">avaticaUser</a></strong> +The user to use when authenticating against Avatica. This parameter is required if `authentication` is `BASIC` or `DIGEST`. + +<strong><a name="avaticaPassword" href="#avaticaPassword">avaticaPassword</a></strong> +The password to use when authenticating against Avatica. This parameter is required if `authentication` is `BASIC` or `DIGEST`. + +<strong><a name="principal" href="#principal">principal</a></strong> +The Kerberos principal to use when authenticating against Avatica. It should be in the form `primary/instance@realm`, where +the instance is optional. This parameter is required if `authentication` is `SPNEGO` and you want the driver to perform the +Kerberos login. + +<strong><a name="keytab" href="#keytab">keytab</a></strong> +The path to the Kerberos keytab to use when authenticating against Avatica. This parameter is required if `authentication` +is `SPNEGO` and you want the driver to perform the Kerberos login. + +<strong><a name="krb5Conf" href="#krb5Conf">krb5Conf</a></strong> +The path to the Kerberos configuration to use when authenticating against Avatica. This parameter is required if `authentication` +is `SPNEGO` and you want the driver to perform the Kerberos login. + +<strong><a name="krb5CredentialsCache" href="#krb5CredentialsCache">krb5CredentialsCache</a></strong> +The path to the Kerberos credential cache file to use when authenticating against Avatica. This parameter is required if +`authentication` is `SPNEGO` and you have logged into Kerberos already and want the driver to use the existing credentials. + +<strong><a name="location" href="#location">location</a></strong> +The `location` will be set as the location of unserialized `time.Time` values. It must be a valid timezone. +If you want to use the local timezone, use `Local`. By default, this is set to `UTC`. + +<strong><a name="maxRowsTotal" href="#maxRowsTotal">maxRowsTotal</a></strong> +The `maxRowsTotal` parameter sets the maximum number of rows to return for a given query. By default, this is set to +`-1`, so that there is no limit on the number of rows returned. + +<strong><a name="frameMaxSize" href="#frameMaxSize">frameMaxSize</a></strong> +The `frameMaxSize` parameter sets the maximum number of rows to return in a frame. Depending on the number of rows +returned and subject to the limits of `maxRowsTotal`, a query result set can contain rows in multiple frames. These +additional frames are then fetched on a as-needed basis. `frameMaxSize` allows you to control the number of rows +in each frame to suit your application's performance profile. By default this is set to `-1`, so that there is no limit +on the number of rows in a frame. + +<strong><a name="transactionIsolation" href="#transactionIsolation">transactionIsolation</a></strong> +Setting `transactionIsolation` allows you to set the isolation level for transactions using the connection. The value +should be a positive integer analogous to the transaction levels defined by the JDBC specification. The default value +is `0`, which means transactions are not supported. This is to deal with the fact that Calcite/Avatica works with +many types of backends, with some backends having no transaction support. If you are using Apache Phoenix 4.7 onwards, +we recommend setting it to `4`, which is the maximum isolation level supported. + +The supported values for `transactionIsolation` are: + +| Value | JDBC Constant | Description | +| :-----| :----------------------------- | :------------------------------------------------------------------------------- | +| 0 | none | Transactions are not supported | +| 1 | `TRANSACTION_READ_UNCOMMITTED` | Dirty reads, non-repeatable reads and phantom reads may occur. | +| 2 | `TRANSACTION_READ_COMMITTED` | Dirty reads are prevented, but non-repeatable reads and phantom reads may occur. | +| 4 | `TRANSACTION_REPEATABLE_READ` | Dirty reads and non-repeatable reads are prevented, but phantom reads may occur. | +| 8 | `TRANSACTION_SERIALIZABLE` | Dirty reads, non-repeatable reads, and phantom reads are all prevented. | + +## time.Time support + +The following datatypes are automatically converted to and from `time.Time`: +`TIME`, `DATE` and `TIMESTAMP`. + +It is important to understand that Avatica and the underlying database ignores the timezone. If you save a `time.Time` +to the database, the timezone is ignored and vice-versa. This is why you need to make sure the `location` parameter +in your DSN is set to the same value as the location of the `time.Time` values you are inserting into the database. + +We recommend using `UTC`, which is the default value of `location`. + +## Apache Phoenix Error Codes +The Go client comes with support for retrieving the error code when an error occurs. This is extremely useful when +you want to take specific action when a particular type of error occurs. + +If the error returned is a ResponseError, calling the `Name()` method on the error will return the appropriate +Apache Phoenix error code: + +~~~~go +_, err := db.Exec("SELECT * FROM table_that_does_not_exist") // Query undefined table + +// First, assert the error type +perr, ok := err.(avatica.ResponseError) + +// If it cannot be asserted +if !ok{ + // Error was not an Avatica ResponseError +} + +// Print the Apache Phoenix error code +fmt.Println(perr.Name()) // Prints: table_undefined +~~~~ + +## Version Compatibility +| Driver Version | Phoenix Version | Calcite-Avatica Version | +| :-------------- | :---------------- | :---------------------- | +| 2.x.x | >= 4.8.0 | >= 1.8.0 | + +## Development + +To file issues, please use the [Calcite JIRA](https://issues.apache.org/jira/projects/CALCITE/issues). + +To run tests, you must have an instance of the Avatica server available and set it in the `AVATICA_HOST` +environment variable. + +For example: `export AVATICA_HOST=http://localhost:8765` + +Once that is set up, you can run the tests but skip tests in the vendor directory +(to avoid running tests for the dependencies) using: + +~~~~ +go test $(go list ./... | grep -v /vendor/) +~~~~ + +To update the procotol buffer definitions, update `AVATICA_VER` in `gen-protobuf.bat` and `gen-protobuf.sh` to match +the version you want to generate protobufs for and then run the appropriate script for your platform. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/calcite-avatica-go/blob/bb7b70cb/site/go_history.md ---------------------------------------------------------------------- diff --git a/site/go_history.md b/site/go_history.md new file mode 100644 index 0000000..af3c37d --- /dev/null +++ b/site/go_history.md @@ -0,0 +1,56 @@ +--- +layout: docs +title: Go Client History +permalink: "/docs/go_history.html" +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +For a full list of releases, see +<a href="https://github.com/apache/calcite-avatica-go/releases">github</a>. +Downloads are available on the +[downloads page]({{ site.baseurl }}/downloads/). + +## <a href="https://github.com/apache/calcite-avatica-go/releases/tag/calcite-avatica-2.2.0">2.2.0</a> / 2017-08-XX +{: #v2-2-0} + +Apache Calcite Avatica Go 2.2.0 is the first release since the Go driver has been donated +to the Apache Software foundation. +Go 1.7+ is supported, but we recommend using the latest stable version of Go. + +Features and bug fixes + +* [<a href="https://issues.apache.org/jira/browse/CALCITE-1240">CALCITE-1240</a>] + Intial import of the original [Boostport/avatica](https://github.com/Boostport/avatica) code-base into the + [apache/calcite-avatica-go](https://github.com/apache/calcite-avatica-go) repository +* [<a href="https://issues.apache.org/jira/browse/CALCITE-1938">CALCITE-1938</a>] + Releasing the first release of Calcite Avatica Go under the Apache Software Foundation + +Web site and documentation + +* [<a href="https://issues.apache.org/jira/browse/CALCITE-1937">CALCITE-1937</a>] + Set up Calcite Avatica Go website + +## Past releases + +Prior to release 2.2.0, the Avatica Go client was developed by Boostport. + +Please refer to the [Boostport/Avatica](https://github.com/Boostport/avatica) Github repository for previous releases +of the Avatica Go client. \ No newline at end of file