Go 데이터베이스/SQL에서 Spanner 시작하기

목표

이 튜토리얼에서는 Spanner 데이터베이스/SQL 드라이버를 사용하여 다음 단계를 안내합니다.

• Spanner 인스턴스와 데이터베이스 만들기
• 데이터베이스에서 데이터 읽기, 쓰기 및 데이터에서 SQL 쿼리 실행
• 데이터베이스 스키마 업데이트
• 읽기-쓰기 트랜잭션을 사용하여 데이터 업데이트
• 데이터베이스에 보조 색인 추가
• 색인을 사용하여 데이터 읽기 및 데이터에서 SQL 쿼리 실행
• 읽기 전용 트랜잭션을 사용하여 데이터 검색

비용

이 튜토리얼에서는 청구 가능한Google Cloud구성요소인 Spanner를 사용합니다. Spanner 사용 비용에 대한 자세한 내용은 가격 책정을 참조하세요.

시작하기 전에

설정에 설명된 단계를 완료합니다. 기본 Google Cloud 프로젝트 만들기 및 설정, 결제 사용 설정, Cloud Spanner API 사용 설정, Cloud Spanner API 사용에 필요한 사용자 인증 정보를 가져오도록 OAuth 2.0 설정을 다룹니다.

특히 gcloud auth application-default login을 실행하여 사용자 인증 정보로 로컬 개발 환경을 설정해야 합니다.

참고: 이 튜토리얼에서 만드는 리소스를 유지하지 않으려면 기존 프로젝트를 선택하는 대신 새 Google Cloud 프로젝트를 만드는 것이 좋습니다. 그러면 튜토리얼을 마친 후 프로젝트를 삭제하여 프로젝트와 연결된 모든 리소스를 제거할 수 있습니다.

로컬 데이터베이스/SQL 환경 준비

1. 개발 머신에 아직 Go가 설치되어 있지 않다면 Go를 다운로드하여 설치합니다.

2. 샘플 저장소를 로컬 머신에 클론합니다.

   git clone https://github.com/googleapis/go-sql-spanner.git
   

3. Spanner 샘플 코드가 있는 디렉터리로 변경합니다.

   cd go-sql-spanner/snippets
   

인스턴스 만들기

Spanner를 처음 사용할 때는 인스턴스를 만들어야 합니다. 이 인스턴스는 Spanner 데이터베이스에서 사용하는 리소스를 할당한 것입니다. 인스턴스를 만들 때는 인스턴스 구성을 선택합니다. 이 구성에 따라 데이터 저장 위치와 사용할 노드 수가 결정되고, 또한 노드 수에 따라 인스턴스의 제공 리소스 및 스토리지 리소스 양이 결정됩니다.

다음 방법 중 하나를 사용하여 Spanner 인스턴스를 만드는 방법은 인스턴스 만들기를 참조하세요. 인스턴스 이름을 test-instance로 지정하여 test-instance라는 인스턴스를 참조하는 이 문서의 다른 주제에서 사용할 수 있습니다.

• Google Cloud CLI
• Google Cloud 콘솔
• 클라이언트 라이브러리(C++, C#, Go, Java, Node.js, PHP, Python 또는 Ruby)

샘플 파일 살펴보기

샘플 저장소에는 데이터베이스/SQL과 함께 Spanner를 사용하는 방법을 보여주는 샘플이 있습니다.

Spanner 사용 방법을 보여주는 getting_started_guide.go 파일을 살펴보세요. 코드는 새 데이터베이스를 만들고 사용하는 방법을 보여줍니다. 데이터는 스키마 및 데이터 모델 페이지에 나와 있는 스키마 예시를 사용합니다.

데이터베이스 만들기

GoogleSQL

gcloud spanner databases create example-db --instance=test-instance

PostgreSQL

gcloud spanner databases create example-db --instance=test-instance \
  --database-dialect=POSTGRESQL

다음과 같이 표시됩니다.

Creating database...done.

테이블 만들기

다음 코드에서는 데이터베이스에 테이블 2개를 만듭니다.

참고: 후속 코드 샘플에서는 이러한 테이블 두 개를 사용합니다. 이 코드를 실행하지 않으면 Google Cloud 콘솔이나 gcloud CLI를 사용하여 테이블을 만드세요. 자세한 내용은 스키마 예시를 참조하세요.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateTables(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Create two tables in one batch on Spanner.
	conn, err := db.Conn(ctx)
	defer conn.Close()

	// Start a DDL batch on the connection.
	// This instructs the connection to buffer all DDL statements until the
	// command `run batch` is executed.
	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Singers (
				SingerId   INT64 NOT NULL,
				FirstName  STRING(1024),
				LastName   STRING(1024),
				SingerInfo BYTES(MAX)
			) PRIMARY KEY (SingerId)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Albums (
				SingerId     INT64 NOT NULL,
				AlbumId      INT64 NOT NULL,
				AlbumTitle   STRING(MAX)
			) PRIMARY KEY (SingerId, AlbumId),
			INTERLEAVE IN PARENT Singers ON DELETE CASCADE`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	fmt.Fprintf(w, "Created Singers & Albums tables in database: [%s]\n", databaseName)
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateTablesPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Create two tables in one batch on Spanner PostgreSQL.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = conn.Close() }()

	// Start a DDL batch on the connection.
	// This instructs the connection to buffer all DDL statements until the
	// command `run batch` is executed.
	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table singers (
				singer_id   bigint not null primary key,
				first_name  varchar(1024),
				last_name   varchar(1024),
				singer_info bytea
			)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table albums (
				singer_id     bigint not null,
				album_id      bigint not null,
				album_title   varchar,
				primary key (singer_id, album_id)
			)
			interleave in parent singers on delete cascade`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	_, _ = fmt.Fprintf(w, "Created singers & albums tables in database: [%s]\n", databaseName)
	return nil
}

다음 명령어로 샘플을 실행합니다.

GoogleSQL

go run getting_started_guide.go createtables projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go createtablespg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

다음 단계는 데이터베이스에 데이터 쓰기입니다.

연결 만들기

읽기 또는 쓰기를 수행하려면 먼저 sql.DB를 만들어야 합니다. sql.DB에는 Spanner와 상호작용하는 데 사용할 수 있는 연결 풀이 포함되어 있습니다. 데이터베이스 이름 및 기타 연결 속성은 데이터베이스/SQL 데이터 소스 이름에 지정됩니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateConnection(ctx context.Context, w io.Writer, databaseName string) error {
	// The dataSourceName should start with a fully qualified Spanner database name
	// in the format `projects/my-project/instances/my-instance/databases/my-database`.
	// Additional properties can be added after the database name by
	// adding one or more `;name=value` pairs.

	dsn := fmt.Sprintf("%s;numChannels=8", databaseName)
	db, err := sql.Open("spanner", dsn)
	if err != nil {
		return err
	}
	defer db.Close()

	row := db.QueryRowContext(ctx, "select 'Hello world!' as hello")
	var msg string
	if err := row.Scan(&msg); err != nil {
		return err
	}
	fmt.Fprintf(w, "Greeting from Spanner: %s\n", msg)
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func CreateConnectionPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	// The dataSourceName should start with a fully qualified Spanner database name
	// in the format `projects/my-project/instances/my-instance/databases/my-database`.
	// Additional properties can be added after the database name by
	// adding one or more `;name=value` pairs.

	dsn := fmt.Sprintf("%s;numChannels=8", databaseName)
	db, err := sql.Open("spanner", dsn)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// The Spanner database/sql driver supports both PostgreSQL-style query
	// parameters ($1, $2, ...) and positional query parameters (?, ?, ...).
	row := db.QueryRowContext(ctx, "select $1 as hello", "Hello world!")
	var msg string
	if err := row.Scan(&msg); err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "Greeting from Spanner PostgreSQL: %s\n", msg)
	return nil
}

