1********************************************************************************
2Go Snowflake Driver
3********************************************************************************
4
5.. image:: https://github.com/snowflakedb/gosnowflake/workflows/Build%20and%20Test/badge.svg?branch=master
6    :target: https://github.com/snowflakedb/gosnowflake/actions?query=workflow%3A%22Build+and+Test%22
7
8.. image:: http://img.shields.io/:license-Apache%202-brightgreen.svg
9    :target: http://www.apache.org/licenses/LICENSE-2.0.txt
10
11.. image:: https://goreportcard.com/badge/github.com/snowflakedb/gosnowflake
12    :target: https://goreportcard.com/report/github.com/snowflakedb/gosnowflake
13
14This topic provides instructions for installing, running, and modifying the Go Snowflake Driver. The driver supports Go's `database/sql <https://golang.org/pkg/database/sql/>`_ package.
15
16Prerequisites
17================================================================================
18
19The following software packages are required to use the Go Snowflake Driver.
20
21Go
22----------------------------------------------------------------------
23
24The latest driver requires the `Go language <https://golang.org/>`_ 1.14 or higher. The supported operating systems are Linux, Mac OS, and Windows, but you may run the driver on other platforms if the Go language works correctly on those platforms.
25
26
27Installation
28================================================================================
29
30Get Gosnowflake source code, if not installed.
31
32.. code-block:: bash
33
34    go get -u github.com/snowflakedb/gosnowflake
35
36Docs
37====
38
39For detailed documentation and basic usage examples, please see the documentation at
40`godoc.org <https://godoc.org/github.com/snowflakedb/gosnowflake/>`_.
41
42Sample Programs
43================================================================================
44
45Snowflake provides a set of sample programs to test with. Set the environment variable ``$GOPATH`` to the top directory of your workspace, e.g., ``~/go`` and make certain to
46include ``$GOPATH/bin`` in the environment variable ``$PATH``. Run the ``make`` command to build all sample programs.
47
48.. code-block:: go
49
50    make install
51
52In the following example, the program ``select1.go`` is built and installed in ``$GOPATH/bin`` and can be run from the command line:
53
54.. code-block:: bash
55
56    SNOWFLAKE_TEST_ACCOUNT=<your_account> \
57    SNOWFLAKE_TEST_USER=<your_user> \
58    SNOWFLAKE_TEST_PASSWORD=<your_password> \
59    select1
60    Congrats! You have successfully run SELECT 1 with Snowflake DB!
61
62Development
63================================================================================
64
65The developer notes are hosted with the source code on `GitHub <https://github.com/snowflakedb/gosnowflake>`_.
66
67Testing Code
68----------------------------------------------------------------------
69
70Set the Snowflake connection info in ``parameters.json``:
71
72.. code-block:: json
73
74    {
75        "testconnection": {
76            "SNOWFLAKE_TEST_USER":      "<your_user>",
77            "SNOWFLAKE_TEST_PASSWORD":  "<your_password>",
78            "SNOWFLAKE_TEST_ACCOUNT":   "<your_account>",
79            "SNOWFLAKE_TEST_WAREHOUSE": "<your_warehouse>",
80            "SNOWFLAKE_TEST_DATABASE":  "<your_database>",
81            "SNOWFLAKE_TEST_SCHEMA":    "<your_schema>",
82            "SNOWFLAKE_TEST_ROLE":      "<your_role>"
83        }
84    }
85
86Install `jq <https://stedolan.github.io/jq/>`_ so that the parameters can get parsed correctly, and run ``make test`` in your Go development environment:
87
88.. code-block:: bash
89
90    make test
91
92Submitting Pull Requests
93----------------------------------------------------------------------
94
95You may use your preferred editor to edit the driver code. Make certain to run ``make fmt lint`` before submitting any pull request to Snowflake. This command formats your source code according to the standard Go style and detects any coding style issues.
96
97Support
98----------------------------------------------------------------------
99
100For official support, contact Snowflake support at:
101https://support.snowflake.net/
102
103