extend-sql-database

Last updated on May 21, 2026

注意

The Extend SQL Database is currently in closed alpha.

Overview

Extend SQL Database allows Extend Apps to store data in an Amazon Aurora PostgreSQL database. It provides a managed, scalable database solution that eliminates the complexity of setting up and maintaining your own database infrastructure. This allows developers to focus on building innovative features and functionality.

Extend SQL Database can be attached to all types of Extend Apps. This unlocks a wide range of use cases that require persistent data storage capabilities with ACID compliance and relational data modeling.

Provision Extend SQL Cluster

You can provision the Extend SQL cluster once you have been approved as a Closed Alpha tester. This action can be performed at the Publisher or Studio namespace level.

1. Go to the Extend menu and click Extend Databases. Click Create Cluster on the Extend SQL Database card.

   

2. Select the database profile based on your needs then click the Create SQL Database button.

   

3. Wait for the cluster to be provisioned for 5-10 minutes.

   

4. The status changes to AVAILABLE once the cluster is provisioned.

   

5. To integrate your Extend App with the Extend SQL Database, proceed to the Setting up Extend SQL Database for your Extend App section.

Update Extend SQL Cluster Database Profile

You can update the database profile if you need to change the cluster size. This action can be performed at the Publisher or Studio namespace level.

1. In the Extend → Extend Databases menu, click Manage Cluster on the SQL card, then find and click the Edit button.

   

2. Select the Extend SQL Database profile based on your needs then click the Update button.

   

3. In the confirmation dialog, type UPDATE to confirm the update action and click the Update button.

   

4. Wait for the cluster to be updated.

   

5. The status changes back to AVAILABLE once the cluster is updated.

   

Delete Extend SQL Cluster

You can delete the cluster when you no longer need it and it can only be deleted when it is in AVAILABLE status. This action can be performed at the Publisher or Studio namespace level.

1. In the Extend → Extend Databases menu, click Manage Cluster in SQL Card, then find and click the Delete Cluster button.

   

2. In the confirmation dialog, type DELETE to confirm the deletion and click the Delete Instance button.

   

3. The page returns to the Extend → Extend Databases page once the cluster is deleted.

Setting up Extend SQL Database for your Extend App

This action can be performed at the Game namespace level, and you can only create the database when the SQL cluster is in AVAILABLE status.

1. In your Extend App details, switch to the Databases tab and click the Set Up button on the SQL Database card.

   

2. Enter your database name, username, and password, check the acknowledgment to manage the credential securely, then click the Add button.

   

3. Take note of the information in the Database Summary page.

   

   The database host, name, username, and password are automatically added to your Extend App secrets and variables as SQLDB_HOST, SQLDB_DATABASE_NAME, SQLDB_USERNAME, and SQLDB_PASSWORD respectively.

Connecting your Extend App to Extend SQL Database

1. Add a PostgreSQL driver to your Extend App.

   Go

   Run the following go get command to get the pgx PostgreSQL driver and connection pool package.

   go get github.com/jackc/pgx/v5

   It is recommended to run the go mod tidy command afterward.

   go mod tidy

2. Configure the PostgreSQL driver to connect to the SQL Database. Use the SQLDB_HOST, SQLDB_USERNAME, SQLDB_PASSWORD, SQLDB_DATABASE_NAME, and SQLDB_CA_CERT_FILE_PATH environment variables to construct the connection string.

   Go

   import (
       ...
       "context"
       "net/url"
       "time"
       "github.com/jackc/pgx/v5/pgxpool"
       ...
   )
   
   ...
   
   ctx := context.Background()
   sqlDbHost := os.Getenv("SQLDB_HOST")
   sqlDbUsername := os.Getenv("SQLDB_USERNAME")
   sqlDbPassword := os.Getenv("SQLDB_PASSWORD")
   sqlDbDatabaseName := os.Getenv("SQLDB_DATABASE_NAME")
   sqlDbCaCertFilePath := os.Getenv("SQLDB_CA_CERT_FILE_PATH")
   
   connectionString := fmt.Sprintf(
       "postgresql://%s:%s@%s/%s?sslmode=verify-full&sslrootcert=%s",
       url.QueryEscape(sqlDbUsername),
       url.QueryEscape(sqlDbPassword),
       sqlDbHost,
       sqlDbDatabaseName,
       sqlDbCaCertFilePath,
   )
   
   poolConfig, err := pgxpool.ParseConfig(connectionString)
   if err != nil {
       // replace with proper error handling in production
   }
   
   // Configure connection pool
   poolConfig.MaxConns = 30
   poolConfig.MinConns = 5
   poolConfig.MaxConnLifetime = time.Hour
   
   db, err := pgxpool.NewWithConfig(ctx, poolConfig)
   if err != nil {
       // replace with proper error handling in production
   }
   defer db.Close()
   
   // Validate the connection
   if err := db.Ping(ctx); err != nil {
       // replace with proper error handling in production
   }
   
   ...

   important

   TLS is enabled by default on the cluster. The option sslmode must be set to one of: allow, prefer, require, verify-ca, or verify-full. The TLS certificate is automatically added and exposed by the SQLDB_CA_CERT_FILE_PATH environment variable. The certificate is required for verify-ca and verify-full modes.