DML을 사용하여 데이터 쓰기

읽기-쓰기 트랜잭션에서 DML(Data Manipulation Language)을 사용하여 데이터를 삽입할 수 있습니다.

ExecContext 함수를 사용하여 DML 문을 실행합니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithDml(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Add 4 rows in one statement.
	// The database/sql driver supports positional query parameters.
	res, err := db.ExecContext(ctx,
		"INSERT INTO Singers (SingerId, FirstName, LastName) "+
			"VALUES (?, ?, ?), (?, ?, ?), "+
			"       (?, ?, ?), (?, ?, ?)",
		12, "Melissa", "Garcia",
		13, "Russel", "Morales",
		14, "Jacqueline", "Long",
		15, "Dylan", "Shaw")
	if err != nil {
		return err
	}
	c, err := res.RowsAffected()
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "%v records inserted\n", c)

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithDmlPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Add 4 rows in one statement.
	// The database/sql driver supports positional query parameters.
	res, err := db.ExecContext(ctx,
		"insert into singers (singer_id, first_name, last_name) "+
			"values (?, ?, ?), (?, ?, ?), "+
			"       (?, ?, ?), (?, ?, ?)",
		12, "Melissa", "Garcia",
		13, "Russel", "Morales",
		14, "Jacqueline", "Long",
		15, "Dylan", "Shaw")
	if err != nil {
		return err
	}
	c, err := res.RowsAffected()
	if err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "%v records inserted\n", c)

	return nil
}

다음 명령어로 샘플을 실행합니다.

GoogleSQL

go run getting_started_guide.go dmlwrite projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go dmlwritepg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

4 records inserted.

참고: 커밋 크기에는 제한이 있습니다. 자세한 내용은 CRUD 한도를 참조하세요.

변형을 사용하여 데이터 쓰기

변형을 사용하여 데이터를 삽입할 수도 있습니다.

Mutation은 변형 작업의 컨테이너입니다. Mutation은 Spanner가 Spanner 데이터베이스의 여러 행과 테이블에 원자적으로 적용할 수 있는 일련의 삽입, 업데이트, 삭제를 나타냅니다.

Mutation.InsertOrUpdate()INSERT_OR_UPDATE를 사용하여 새 행을 추가하거나 행이 이미 존재하는 경우에는 열 값을 업데이트하는 변형을 생성합니다. 또는 Mutation.Insert() 메서드를 사용하여 새 행을 추가하는 INSERT 변형을 생성합니다.

conn.Raw 함수를 사용하여 기본 Spanner 연결의 참조를 가져옵니다. SpannerConn.Apply 함수가 데이터베이스에 원자적으로 변형을 적용합니다.

