feat: Initial implementation of the PostgresFDW #2806

josephschorr · 2026-01-07T23:40:44Z

The PostgresFDW allows SpiceDB to be used from within Postgres via the Postgres Foreign Data Wrapper protocol, as-if Postgres was speaking to another Postgres.

It supports querying (Check, LookupResources, LookupSubjects), as well as reads (RealRelationships), writes (WriteRelationships) and schema updates (ReadSchema/WriteSchema).

These operations are performed against "virtual" tables (permissions, relationships and schema) that are placed into the Postgres and translated by this proxy.

For more information, see the README.md

This is currently experimental and subject to changes

codecov · 2026-01-07T23:45:17Z

Codecov Report

❌ Patch coverage is 36.27628% with 1061 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.53%. Comparing base (3e906b6) to head (1d80dac).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/fdw/tables/permissions.go	0.00%	308 Missing ⚠️
internal/fdw/tables/relationships.go	25.68%	161 Missing and 4 partials ⚠️
internal/fdw/pgserver.go	0.00%	100 Missing ⚠️
internal/fdw/tables/matcher.go	61.04%	61 Missing and 29 partials ⚠️
internal/fdw/tables/select.go	56.29%	61 Missing and 12 partials ⚠️
internal/fdw/cursor.go	0.00%	53 Missing ⚠️
pkg/cmd/postgresfdw.go	49.50%	45 Missing and 5 partials ⚠️
internal/fdw/session.go	0.00%	37 Missing ⚠️
internal/fdw/tables/schema.go	0.00%	37 Missing ⚠️
internal/fdw/transaction.go	0.00%	28 Missing ⚠️
... and 9 more

