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

Reply via email to