1# MinIO Go Client SDK for Amazon S3 Compatible Cloud Storage [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Sourcegraph](https://sourcegraph.com/github.com/minio/minio-go/-/badge.svg)](https://sourcegraph.com/github.com/minio/minio-go?badge) [![Apache V2 License](http://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/minio/minio-go/blob/master/LICENSE)
2
3The MinIO Go Client SDK provides simple APIs to access any Amazon S3 compatible object storage.
4
5This quickstart guide will show you how to install the MinIO client SDK, connect to MinIO, and provide a walkthrough for a simple file uploader. For a complete list of APIs and examples, please take a look at the [Go Client API Reference](https://docs.min.io/docs/golang-client-api-reference).
6
7This document assumes that you have a working [Go development environment](https://golang.org/doc/install).
8
9## Download from Github
10```sh
11GO111MODULE=on go get github.com/minio/minio-go/v7
12```
13
14## Initialize MinIO Client
15MinIO client requires the following four parameters specified to connect to an Amazon S3 compatible object storage.
16
17| Parameter  | Description|
18| :---         |     :---     |
19| endpoint   | URL to object storage service.   |
20| _minio.Options_ | All the options such as credentials, custom transport etc. |
21
22```go
23package main
24
25import (
26	"log"
27
28	"github.com/minio/minio-go/v7"
29	"github.com/minio/minio-go/v7/pkg/credentials"
30)
31
32func main() {
33	endpoint := "play.min.io"
34	accessKeyID := "Q3AM3UQ867SPQQA43P2F"
35	secretAccessKey := "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"
36	useSSL := true
37
38	// Initialize minio client object.
39	minioClient, err := minio.New(endpoint, &minio.Options{
40		Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
41		Secure: useSSL,
42	})
43	if err != nil {
44		log.Fatalln(err)
45	}
46
47	log.Printf("%#v\n", minioClient) // minioClient is now set up
48}
49```
50
51## Quick Start Example - File Uploader
52This example program connects to an object storage server, creates a bucket and uploads a file to the bucket.
53
54We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public.
55
56### FileUploader.go
57```go
58package main
59
60import (
61	"context"
62	"log"
63
64	"github.com/minio/minio-go/v7"
65	"github.com/minio/minio-go/v7/pkg/credentials"
66)
67
68func main() {
69	ctx := context.Background()
70	endpoint := "play.min.io"
71	accessKeyID := "Q3AM3UQ867SPQQA43P2F"
72	secretAccessKey := "zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG"
73	useSSL := true
74
75	// Initialize minio client object.
76	minioClient, err := minio.New(endpoint, &minio.Options{
77		Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
78		Secure: useSSL,
79	})
80	if err != nil {
81		log.Fatalln(err)
82	}
83
84	// Make a new bucket called mymusic.
85	bucketName := "mymusic"
86	location := "us-east-1"
87
88	err = minioClient.MakeBucket(ctx, bucketName, minio.MakeBucketOptions{Region: location})
89	if err != nil {
90		// Check to see if we already own this bucket (which happens if you run this twice)
91		exists, errBucketExists := minioClient.BucketExists(ctx, bucketName)
92		if errBucketExists == nil && exists {
93			log.Printf("We already own %s\n", bucketName)
94		} else {
95			log.Fatalln(err)
96		}
97	} else {
98		log.Printf("Successfully created %s\n", bucketName)
99	}
100
101	// Upload the zip file
102	objectName := "golden-oldies.zip"
103	filePath := "/tmp/golden-oldies.zip"
104	contentType := "application/zip"
105
106	// Upload the zip file with FPutObject
107	n, err := minioClient.FPutObject(ctx, bucketName, objectName, filePath, minio.PutObjectOptions{ContentType: contentType})
108	if err != nil {
109		log.Fatalln(err)
110	}
111
112	log.Printf("Successfully uploaded %s of size %d\n", objectName, n)
113}
114```
115
116### Run FileUploader
117```sh
118export GO111MODULE=on
119go run file-uploader.go
1202016/08/13 17:03:28 Successfully created mymusic
1212016/08/13 17:03:40 Successfully uploaded golden-oldies.zip of size 16253413
122
123mc ls play/mymusic/
124[2016-05-27 16:02:16 PDT]  17MiB golden-oldies.zip
125```
126
127## API Reference
128The full API Reference is available here.
129
130* [Complete API Reference](https://docs.min.io/docs/golang-client-api-reference)
131
132### API Reference : Bucket Operations
133* [`MakeBucket`](https://docs.min.io/docs/golang-client-api-reference#MakeBucket)
134* [`ListBuckets`](https://docs.min.io/docs/golang-client-api-reference#ListBuckets)
135* [`BucketExists`](https://docs.min.io/docs/golang-client-api-reference#BucketExists)
136* [`RemoveBucket`](https://docs.min.io/docs/golang-client-api-reference#RemoveBucket)
137* [`ListObjects`](https://docs.min.io/docs/golang-client-api-reference#ListObjects)
138* [`ListIncompleteUploads`](https://docs.min.io/docs/golang-client-api-reference#ListIncompleteUploads)
139
140### API Reference : Bucket policy Operations
141* [`SetBucketPolicy`](https://docs.min.io/docs/golang-client-api-reference#SetBucketPolicy)
142* [`GetBucketPolicy`](https://docs.min.io/docs/golang-client-api-reference#GetBucketPolicy)
143
144### API Reference : Bucket notification Operations
145* [`SetBucketNotification`](https://docs.min.io/docs/golang-client-api-reference#SetBucketNotification)
146* [`GetBucketNotification`](https://docs.min.io/docs/golang-client-api-reference#GetBucketNotification)
147* [`RemoveAllBucketNotification`](https://docs.min.io/docs/golang-client-api-reference#RemoveAllBucketNotification)
148* [`ListenBucketNotification`](https://docs.min.io/docs/golang-client-api-reference#ListenBucketNotification) (MinIO Extension)
149* [`ListenNotification`](https://docs.min.io/docs/golang-client-api-reference#ListenNotification) (MinIO Extension)
150
151### API Reference : File Object Operations
152* [`FPutObject`](https://docs.min.io/docs/golang-client-api-reference#FPutObject)
153* [`FGetObject`](https://docs.min.io/docs/golang-client-api-reference#FGetObject)
154
155### API Reference : Object Operations
156* [`GetObject`](https://docs.min.io/docs/golang-client-api-reference#GetObject)
157* [`PutObject`](https://docs.min.io/docs/golang-client-api-reference#PutObject)
158* [`PutObjectStreaming`](https://docs.min.io/docs/golang-client-api-reference#PutObjectStreaming)
159* [`StatObject`](https://docs.min.io/docs/golang-client-api-reference#StatObject)
160* [`CopyObject`](https://docs.min.io/docs/golang-client-api-reference#CopyObject)
161* [`RemoveObject`](https://docs.min.io/docs/golang-client-api-reference#RemoveObject)
162* [`RemoveObjects`](https://docs.min.io/docs/golang-client-api-reference#RemoveObjects)
163* [`RemoveIncompleteUpload`](https://docs.min.io/docs/golang-client-api-reference#RemoveIncompleteUpload)
164* [`SelectObjectContent`](https://docs.min.io/docs/golang-client-api-reference#SelectObjectContent)
165
166
167### API Reference : Presigned Operations
168* [`PresignedGetObject`](https://docs.min.io/docs/golang-client-api-reference#PresignedGetObject)
169* [`PresignedPutObject`](https://docs.min.io/docs/golang-client-api-reference#PresignedPutObject)
170* [`PresignedHeadObject`](https://docs.min.io/docs/golang-client-api-reference#PresignedHeadObject)
171* [`PresignedPostPolicy`](https://docs.min.io/docs/golang-client-api-reference#PresignedPostPolicy)
172
173### API Reference : Client custom settings
174* [`SetAppInfo`](http://docs.min.io/docs/golang-client-api-reference#SetAppInfo)
175* [`TraceOn`](http://docs.min.io/docs/golang-client-api-reference#TraceOn)
176* [`TraceOff`](http://docs.min.io/docs/golang-client-api-reference#TraceOff)
177
178## Full Examples
179
180### Full Examples : Bucket Operations
181* [makebucket.go](https://github.com/minio/minio-go/blob/master/examples/s3/makebucket.go)
182* [listbuckets.go](https://github.com/minio/minio-go/blob/master/examples/s3/listbuckets.go)
183* [bucketexists.go](https://github.com/minio/minio-go/blob/master/examples/s3/bucketexists.go)
184* [removebucket.go](https://github.com/minio/minio-go/blob/master/examples/s3/removebucket.go)
185* [listobjects.go](https://github.com/minio/minio-go/blob/master/examples/s3/listobjects.go)
186* [listobjectsV2.go](https://github.com/minio/minio-go/blob/master/examples/s3/listobjectsV2.go)
187* [listincompleteuploads.go](https://github.com/minio/minio-go/blob/master/examples/s3/listincompleteuploads.go)
188
189### Full Examples : Bucket policy Operations
190* [setbucketpolicy.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketpolicy.go)
191* [getbucketpolicy.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketpolicy.go)
192* [listbucketpolicies.go](https://github.com/minio/minio-go/blob/master/examples/s3/listbucketpolicies.go)
193
194### Full Examples : Bucket lifecycle Operations
195* [setbucketlifecycle.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketlifecycle.go)
196* [getbucketlifecycle.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketlifecycle.go)
197
198### Full Examples : Bucket encryption Operations
199* [setbucketencryption.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketencryption.go)
200* [getbucketencryption.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketencryption.go)
201* [deletebucketencryption.go](https://github.com/minio/minio-go/blob/master/examples/s3/deletebucketencryption.go)
202
203### Full Examples : Bucket replication Operations
204* [setbucketreplication.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketreplication.go)
205* [getbucketreplication.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketreplication.go)
206* [removebucketreplication.go](https://github.com/minio/minio-go/blob/master/examples/s3/removebucketreplication.go)
207
208### Full Examples : Bucket notification Operations
209* [setbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/s3/setbucketnotification.go)
210* [getbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/s3/getbucketnotification.go)
211* [removeallbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/s3/removeallbucketnotification.go)
212* [listenbucketnotification.go](https://github.com/minio/minio-go/blob/master/examples/minio/listenbucketnotification.go) (MinIO Extension)
213* [listennotification.go](https://github.com/minio/minio-go/blob/master/examples/minio/listen-notification.go) (MinIO Extension)
214
215### Full Examples : File Object Operations
216* [fputobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/fputobject.go)
217* [fgetobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/fgetobject.go)
218* [fputobject-context.go](https://github.com/minio/minio-go/blob/master/examples/s3/fputobject-context.go)
219* [fgetobject-context.go](https://github.com/minio/minio-go/blob/master/examples/s3/fgetobject-context.go)
220
221### Full Examples : Object Operations
222* [putobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/putobject.go)
223* [getobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/getobject.go)
224* [putobject-context.go](https://github.com/minio/minio-go/blob/master/examples/s3/putobject-context.go)
225* [getobject-context.go](https://github.com/minio/minio-go/blob/master/examples/s3/getobject-context.go)
226* [statobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/statobject.go)
227* [copyobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/copyobject.go)
228* [removeobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/removeobject.go)
229* [removeincompleteupload.go](https://github.com/minio/minio-go/blob/master/examples/s3/removeincompleteupload.go)
230* [removeobjects.go](https://github.com/minio/minio-go/blob/master/examples/s3/removeobjects.go)
231
232### Full Examples : Encrypted Object Operations
233* [put-encrypted-object.go](https://github.com/minio/minio-go/blob/master/examples/s3/put-encrypted-object.go)
234* [get-encrypted-object.go](https://github.com/minio/minio-go/blob/master/examples/s3/get-encrypted-object.go)
235* [fput-encrypted-object.go](https://github.com/minio/minio-go/blob/master/examples/s3/fputencrypted-object.go)
236
237### Full Examples : Presigned Operations
238* [presignedgetobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedgetobject.go)
239* [presignedputobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedputobject.go)
240* [presignedheadobject.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedheadobject.go)
241* [presignedpostpolicy.go](https://github.com/minio/minio-go/blob/master/examples/s3/presignedpostpolicy.go)
242
243## Explore Further
244* [Complete Documentation](https://docs.min.io)
245* [MinIO Go Client SDK API Reference](https://docs.min.io/docs/golang-client-api-reference)
246
247## Contribute
248[Contributors Guide](https://github.com/minio/minio-go/blob/master/CONTRIBUTING.md)
249
250## License
251This SDK is distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), see [LICENSE](https://github.com/minio/minio-go/blob/master/LICENSE) and [NOTICE](https://github.com/minio/minio-go/blob/master/NOTICE) for more information.
252