3. Use the database connection to execute SQL queries.

   Go

   ...
   
   ctx := context.Background()
   
   // Create a table
   _, err = db.Exec(ctx, `
       CREATE TABLE IF NOT EXISTS users (
           id SERIAL PRIMARY KEY,
           username VARCHAR(50) UNIQUE NOT NULL,
           email VARCHAR(100) UNIQUE NOT NULL,
           created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
       )
   `)
   if err != nil {
       // replace with proper error handling in production
   }
   
   // Insert data
   _, err = db.Exec(
       ctx,
       "INSERT INTO users (username, email) VALUES ($1, $2)",
       "player1",
       "player1@example.com",
   )
   if err != nil {
       // replace with proper error handling in production
   }
   
   // Query data
   var username string
   var email string
   err = db.QueryRow(ctx, "SELECT username, email FROM users WHERE id = $1", 1).Scan(&username, &email)
   if err != nil {
       // replace with proper error handling in production
   }
   
   ...

   ヒント

   To learn more about working with PostgreSQL in Go, check out the official PostgreSQL documentation and the pgx documentation.

Accessing the Extend SQL Database through Extend TCP Tunneling

You can connect to your Extend SQL Database from a local development environment using Extend TCP Tunneling via the Extend Helper CLI. You can only perform this action when the SQL cluster is in AVAILABLE status.

1. Make sure the Extend Helper CLI is set up. Then add the following permission to the IAM client you use with it.

   • For AGS Private Cloud customers:
     • ADMIN:NAMESPACE:{namespace}:EXTEND:TUNNEL [READ]
   • For AGS Shared Cloud customers:
     • Extend > TCP Tunneling (Read)

2. Copy the Resource Name information from the SQL Database detail tab.

   

   

3. Start Extend TCP Tunneling to the Extend SQL Database using Extend Helper CLI. Pass the Resource Name information from step 2 as the --resource-name option parameter.

   extend-helper-cli tunnel --resource-name <Resource Name> --namespace <namespace> --local-port <port>

   important

   Authentication may fail if your system clock is not synchronized. Ensure your local time is accurate before running the command.

   ヒント

   You can also copy the full command from the Tunnel Command information in the SQL Database tab.

4. Make sure you have downloaded the AWS RDS TLS certificate from https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem (TLS is enabled, the certificate is required for verify-ca and verify-full modes, otherwise it is optional).

5. Use your PostgreSQL client (such as pgAdmin, DBeaver, or psql) to connect to the Extend SQL Database through the local port you specified in step 3. Use your database name, username, and password from the information you noted when setting up the database. The connection string should look like the following.

   postgresql://<username>:<password>@localhost:<port>/<database-name>?sslmode=verify-full&sslrootcert=<path-to-certs-file>

   Using psql command line:

   psql "postgresql://<username>:<password>@localhost:<port>/<database-name>?sslmode=verify-full&sslrootcert=<path-to-certs-file>"

Samples

The sample Extend App below is an Extend Service Extension guild service that stores its data in Extend SQL Database.

Go

git clone https://github.com/AccelByte/extend-service-extension-with-sql-go.git

Observability

You can monitor your SQL cluster performance through a Grafana Cloud dashboard. The dashboard provides panels displaying key performance metrics including CPU utilization, latency, IOPS, database connections, etc., allowing you to identify bottlenecks and optimize your application's database usage.

1. In the Databases tab, click the extra ... menu button, then select Database Dashboard.

   

2. A new tab opens with the Grafana Cloud login page. Log in with AccelByte credentials by clicking the Sign in with Admin Portal button.

   

3. Once you are logged in, you will see the dashboard.