다음 코드는 변형을 사용하여 데이터를 쓰는 방법을 보여줍니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithMutations(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer conn.Close()

	singerColumns := []string{"SingerId", "FirstName", "LastName"}
	albumColumns := []string{"SingerId", "AlbumId", "AlbumTitle"}
	mutations := []*spanner.Mutation{
		spanner.Insert("Singers", singerColumns, []interface{}{int64(1), "Marc", "Richards"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(2), "Catalina", "Smith"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(3), "Alice", "Trentor"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(4), "Lea", "Martin"}),
		spanner.Insert("Singers", singerColumns, []interface{}{int64(5), "David", "Lomond"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(1), int64(1), "Total Junk"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(1), int64(2), "Go, Go, Go"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(2), int64(1), "Green"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(2), int64(2), "Forever Hold Your Peace"}),
		spanner.Insert("Albums", albumColumns, []interface{}{int64(2), int64(3), "Terrified"}),
	}
	// Mutations can be written outside an explicit transaction using SpannerConn#Apply.
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	fmt.Fprintf(w, "Inserted %v rows\n", len(mutations))

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func WriteDataWithMutationsPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = conn.Close() }()

	singerColumns := []string{"singer_id", "first_name", "last_name"}
	albumColumns := []string{"singer_id", "album_id", "album_title"}
	mutations := []*spanner.Mutation{
		spanner.Insert("singers", singerColumns, []interface{}{int64(1), "Marc", "Richards"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(2), "Catalina", "Smith"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(3), "Alice", "Trentor"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(4), "Lea", "Martin"}),
		spanner.Insert("singers", singerColumns, []interface{}{int64(5), "David", "Lomond"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(1), int64(1), "Total Junk"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(1), int64(2), "Go, Go, Go"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(2), int64(1), "Green"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(2), int64(2), "Forever Hold Your Peace"}),
		spanner.Insert("albums", albumColumns, []interface{}{int64(2), int64(3), "Terrified"}),
	}
	// Mutations can be written outside an explicit transaction using SpannerConn#Apply.
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "Inserted %v rows\n", len(mutations))

	return nil
}

write 인수를 사용하여 다음 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go write projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go writepg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

참고: 커밋 크기에는 제한이 있습니다. 자세한 내용은 CRUD 한도를 참조하세요.

SQL을 사용하여 데이터 쿼리

Spanner는 데이터 읽기용 SQL 인터페이스를 지원하며, 개발자는 Google Cloud CLI를 사용하여 명령줄에서 액세스하거나 Spanner 데이터베이스/SQL 드라이버를 사용하여 프로그래매틱 방식으로 액세스할 수 있습니다.

명령줄에서

다음 SQL 문을 실행하여 Albums 테이블에서 모든 열의 값을 읽습니다.

GoogleSQL

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

PostgreSQL

gcloud spanner databases execute-sql example-db --instance=test-instance \
    --sql='SELECT singer_id, album_id, album_title FROM albums'

참고: GoogleSQL 참조는 GoogleSQL의 쿼리 구문을, PostgreSQL 참조는 PostgreSQL 어휘 구조 및 구문을 확인하세요.

결과는 다음과 같습니다.

SingerId AlbumId AlbumTitle
1        1       Total Junk
1        2       Go, Go, Go
2        1       Green
2        2       Forever Hold Your Peace
2        3       Terrified

Spanner database/sql 드라이버 사용

명령줄에서 SQL 문을 실행하는 것 외에도 Spanner 데이터베이스/SQL 드라이버를 사용하여 동일한 SQL 문을 프로그래매틱 방식으로 실행할 수 있습니다.

다음 함수와 구조체는 SQL 쿼리를 실행하는 데 사용됩니다.

• DB 구조체의 QueryContext 함수: 쿼리 또는 THEN RETURN 절이 있는 DML 문과 같이 행을 반환하는 SQL 문을 실행하는 데 사용합니다.
• Rows 구조체: SQL 문으로 반환된 데이터에 액세스하려면 사용합니다.

다음 예시에서는 QueryContext 함수를 사용합니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryData(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	rows, err := db.QueryContext(ctx,
		`SELECT SingerId, AlbumId, AlbumTitle
		FROM Albums
		ORDER BY SingerId, AlbumId`)
	defer rows.Close()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var title string
		err = rows.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryDataPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	rows, err := db.QueryContext(ctx,
		`select singer_id, album_id, album_title
		from albums
		order by singer_id, album_id`)
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var title string
		err = rows.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go query projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go querypg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

1 1 Total Junk
1 2 Go, Go, Go
2 1 Green
2 2 Forever Hold Your Peace
2 3 Terrified

SQL 매개변수를 사용하여 쿼리

애플리케이션에 자주 실행되는 쿼리가 있는 경우 이를 매개변수화하여 성능을 개선할 수 있습니다. 매개변수화된 결과 쿼리를 캐시하고 다시 사용할 수 있으므로 컴파일 비용이 절감됩니다. 자세한 내용은 쿼리 매개변수를 사용하여 자주 실행되는 쿼리 속도 향상을 참조하세요.

다음 예시에서는 WHERE 절의 매개변수를 사용하여 LastName의 특정 값이 포함된 레코드를 쿼리합니다.

Spanner 데이터베이스/SQL 드라이버는 위치 쿼리 파라미터와 이름 지정 쿼리 파라미터를 모두 지원합니다. SQL 문의 ?는 위치 쿼리 파라미터를 나타냅니다. 쿼리 파라미터 값을 QueryContext 함수에 추가 인수로 전달합니다. 예를 들면 다음과 같습니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryDataWithParameter(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	rows, err := db.QueryContext(ctx,
		`SELECT SingerId, FirstName, LastName
		FROM Singers
		WHERE LastName = ?`, "Garcia")
	defer rows.Close()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId int64
		var firstName, lastName string
		err = rows.Scan(&singerId, &firstName, &lastName)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, firstName, lastName)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryDataWithParameterPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	rows, err := db.QueryContext(ctx,
		`select singer_id, first_name, last_name
		from singers
		where last_name = ?`, "Garcia")
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId int64
		var firstName, lastName string
		err = rows.Scan(&singerId, &firstName, &lastName)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, firstName, lastName)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go querywithparameter projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go querywithparameterpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

12 Melissa Garcia

데이터베이스 스키마 업데이트