❌ Your project status has failed because the head coverage (74.53%) is below the target coverage (75.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2806      +/-   ##
==========================================
- Coverage   75.78%   74.53%   -1.24%     
==========================================
  Files         460      483      +23     
  Lines       55026    56691    +1665     
==========================================
+ Hits        41694    42251     +557     
- Misses      10456    11490    +1034     
- Partials     2876     2950      +74

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

tstirrat15 · 2026-01-12T15:31:36Z

docs/spicedb.md

 - [spicedb datastore](#reference-spicedb-datastore)	 - datastore operations
 - [spicedb lsp](#reference-spicedb-lsp)	 - serve language server protocol
 - [spicedb man](#reference-spicedb-man)	 - Generate man page
+- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw)	 - serve a Postgres Foreign Data Wrapper for SpiceDB


Suggested change

- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB

- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB

whitespace change

tstirrat15 · 2026-01-12T15:32:14Z

docs/spicedb.md

+Serves a Postgres-compatible interface for querying SpiceDB data using foreign data wrappers
+
+```
+spicedb postgres-fdw [flags]


General question: does this mean the postgres-fdw is now a part of the SpiceDB binary? When do we start to get concerned about the size of the binary?

Yes and the plan is any SpiceDB-adjacent systems will be as well.

I think, for now, we won't be worrying about it

tstirrat15 · 2026-01-12T15:36:05Z

internal/fdw/common/errors_test.go

+			// Verify error is properly wrapped with psql codes
+			require.Error(t, err)


I don't see these assertions

tstirrat15 · 2026-01-12T15:36:13Z

internal/fdw/common/errors_test.go

+			// Verify error is properly wrapped with psql codes
+			require.Error(t, err)


tstirrat15 · 2026-01-12T15:36:21Z

internal/fdw/common/errors_test.go

+			// Verify error is properly wrapped with psql codes
+			require.Error(t, err)


tstirrat15 · 2026-01-12T19:37:29Z

internal/fdw/pgserver.go

+
+	// slog.SetLogLoggerLevel(slog.LevelDebug)


Suggested change

// slog.SetLogLoggerLevel(slog.LevelDebug)

Added comment

tstirrat15 · 2026-01-12T19:43:02Z

internal/fdw/README.md

+SELECT resource_type, resource_id, relation, subject_type, subject_id
+FROM relationships
+WHERE resource_type = 'document'
+  AND resource_id = 'readme';


I'm not sure this is a "now" issue, but is there a way that we can help ensure that we don't have index misses on ReadRels?

No; We do not have full coverage on all shapes of read rels that are possible (and likely never will). The best we could do is warn, but that's unrelated to these changes

Yeah. My concern is that this implementation detail is kinda hidden, and that it might be relatively easy to write a postgres query that accidentally misses the indices and then it leaves the user wondering why SpiceDB is slow. I'm okay with saying that's a future problem, though.

tstirrat15 · 2026-01-12T19:45:01Z

internal/fdw/README.md

+```sql
+-- Add a new relationship
+INSERT INTO relationships (resource_type, resource_id, relation, subject_type, subject_id)
+VALUES ('document', 'readme', 'viewer', 'user', 'alice');
+```


Something I wanna make sure we clarify in external documentation if I've got it right: the transaction support here doesn't sidestep the dual-write problem, right?

No, because postgres_fdw sadly does not support two-phase commit

tstirrat15 · 2026-01-12T19:50:37Z

internal/fdw/pgserver.go

+
+// Run starts the Postgres wire protocol server on the specified endpoint.
+// It blocks until the context is cancelled or an error occurs.
+func (p *PgBackend) Run(ctx context.Context, endpoint string) error {


It doesn't have to be in this PR, but I'd wanna see observability and metrics for this as a fast follow

tstirrat15 · 2026-01-12T19:52:03Z

internal/fdw/pgserver_e2e_test.go

+	serverReady := make(chan bool)
+	go (func() {
+		serverReady <- true
+		_ = runnableServer.Run(ctx)


can use assert.NoError here if desired

Nah; I don't like error checking after cleanup in tests. It likely is returning an error (context canceled) when its forcibly shutdown at the end of the time

tstirrat15

See comments; otherwise this is looking good to me for the first implementation.

tstirrat15 · 2026-01-12T19:54:06Z

internal/fdw/pgserver_e2e_test.go

+
+	// Verify server is ready
+	retryCount := 0
+	for retryCount < 10 {


Can use https://pkg.go.dev/github.com/stretchr/testify/require#EventuallyWithT for this if desired

tstirrat15 · 2026-01-12T22:00:26Z

pkg/cmd/postgresfdw_test.go

+	prevEnv := os.Environ()
+	restore := func() {
+		restoreEnv(prevEnv)
+	}


Is this necessary with t.Setenv?

tstirrat15 · 2026-01-12T22:27:57Z

internal/fdw/tables/permissions.go

+
+		var trailerMD metadata.MD
+
+		checkResult, err := client.CheckPermission(ctx, &v1.CheckPermissionRequest{


Is the caveat context also a todo here?

Yes, it has TODOs saying so

tstirrat15 · 2026-01-12T22:37:11Z

internal/fdw/tables/relationships.go

+				ObjectType: valuesByColumnName["subject_type"],
+				ObjectId:   valuesByColumnName["subject_id"],
+			},
+			OptionalRelation: valuesByColumnName["optional_subject_relation"],


Does this mean that the optional subject relation has to be defined, or is the assumption that it'll typically come through as an empty string and be handled as an unset value?

Empty string

tstirrat15 · 2026-01-12T22:44:25Z

internal/fdw/tables/select.go

+	return nil
+}
+
+type valueOrRef struct {


Docstring on this one? Also maybe pull it towards the top or into a separate file.

Why? Its used internally

Just cuz it's used widely enough in this package. I ended up inferring it from usage as I was reading and then finding it in one of the last files I looked at and thinking that it would have been nicer to have it up front. I guess that's a review-time concern, though, so it's probably fine.

tstirrat15 · 2026-01-12T22:46:15Z

internal/fdw/tables/statement_test.go

+			t.Parallel()
+
+			require.Equal(t, tc.expectedName, tc.stmt.TableName())
+			require.Equal(t, tc.stmt.isUnsupported, tc.stmt.IsUnsupported())


What is this asserting? Is it functionally asserting that the interface is satisfied?

Its just making sure the accessors return what was defined

tstirrat15

See comments, otherwise LGTM

tstirrat15 · 2026-01-13T19:04:12Z

internal/fdw/pgserver_e2e_test.go

+	// Give PGServer time to start
+	time.Sleep(50 * time.Millisecond)


Is there a condition that we can explicitly poll here? I don't want this to become a flake source.

tstirrat15

LGTM

tstirrat15

LGTM. I'm curious to see what the ramifications of CGO are.

The PostgresFDW allows SpiceDB to be used from within Postgres via the Postgres Foreign Data Wrapper protocol, as-if Postgres was speaking to another Postgres. It supports querying (Check, LookupResources, LookupSubjects), as well as reads (RealRelationships), writes (WriteRelationships) and schema updates (ReadSchema/WriteSchema). These operations are performed against "virtual" tables (`permissions`, `relationships` and `schema`) that are placed into the Postgres and translated by this proxy. For more information, see the README.md This is currently experimental and subject to changes

josephschorr requested a review from a team as a code owner January 7, 2026 23:40

github-actions bot added area/cli Affects the command line area/dependencies Affects dependencies area/tooling Affects the dev or user toolchain (e.g. tests, ci, build tools) labels Jan 7, 2026

tstirrat15 reviewed Jan 12, 2026

View reviewed changes

tstirrat15 previously approved these changes Jan 12, 2026

View reviewed changes

josephschorr dismissed tstirrat15’s stale review via 942b7f1 January 13, 2026 17:36

josephschorr force-pushed the postgres-fdw branch 3 times, most recently from 281f677 to 70a611b Compare January 13, 2026 18:20

tstirrat15 previously approved these changes Jan 13, 2026

View reviewed changes

josephschorr dismissed tstirrat15’s stale review via 94e6043 January 13, 2026 19:38

josephschorr force-pushed the postgres-fdw branch from 70a611b to 94e6043 Compare January 13, 2026 19:38

tstirrat15 previously approved these changes Jan 13, 2026

View reviewed changes

josephschorr dismissed tstirrat15’s stale review via 376c046 January 13, 2026 20:37

josephschorr force-pushed the postgres-fdw branch 3 times, most recently from c53bb4b to c3fef24 Compare January 13, 2026 21:32

josephschorr marked this pull request as draft January 13, 2026 22:02

josephschorr force-pushed the postgres-fdw branch from c3fef24 to 4260757 Compare January 14, 2026 18:12

josephschorr marked this pull request as ready for review January 14, 2026 18:12

josephschorr force-pushed the postgres-fdw branch 2 times, most recently from 6ddcc43 to 17d5534 Compare January 14, 2026 19:05

tstirrat15 approved these changes Jan 14, 2026

View reviewed changes

josephschorr force-pushed the postgres-fdw branch from 17d5534 to 1d80dac Compare January 16, 2026 18:14

josephschorr added this pull request to the merge queue Jan 16, 2026

Merged via the queue into authzed:main with commit fd4b204 Jan 16, 2026
43 of 45 checks passed

josephschorr deleted the postgres-fdw branch January 16, 2026 23:38

github-actions bot locked and limited conversation to collaborators Jan 16, 2026

	- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB
	- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB

		// Verify error is properly wrapped with psql codes
		require.Error(t, err)


		var trailerMD metadata.MD

		checkResult, err := client.CheckPermission(ctx, &v1.CheckPermissionRequest{

		// Give PGServer time to start
		time.Sleep(50 * time.Millisecond)

feat: Initial implementation of the PostgresFDW #2806

feat: Initial implementation of the PostgresFDW #2806

Uh oh!

Conversation

josephschorr commented Jan 7, 2026

Uh oh!

codecov bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josephschorr Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tstirrat15 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tstirrat15 left a comment

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Jan 7, 2026 •

edited

Loading

josephschorr Jan 13, 2026 •

edited

Loading