feat: add Amazon Aurora DSQL storage backend

Add Aurora DSQL as a supported storage backend for OpenFGA. DSQL is a
PostgreSQL-compatible serverless database, so this implementation reuses
the existing Postgres storage layer with DSQL-specific adaptations:

- DSQL connection management via aurora-dsql-connectors/go (v0.2.0)
  with automatic IAM token refresh
- Dedicated migration files (assets/migrations/dsql/) that avoid
  partial indexes and use ASYNC index creation per DSQL requirements
- DSQL-specific SQL overrides in sqlcommon and postgres packages for
  queries that need adaptation (e.g. ReadPage ordering)
- New --datastore-engine=dsql flag and configuration path
- Integration test fixtures for DSQL

The storage interface is unchanged; DSQL plugs in as a new engine
option alongside postgres, mysql, and sqlite.

Author: amaksimo

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Try to keep listed changes to a concise bulleted list of simple explanations of changes. Aim for the amount of information needed so that readers can understand where they would look in the codebase to investigate the changes' implementation, or where they would look in the documentation to understand how to make use of the change in practice - better yet, link directly to the docs and provide detailed information there. Only elaborate if doing so is required to avoid breaking changes or experimental features from ruining someone's day.
 
 ## [Unreleased]
+### Added
+- Add Amazon Aurora DSQL as a supported storage backend.
+
 ### Changed
 - The ListObjects "pipeline" algorithm ditches its custom Pipe implementation and replaces it with Go native channels. [#2977](https://github.com/openfga/openfga/pull/2977)
 - Refactor tuple validation and manipulation functions for optimal performance. [#2984](https://github.com/openfga/openfga/pull/2984)

assets/assets.go

@@ -7,6 +7,7 @@ const (
 	MySQLMigrationDir    = "migrations/mysql"
 	PostgresMigrationDir = "migrations/postgres"
 	SqliteMigrationDir   = "migrations/sqlite"
+	DSQLMigrationDir     = "migrations/dsql"
 )
 
 // EmbedMigrations within the openfga binary.

assets/migrations/dsql/001_initialize_schema.sql

@@ -0,0 +1,60 @@
+-- +goose Up
+-- +goose NO TRANSACTION
+-- DSQL schema: uses full indexes (no partial), ASYNC index creation, C collation by default
+
+CREATE TABLE tuple (
+    store TEXT NOT NULL,
+    object_type TEXT NOT NULL,
+    object_id TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    _user TEXT NOT NULL,
+    user_type TEXT NOT NULL,
+    ulid TEXT NOT NULL,
+    inserted_at TIMESTAMPTZ NOT NULL,
+    PRIMARY KEY (store, object_type, object_id, relation, _user)
+);
+
+CREATE INDEX ASYNC idx_tuple_user ON tuple (store, object_type, object_id, relation, _user, user_type);
+CREATE UNIQUE INDEX ASYNC idx_tuple_ulid ON tuple (ulid);
+
+CREATE TABLE authorization_model (
+    store TEXT NOT NULL,
+    authorization_model_id TEXT NOT NULL,
+    type TEXT NOT NULL,
+    type_definition BYTEA,
+    PRIMARY KEY (store, authorization_model_id, type)
+);
+
+CREATE TABLE store (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL,
+    updated_at TIMESTAMPTZ,
+    deleted_at TIMESTAMPTZ
+);
+
+CREATE TABLE assertion (
+    store TEXT NOT NULL,
+    authorization_model_id TEXT NOT NULL,
+    assertions BYTEA,
+    PRIMARY KEY (store, authorization_model_id)
+);
+
+CREATE TABLE changelog (
+    store TEXT NOT NULL,
+    object_type TEXT NOT NULL,
+    object_id TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    _user TEXT NOT NULL,
+    operation INTEGER NOT NULL,
+    ulid TEXT NOT NULL,
+    inserted_at TIMESTAMPTZ NOT NULL,
+    PRIMARY KEY (store, ulid, object_type)
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS tuple;
+DROP TABLE IF EXISTS authorization_model;
+DROP TABLE IF EXISTS store;
+DROP TABLE IF EXISTS assertion;
+DROP TABLE IF EXISTS changelog;

assets/migrations/dsql/002_add_authorization_model_version.sql

@@ -0,0 +1,9 @@
+-- +goose Up
+-- +goose NO TRANSACTION
+-- DSQL: ADD COLUMN without DEFAULT, then UPDATE existing rows
+ALTER TABLE authorization_model ADD COLUMN schema_version TEXT;
+UPDATE authorization_model SET schema_version = '1.0' WHERE schema_version IS NULL;
+
+-- +goose Down
+-- +goose NO TRANSACTION
+ALTER TABLE authorization_model DROP COLUMN schema_version;

assets/migrations/dsql/003_add_reverse_lookup_index.sql

@@ -0,0 +1,7 @@
+-- +goose Up
+-- +goose NO TRANSACTION
+CREATE INDEX ASYNC idx_reverse_lookup_user ON tuple (store, object_type, relation, _user);
+
+-- +goose Down
+-- +goose NO TRANSACTION
+DROP INDEX IF EXISTS idx_reverse_lookup_user;

assets/migrations/dsql/004_add_authorization_model_serialized_protobuf.sql

@@ -0,0 +1,7 @@
+-- +goose Up
+-- +goose NO TRANSACTION
+ALTER TABLE authorization_model ADD COLUMN serialized_protobuf BYTEA;
+
+-- +goose Down
+-- +goose NO TRANSACTION
+ALTER TABLE authorization_model DROP COLUMN serialized_protobuf;

assets/migrations/dsql/005_add_conditions_to_tuples.sql

@@ -0,0 +1,14 @@
+-- +goose Up
+-- +goose NO TRANSACTION
+-- DSQL: separate ALTER statements (one DDL per transaction)
+ALTER TABLE tuple ADD COLUMN condition_name TEXT;
+ALTER TABLE tuple ADD COLUMN condition_context BYTEA;
+ALTER TABLE changelog ADD COLUMN condition_name TEXT;
+ALTER TABLE changelog ADD COLUMN condition_context BYTEA;
+
+-- +goose Down
+-- +goose NO TRANSACTION
+ALTER TABLE tuple DROP COLUMN condition_name;
+ALTER TABLE tuple DROP COLUMN condition_context;
+ALTER TABLE changelog DROP COLUMN condition_name;
+ALTER TABLE changelog DROP COLUMN condition_context;

assets/migrations/dsql/006_add_collate_index.sql

@@ -0,0 +1,17 @@
+-- +goose Up
+-- +goose NO TRANSACTION
+-- DSQL: uses C collation by default, ASYNC instead of CONCURRENTLY
+CREATE INDEX ASYNC idx_user_lookup ON tuple (
+    store,
+    _user,
+    relation,
+    object_type,
+    object_id
+);
+
+DROP INDEX IF EXISTS idx_reverse_lookup_user;
+
+-- +goose Down
+-- +goose NO TRANSACTION
+DROP INDEX IF EXISTS idx_user_lookup;
+CREATE INDEX ASYNC idx_reverse_lookup_user ON tuple (store, object_type, relation, _user);

assets/migrations/dsql/README.md

@@ -0,0 +1,39 @@
+# DSQL Migrations for OpenFGA
+
+These migrations are adapted from the PostgreSQL migrations for Aurora DSQL compatibility.
+
+## Key Differences from PostgreSQL Migrations
+
+1. **ASYNC Indexes**: All `CREATE INDEX` statements use `CREATE INDEX ASYNC` (DSQL requirement)
+2. **NO TRANSACTION**: All migrations use `-- +goose NO TRANSACTION` as DSQL runs one DDL statement per transaction
+3. **BIGINT IDENTITY**: The goose version table uses `BIGINT GENERATED BY DEFAULT AS IDENTITY`, as required by DSQL
+4. **No Partial Indexes**: DSQL doesn't support partial indexes, so full indexes are used
+
+## Migration Files
+
+| File | Description |
+|------|-------------|
+| 001_initialize_schema.sql | Creates core tables (tuple, authorization_model, store, assertion, changelog) |
+| 002_add_authorization_model_version.sql | Adds schema_version column |
+| 003_add_reverse_lookup_index.sql | Adds reverse lookup index |
+| 004_add_authorization_model_serialized_protobuf.sql | Adds serialized_protobuf column |
+| 005_add_conditions_to_tuples.sql | Adds condition columns to tuple and changelog |
+| 006_add_collate_index.sql | Adds user lookup index with C collation |
+
+## Future Consideration: Splitting Migrations
+
+Per DSQL best practices, each migration should ideally contain only one DDL statement. Currently, migrations 002 and 005 contain multiple statements:
+
+- **002**: ALTER TABLE + UPDATE (mixed DDL and DML)
+- **005**: Four ALTER TABLE statements
+
+While these work correctly with `-- +goose NO TRANSACTION` (goose executes each statement separately), consider splitting them into individual migration files if you encounter OCC errors during migration. For example:
+
+```
+005a_add_condition_name_to_tuple.sql
+005b_add_condition_context_to_tuple.sql
+005c_add_condition_name_to_changelog.sql
+005d_add_condition_context_to_changelog.sql
+```
+
+See [DSQL Development Guide](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/) for more information on DDL best practices.

cmd/run/run.go

@@ -508,6 +508,13 @@ func (s *ServerContext) datastoreConfig(config *serverconfig.Config) (storage.Op
 		if err != nil {
 			return nil, nil, fmt.Errorf("initialize sqlite datastore: %w", err)
 		}
+	case "dsql":
+		// Aurora DSQL uses PostgreSQL wire protocol with IAM authentication
+		// The postgres.New function handles dsql:// URIs automatically
+		datastore, err = postgres.New(config.Datastore.URI, dsCfg)
+		if err != nil {
+			return nil, nil, fmt.Errorf("initialize dsql datastore: %w", err)
+		}
 	default:
 		return nil, nil, fmt.Errorf("storage engine '%s' is unsupported", config.Datastore.Engine)
 	}