Albums 테이블에 MarketingBudget이라는 새 열을 추가해야 한다고 가정합니다. 기존 테이블에 새 열을 추가하려면 데이터베이스 스키마를 업데이트해야 합니다. Spanner는 데이터베이스에서 트래픽이 계속 처리되는 동안 데이터베이스의 스키마 업데이트를 지원합니다. 스키마 업데이트 시 데이터베이스를 오프라인으로 전환할 필요가 없고 전체 테이블 또는 열을 잠그지 않습니다. 스키마 업데이트 중에도 데이터베이스에 계속 데이터를 쓸 수 있습니다. 스키마 업데이트에서 지원되는 스키마 업데이트와 스키마 변경 성능에 대해 자세히 알아보세요.

열 추가

Google Cloud CLI를 사용하여 명령줄에서 열을 추가하거나 Spanner 데이터베이스/SQL 드라이버를 사용해서 프로그래매틱 방식으로 열을 추가할 수 있습니다.

명령줄에서

다음과 같은 ALTER TABLE 명령어를 사용하여 테이블에 새 열을 추가합니다.

GoogleSQL

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'

PostgreSQL

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='alter table albums add column marketing_budget bigint'

다음과 같이 표시됩니다.

Schema updating...done.

Spanner 데이터베이스/SQL 드라이버 사용

ExecContext 함수를 사용하여 스키마를 수정합니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func AddColumn(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	_, err = db.ExecContext(ctx,
		`ALTER TABLE Albums
			ADD COLUMN MarketingBudget INT64`)
	if err != nil {
		return err
	}

	fmt.Fprint(w, "Added MarketingBudget column\n")
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func AddColumnPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	_, err = db.ExecContext(ctx,
		`alter table albums
			add column marketing_budget bigint`)
	if err != nil {
		return err
	}

	_, _ = fmt.Fprint(w, "Added marketing_budget column\n")
	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go addcolumn projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go addcolumnpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

Added MarketingBudget column.

DDL 일괄 실행

여러 스키마 수정을 일괄 실행하는 것이 좋습니다. START BATCH DDL 및 RUN BATCH 명령어를 사용하여 DDL 일괄 처리를 실행합니다. 다음 예시에서는 한 번에 두 개의 테이블을 만듭니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func DdlBatch(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Executing multiple DDL statements as one batch is
	// more efficient than executing each statement
	// individually.
	conn, err := db.Conn(ctx)
	defer conn.Close()

	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Venues (
			VenueId     INT64 NOT NULL,
			Name        STRING(1024),
			Description JSON,
		) PRIMARY KEY (VenueId)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`CREATE TABLE Concerts (
			ConcertId INT64 NOT NULL,
			VenueId   INT64 NOT NULL,
			SingerId  INT64 NOT NULL,
			StartTime TIMESTAMP,
			EndTime   TIMESTAMP,
			CONSTRAINT Fk_Concerts_Venues FOREIGN KEY
				(VenueId) REFERENCES Venues (VenueId),
			CONSTRAINT Fk_Concerts_Singers FOREIGN KEY
				(SingerId) REFERENCES Singers (SingerId),
		) PRIMARY KEY (ConcertId)`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	fmt.Fprint(w, "Added Venues and Concerts tables\n")
	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func DdlBatchPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Executing multiple DDL statements as one batch is
	// more efficient than executing each statement
	// individually.
	conn, err := db.Conn(ctx)
	defer func() { _ = conn.Close() }()

	if _, err := conn.ExecContext(ctx, "start batch ddl"); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table venues (
			venue_id    bigint not null primary key,
			name        varchar(1024),
			description jsonb
		)`); err != nil {
		return err
	}
	if _, err := conn.ExecContext(ctx,
		`create table concerts (
			concert_id bigint not null primary key,
			venue_id   bigint not null,
			singer_id  bigint not null,
			start_time timestamptz,
			end_time   timestamptz,
			constraint fk_concerts_venues foreign key
				(venue_id) references venues (venue_id),
			constraint fk_concerts_singers foreign key
				(singer_id) references singers (singer_id)
		)`); err != nil {
		return err
	}
	// `run batch` sends the DDL statements to Spanner and blocks until
	// all statements have finished executing.
	if _, err := conn.ExecContext(ctx, "run batch"); err != nil {
		return err
	}

	_, _ = fmt.Fprint(w, "Added venues and concerts tables\n")
	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go ddlbatch projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go ddlbatchpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

Added Venues and Concerts tables.

새 열에 데이터 쓰기

다음 코드는 새 열에 데이터를 씁니다. 이 코드는 MarketingBudget을 Albums(1, 1)로 키가 지정된 행에서는 100000으로, Albums(2, 2)로 키가 지정된 행에서는 500000으로 설정합니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func UpdateDataWithMutations(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer conn.Close()

	cols := []string{"SingerId", "AlbumId", "MarketingBudget"}
	mutations := []*spanner.Mutation{
		spanner.Update("Albums", cols, []interface{}{1, 1, 100000}),
		spanner.Update("Albums", cols, []interface{}{2, 2, 500000}),
	}
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, "+
				"expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	fmt.Fprintf(w, "Updated %v albums\n", len(mutations))

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func UpdateDataWithMutationsPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Get a connection so that we can get access to the Spanner specific
	// connection interface SpannerConn.
	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	defer func() { _ = conn.Close() }()

	cols := []string{"singer_id", "album_id", "marketing_budget"}
	mutations := []*spanner.Mutation{
		spanner.Update("albums", cols, []interface{}{1, 1, 100000}),
		spanner.Update("albums", cols, []interface{}{2, 2, 500000}),
	}
	if err := conn.Raw(func(driverConn interface{}) error {
		spannerConn, ok := driverConn.(spannerdriver.SpannerConn)
		if !ok {
			return fmt.Errorf("unexpected driver connection %v, "+
				"expected SpannerConn", driverConn)
		}
		_, err = spannerConn.Apply(ctx, mutations)
		return err
	}); err != nil {
		return err
	}
	_, _ = fmt.Fprintf(w, "Updated %v albums\n", len(mutations))

	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go update projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go updatepg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

Updated 2 albums

방금 쓴 값을 가져오기 위해 SQL 쿼리를 실행할 수도 있습니다.

다음 예시에서는 QueryContext 함수를 사용하여 쿼리를 실행합니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryNewColumn(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	rows, err := db.QueryContext(ctx,
		`SELECT SingerId, AlbumId, MarketingBudget
		FROM Albums
		ORDER BY SingerId, AlbumId`)
	defer rows.Close()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var marketingBudget sql.NullInt64
		err = rows.Scan(&singerId, &albumId, &marketingBudget)
		if err != nil {
			return err
		}
		budget := "NULL"
		if marketingBudget.Valid {
			budget = fmt.Sprintf("%v", marketingBudget.Int64)
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, budget)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func QueryNewColumnPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	rows, err := db.QueryContext(ctx,
		`select singer_id, album_id, marketing_budget
		from albums
		order by singer_id, album_id`)
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	for rows.Next() {
		var singerId, albumId int64
		var marketingBudget sql.NullInt64
		err = rows.Scan(&singerId, &albumId, &marketingBudget)
		if err != nil {
			return err
		}
		budget := "null"
		if marketingBudget.Valid {
			budget = fmt.Sprintf("%v", marketingBudget.Int64)
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, budget)
	}
	if rows.Err() != nil {
		return rows.Err()
	}
	return rows.Close()
}

이 쿼리를 실행하려면 다음 명령어를 실행합니다.

GoogleSQL

go run getting_started_guide.go querymarketingbudget projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go querymarketingbudgetpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

다음과 같이 표시됩니다.

1 1 100000
1 2 null
2 1 null
2 2 500000
2 3 null

데이터 업데이트

읽기-쓰기 트랜잭션에서 DML을 사용하여 데이터를 업데이트할 수 있습니다.

DB.BeginTx를 호출하여 데이터베이스/SQL에서 읽기-쓰기 트랜잭션을 실행합니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteWithTransactionUsingDml(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Transfer marketing budget from one album to another. We do it in a
	// transaction to ensure that the transfer is atomic.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{})
	if err != nil {
		return err
	}
	// The Spanner database/sql driver supports both positional and named
	// query parameters. This query uses named query parameters.
	const selectSql = "SELECT MarketingBudget " +
		"FROM Albums " +
		"WHERE SingerId = @singerId and AlbumId = @albumId"
	// Get the marketing_budget of singer 2 / album 2.
	row := tx.QueryRowContext(ctx, selectSql,
		sql.Named("singerId", 2), sql.Named("albumId", 2))
	var budget2 int64
	if err := row.Scan(&budget2); err != nil {
		tx.Rollback()
		return err
	}
	const transfer = 20000
	// The transaction will only be committed if this condition still holds
	// at the time of commit. Otherwise, the transaction will be aborted.
	if budget2 >= transfer {
		// Get the marketing_budget of singer 1 / album 1.
		row := tx.QueryRowContext(ctx, selectSql,
			sql.Named("singerId", 1), sql.Named("albumId", 1))
		var budget1 int64
		if err := row.Scan(&budget1); err != nil {
			tx.Rollback()
			return err
		}
		// Transfer part of the marketing budget of Album 2 to Album 1.
		budget1 += transfer
		budget2 -= transfer
		const updateSql = "UPDATE Albums " +
			"SET MarketingBudget = @budget " +
			"WHERE SingerId = @singerId and AlbumId = @albumId"
		// Start a DML batch and execute it as part of the current transaction.
		if _, err := tx.ExecContext(ctx, "start batch dml"); err != nil {
			tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql,
			sql.Named("singerId", 1),
			sql.Named("albumId", 1),
			sql.Named("budget", budget1)); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql,
			sql.Named("singerId", 2),
			sql.Named("albumId", 2),
			sql.Named("budget", budget2)); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			tx.Rollback()
			return err
		}
		// `run batch` sends the DML statements to Spanner.
		// The result contains the total affected rows across the entire batch.
		result, err := tx.ExecContext(ctx, "run batch")
		if err != nil {
			tx.Rollback()
			return err
		}
		if affected, err := result.RowsAffected(); err != nil {
			tx.Rollback()
			return err
		} else if affected != 2 {
			// The batch should update 2 rows.
			tx.Rollback()
			return fmt.Errorf("unexpected number of rows affected: %v", affected)
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}

	fmt.Fprintln(w, "Transferred marketing budget from Album 2 to Album 1")

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func WriteWithTransactionUsingDmlPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Transfer marketing budget from one album to another. We do it in a
	// transaction to ensure that the transfer is atomic.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{})
	if err != nil {
		return err
	}
	const selectSql = "select marketing_budget " +
		"from albums " +
		"where singer_id = $1 and album_id = $2"
	// Get the marketing_budget of singer 2 / album 2.
	row := tx.QueryRowContext(ctx, selectSql, 2, 2)
	var budget2 int64
	if err := row.Scan(&budget2); err != nil {
		_ = tx.Rollback()
		return err
	}
	const transfer = 20000
	// The transaction will only be committed if this condition still holds
	// at the time of commit. Otherwise, the transaction will be aborted.
	if budget2 >= transfer {
		// Get the marketing_budget of singer 1 / album 1.
		row := tx.QueryRowContext(ctx, selectSql, 1, 1)
		var budget1 int64
		if err := row.Scan(&budget1); err != nil {
			_ = tx.Rollback()
			return err
		}
		// Transfer part of the marketing budget of Album 2 to Album 1.
		budget1 += transfer
		budget2 -= transfer
		const updateSql = "update albums " +
			"set marketing_budget = $1 " +
			"where singer_id = $2 and album_id = $3"
		// Start a DML batch and execute it as part of the current transaction.
		if _, err := tx.ExecContext(ctx, "start batch dml"); err != nil {
			_ = tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql, budget1, 1, 1); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			_ = tx.Rollback()
			return err
		}
		if _, err := tx.ExecContext(ctx, updateSql, budget2, 2, 2); err != nil {
			_, _ = tx.ExecContext(ctx, "abort batch")
			_ = tx.Rollback()
			return err
		}
		// `run batch` sends the DML statements to Spanner.
		// The result contains the total affected rows across the entire batch.
		result, err := tx.ExecContext(ctx, "run batch")
		if err != nil {
			_ = tx.Rollback()
			return err
		}
		if affected, err := result.RowsAffected(); err != nil {
			_ = tx.Rollback()
			return err
		} else if affected != 2 {
			// The batch should update 2 rows.
			_ = tx.Rollback()
			return fmt.Errorf("unexpected number of rows affected: %v", affected)
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}

	_, _ = fmt.Fprintln(w, "Transferred marketing budget from Album 2 to Album 1")

	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go writewithtransactionusingdml projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go writewithtransactionusingdmlpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

트랜잭션 태그 및 요청 태그

트랜잭션 태그 및 요청 태그를 사용하여 Spanner에서 트랜잭션 및 쿼리를 문제 해결할 수 있습니다. spannerdriver.BeginReadWriteTransaction 함수에 추가 트랜잭션 옵션을 전달할 수 있습니다.

spannerdriver.ExecOptions를 사용하여 SQL 문에 추가 쿼리 옵션을 전달합니다. 예를 들면 다음과 같습니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func Tags(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Use the spannerdriver.BeginReadWriteTransaction function
	// to specify specific Spanner options, such as transaction tags.
	tx, err := spannerdriver.BeginReadWriteTransaction(ctx, db,
		spannerdriver.ReadWriteTransactionOptions{
			TransactionOptions: spanner.TransactionOptions{
				TransactionTag: "example-tx-tag",
			},
		})
	if err != nil {
		return err
	}

	// Pass in an argument of type spannerdriver.ExecOptions to supply
	// additional options for a statement.
	row := tx.QueryRowContext(ctx, "SELECT MarketingBudget "+
		"FROM Albums "+
		"WHERE SingerId=? and AlbumId=?",
		spannerdriver.ExecOptions{
			QueryOptions: spanner.QueryOptions{RequestTag: "query-marketing-budget"},
		}, 1, 1)
	var budget int64
	if err := row.Scan(&budget); err != nil {
		tx.Rollback()
		return err
	}

	// Reduce the marketing budget by 10% if it is more than 1,000.
	if budget > 1000 {
		budget = int64(float64(budget) - float64(budget)*0.1)
		if _, err := tx.ExecContext(ctx,
			`UPDATE Albums SET MarketingBudget=@budget 
               WHERE SingerId=@singerId AND AlbumId=@albumId`,
			spannerdriver.ExecOptions{
				QueryOptions: spanner.QueryOptions{RequestTag: "reduce-marketing-budget"},
			},
			sql.Named("budget", budget),
			sql.Named("singerId", 1),
			sql.Named("albumId", 1)); err != nil {
			tx.Rollback()
			return err
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}
	fmt.Fprintln(w, "Reduced marketing budget")

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func TagsPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Use the spannerdriver.BeginReadWriteTransaction function
	// to specify specific Spanner options, such as transaction tags.
	tx, err := spannerdriver.BeginReadWriteTransaction(ctx, db,
		spannerdriver.ReadWriteTransactionOptions{
			TransactionOptions: spanner.TransactionOptions{
				TransactionTag: "example-tx-tag",
			},
		})
	if err != nil {
		return err
	}

	// Pass in an argument of type spannerdriver.ExecOptions to supply
	// additional options for a statement.
	row := tx.QueryRowContext(ctx, "select marketing_budget "+
		"from albums "+
		"where singer_id=? and album_id=?",
		spannerdriver.ExecOptions{
			QueryOptions: spanner.QueryOptions{RequestTag: "query-marketing-budget"},
		}, 1, 1)
	var budget int64
	if err := row.Scan(&budget); err != nil {
		_ = tx.Rollback()
		return err
	}

	// Reduce the marketing budget by 10% if it is more than 1,000.
	if budget > 1000 {
		budget = int64(float64(budget) - float64(budget)*0.1)
		if _, err := tx.ExecContext(ctx,
			`update albums set marketing_budget=$1 
               where singer_id=$2 and album_id=$3`,
			spannerdriver.ExecOptions{
				QueryOptions: spanner.QueryOptions{RequestTag: "reduce-marketing-budget"},
			}, budget, 1, 1); err != nil {
			_ = tx.Rollback()
			return err
		}
	}
	// Commit the current transaction.
	if err := tx.Commit(); err != nil {
		return err
	}
	_, _ = fmt.Fprintln(w, "Reduced marketing budget")

	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go tags projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go tagspg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

읽기 전용 트랜잭션을 사용하여 데이터 검색

같은 타임스탬프에서 읽기를 하나 이상 실행한다고 가정해 봅시다. 읽기 전용 트랜잭션은 트랜잭션 커밋 기록의 일관된 프리픽스를 관찰하므로 애플리케이션이 항상 일관된 데이터를 가져옵니다. TxOptions.ReadOnly 필드를 true로 설정하여 읽기 전용 트랜잭션을 실행합니다.

다음은 같은 읽기 전용 트랜잭션에서 쿼리를 실행하고 읽기를 수행하는 방법을 보여줍니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func ReadOnlyTransaction(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Start a read-only transaction by supplying additional transaction options.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})

	albumsOrderedById, err := tx.QueryContext(ctx,
		`SELECT SingerId, AlbumId, AlbumTitle
		FROM Albums
		ORDER BY SingerId, AlbumId`)
	defer albumsOrderedById.Close()
	if err != nil {
		return err
	}
	for albumsOrderedById.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedById.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	albumsOrderedTitle, err := tx.QueryContext(ctx,
		`SELECT SingerId, AlbumId, AlbumTitle
		FROM Albums
		ORDER BY AlbumTitle`)
	defer albumsOrderedTitle.Close()
	if err != nil {
		return err
	}
	for albumsOrderedTitle.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedTitle.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	// End the read-only transaction by calling Commit.
	return tx.Commit()
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func ReadOnlyTransactionPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Start a read-only transaction by supplying additional transaction options.
	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
	if err != nil {
		return err
	}

	albumsOrderedById, err := tx.QueryContext(ctx,
		`select singer_id, album_id, album_title
		from albums
		order by singer_id, album_id`)
	defer func() { _ = albumsOrderedById.Close() }()
	if err != nil {
		return err
	}
	for albumsOrderedById.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedById.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	albumsOrderedTitle, err := tx.QueryContext(ctx,
		`select singer_id, album_id, album_title
		from albums
		order by album_title`)
	defer func() { _ = albumsOrderedTitle.Close() }()
	if err != nil {
		return err
	}
	for albumsOrderedTitle.Next() {
		var singerId, albumId int64
		var title string
		err = albumsOrderedTitle.Scan(&singerId, &albumId, &title)
		if err != nil {
			return err
		}
		_, _ = fmt.Fprintf(w, "%v %v %v\n", singerId, albumId, title)
	}

	// End the read-only transaction by calling Commit.
	return tx.Commit()
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go readonlytransaction projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go readonlytransactionpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

결과는 다음과 같습니다.

    1 1 Total Junk
    1 2 Go, Go, Go
    2 1 Green
    2 2 Forever Hold Your Peace
    2 3 Terrified
    2 2 Forever Hold Your Peace
    1 2 Go, Go, Go
    2 1 Green
    2 3 Terrified
    1 1 Total Junk

파티션을 나눈 쿼리 및 Data Boost

partitionQuery API는 쿼리를 더 작은 부분이나 파티션으로 나누고 여러 머신을 사용하여 동시에 파티션을 가져옵니다. 각 파티션은 파티션 토큰으로 식별됩니다. PartitionQuery API는 전체 데이터베이스 내보내기 또는 스캔과 같은 대량 작업에 사용되므로 표준 쿼리 API보다 지연 시간이 깁니다.

Data Boost를 사용하면 프로비저닝된 Spanner 인스턴스의 기존 워크로드에 거의 영향을 주지 않고 분석 쿼리와 데이터 내보내기를 실행할 수 있습니다. Data Boost는 파티션을 나눈 쿼리만 지원합니다.

다음 예tl는 데이터베이스/SQL 드라이버를 사용하여 Data Boost로 파티션된 쿼리를 실행하는 방법을 보여줍니다.

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"
	"slices"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func DataBoost(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	// Run a partitioned query that uses Data Boost.
	rows, err := db.QueryContext(ctx,
		"SELECT SingerId, FirstName, LastName from Singers",
		spannerdriver.ExecOptions{
			PartitionedQueryOptions: spannerdriver.PartitionedQueryOptions{
				// AutoPartitionQuery instructs the Spanner database/sql driver to
				// automatically partition the query and execute each partition in parallel.
				// The rows are returned as one result set in undefined order.
				AutoPartitionQuery: true,
			},
			QueryOptions: spanner.QueryOptions{
				// Set DataBoostEnabled to true to enable DataBoost.
				// See https://cloud.google.com/spanner/docs/databoost/databoost-overview
				// for more information.
				DataBoostEnabled: true,
			},
		})
	defer rows.Close()
	if err != nil {
		return err
	}
	type Singer struct {
		SingerId  int64
		FirstName string
		LastName  string
	}
	var singers []Singer
	for rows.Next() {
		var singer Singer
		err = rows.Scan(&singer.SingerId, &singer.FirstName, &singer.LastName)
		if err != nil {
			return err
		}
		singers = append(singers, singer)
	}
	// Queries that use the AutoPartition option return rows in undefined order,
	// so we need to sort them in memory to guarantee the output order.
	slices.SortFunc(singers, func(a, b Singer) int {
		return int(a.SingerId - b.SingerId)
	})
	for _, s := range singers {
		fmt.Fprintf(w, "%v %v %v\n", s.SingerId, s.FirstName, s.LastName)
	}

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"
	"slices"

	"cloud.google.com/go/spanner"
	spannerdriver "github.com/googleapis/go-sql-spanner"
)

func DataBoostPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	// Run a partitioned query that uses Data Boost.
	rows, err := db.QueryContext(ctx,
		"select singer_id, first_name, last_name from singers",
		spannerdriver.ExecOptions{
			PartitionedQueryOptions: spannerdriver.PartitionedQueryOptions{
				// AutoPartitionQuery instructs the Spanner database/sql driver to
				// automatically partition the query and execute each partition in parallel.
				// The rows are returned as one result set in undefined order.
				AutoPartitionQuery: true,
			},
			QueryOptions: spanner.QueryOptions{
				// Set DataBoostEnabled to true to enable DataBoost.
				// See https://cloud.google.com/spanner/docs/databoost/databoost-overview
				// for more information.
				DataBoostEnabled: true,
			},
		})
	defer func() { _ = rows.Close() }()
	if err != nil {
		return err
	}
	type Singer struct {
		SingerId  int64
		FirstName string
		LastName  string
	}
	var singers []Singer
	for rows.Next() {
		var singer Singer
		err = rows.Scan(&singer.SingerId, &singer.FirstName, &singer.LastName)
		if err != nil {
			return err
		}
		singers = append(singers, singer)
	}
	// Queries that use the AutoPartition option return rows in undefined order,
	// so we need to sort them in memory to guarantee the output order.
	slices.SortFunc(singers, func(a, b Singer) int {
		return int(a.SingerId - b.SingerId)
	})
	for _, s := range singers {
		_, _ = fmt.Fprintf(w, "%v %v %v\n", s.SingerId, s.FirstName, s.LastName)
	}

	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go databoost projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go databoostpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

Partitioned DML

Partitioned DML은 다음과 같은 유형의 일괄 업데이트와 삭제를 위해 설계되었습니다.

• 정기적 클린업 및 가비지 컬렉션:
• 새 열을 기본값으로 백필:

GoogleSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func PartitionedDml(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer db.Close()

	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	// Enable Partitioned DML on this connection.
	if _, err := conn.ExecContext(ctx, "SET AUTOCOMMIT_DML_MODE='PARTITIONED_NON_ATOMIC'"); err != nil {
		return fmt.Errorf("failed to change DML mode to Partitioned_Non_Atomic: %v", err)
	}
	// Back-fill a default value for the MarketingBudget column.
	res, err := conn.ExecContext(ctx, "UPDATE Albums SET MarketingBudget=0 WHERE MarketingBudget IS NULL")
	if err != nil {
		return err
	}
	affected, err := res.RowsAffected()
	if err != nil {
		return fmt.Errorf("failed to get affected rows: %v", err)
	}

	// Partitioned DML returns the minimum number of records that were affected.
	fmt.Fprintf(w, "Updated at least %v albums\n", affected)

	// Closing the connection will return it to the connection pool. The DML mode will automatically be reset to the
	// default TRANSACTIONAL mode when the connection is returned to the pool, so we do not need to change it back
	// manually.
	_ = conn.Close()

	return nil
}

PostgreSQL

import (
	"context"
	"database/sql"
	"fmt"
	"io"

	_ "github.com/googleapis/go-sql-spanner"
)

func PartitionedDmlPostgreSQL(ctx context.Context, w io.Writer, databaseName string) error {
	db, err := sql.Open("spanner", databaseName)
	if err != nil {
		return err
	}
	defer func() { _ = db.Close() }()

	conn, err := db.Conn(ctx)
	if err != nil {
		return err
	}
	// Enable Partitioned DML on this connection.
	if _, err := conn.ExecContext(ctx, "set autocommit_dml_mode='partitioned_non_atomic'"); err != nil {
		return fmt.Errorf("failed to change DML mode to Partitioned_Non_Atomic: %v", err)
	}
	// Back-fill a default value for the marketing_budget column.
	res, err := conn.ExecContext(ctx, "update albums set marketing_budget=0 where marketing_budget is null")
	if err != nil {
		return err
	}
	affected, err := res.RowsAffected()
	if err != nil {
		return fmt.Errorf("failed to get affected rows: %v", err)
	}

	// Partitioned DML returns the minimum number of records that were affected.
	_, _ = fmt.Fprintf(w, "Updated at least %v albums\n", affected)

	// Closing the connection will return it to the connection pool. The DML mode will automatically be reset to the
	// default TRANSACTIONAL mode when the connection is returned to the pool, so we do not need to change it back
	// manually.
	_ = conn.Close()

	return nil
}

다음 명령어를 사용하여 예시를 실행합니다.

GoogleSQL

go run getting_started_guide.go pdml projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

PostgreSQL

go run getting_started_guide.go pdmlpg projects/GCLOUD_PROJECT/instances/test-instance/databases/example-db

삭제

이 튜토리얼에서 사용한 리소스에 대한 추가 비용이 Cloud Billing 계정에 청구되지 않도록 하려면 데이터베이스와 새로 만든 인스턴스를 삭제합니다.

데이터베이스 삭제

인스턴스를 삭제하면 인스턴스 내의 모든 데이터베이스가 자동으로 삭제됩니다. 다음 단계는 인스턴스를 삭제하지 않고 데이터베이스를 삭제하는 방법을 보여줍니다. 인스턴스에 대한 비용은 여전히 발생합니다.

명령줄에서

gcloud spanner databases delete example-db --instance=test-instance

Google Cloud 콘솔 사용

1. Google Cloud 콘솔에서 Spanner 인스턴스 페이지로 이동합니다.

   인스턴스 페이지로 이동

2. 인스턴스를 클릭합니다.

3. 삭제할 데이터베이스를 클릭합니다.

4. 데이터베이스 세부정보 페이지에서 삭제를 클릭합니다.

5. 데이터베이스 삭제 여부를 확인하고 삭제를 클릭합니다.

인스턴스 삭제

인스턴스를 삭제하면 해당 인스턴스에서 만든 모든 데이터베이스가 자동으로 삭제됩니다.

명령줄에서

gcloud spanner instances delete test-instance

Google Cloud 콘솔 사용

1. Google Cloud 콘솔에서 Spanner 인스턴스 페이지로 이동합니다.

   인스턴스 페이지로 이동

2. 인스턴스를 클릭합니다.

3. 삭제를 클릭합니다.

4. 인스턴스 삭제 여부를 확인하고 삭제를 클릭합니다.

다음 단계

• 가상 머신 인스턴스에서 Spanner에 액세스하는 방법을 알아봅니다.

• 클라이언트 라이브러리를 사용하여 Cloud 서비스에 인증에서 사용자 인증 정보의 승인 및 인증에 대해 알아봅니다.

• Spanner 스키마 설계 권장사항에 대해 자세히 알아봅니다.