Migrating from Hasura to FraiseQL

Tip

Prefer a no-big-bang approach? This guide covers full migration. For a phased strategy where FraiseQL runs alongside Hasura while you migrate domain by domain — with rollback at every step — see the Incremental Migration Guide.

Migrating from Hasura to FraiseQL

This guide covers migrating from Hasura (auto-generated GraphQL from database introspection) to FraiseQL (code-first GraphQL backed by hand-written SQL views and PostgreSQL functions).

Comparison

Feature	Hasura	FraiseQL
Approach	Database-first (auto-schema from DB)	Code-first (schema from Python/TS/Go decorators)
Configuration	Web UI + YAML	SDK decorators + TOML
Type Safety	GraphQL generated	Native SDK types (Python, TypeScript, Go)
Hosting	Cloud or self-hosted	Any server — Docker, K8s, bare metal
Custom Logic	Actions + Webhooks	PostgreSQL functions (fn_*)
Federation	No	Yes (multi-database)
Performance	Good	Excellent (pre-compiled SQL views)
Runtime	Node.js / Haskell	Rust binary
Learning Curve	Low (UI-driven)	Medium (code-driven)

Concept Mapping

Use this table as a translation guide as you work through the migration:

Hasura	FraiseQL Equivalent
Track table	Create SQL view (v_*)
Permissions (YAML)	PostgreSQL Row-Level Security via SQL view WHERE clause
Event triggers	Observers (TOML [observers] section)
Actions	SQL functions (fn_*) + mutations
Remote schemas	Federation (multi-database in one binary)
Computed fields	SQL view expressions
Relationships (YAML)	Typed fields on @fraiseql.type backed by SQL JOIN
Hasura Console	fraiseql.toml + SDK decorators

Unlike Hasura, FraiseQL also serves REST and gRPC alongside GraphQL. After migration, your API is accessible to non-GraphQL clients without a separate gateway.

What changes

FraiseQL asks you to write views. In exchange:

• Your database schema is decoupled from your API. Hasura exposes tables directly — a table rename breaks the API. FraiseQL exposes views — a table rename is invisible to clients.
• You control exactly what the API exposes. No _aggregate, _by_pk, _stream variants you didn’t ask for.
• Complex queries are SQL, not YAML permission rules or nested filter objects.
• Row-level filtering uses SQL WHERE clauses instead of Hasura’s permission rule engine.

The migration involves creating v_* views that match your existing data model. For a simple case this is 30–60 minutes of SQL. For a complex case with permissions it replaces Hasura’s YAML rules with SQL WHERE conditions on the view.

Architecture Difference

Hasura auto-generates a GraphQL schema by introspecting your database tables. Every column and relationship becomes a queryable field automatically.

FraiseQL uses hand-written SQL views (v_*) for reads and PostgreSQL functions (fn_*) for writes. The Rust binary serves a GraphQL API derived from your decorator-annotated schema types — giving you explicit control over exactly what data is exposed and how it is shaped.

Tip

The key trade-off: Hasura is faster to prototype (zero SQL views to write) but harder to customize and secure. FraiseQL requires writing SQL views upfront but gives you precise control over query shape, row-level filtering, and performance.

Migration Path

1. Export Hasura Configuration

   # Get current Hasura metadata
   hasura metadata export
   
   # Review generated metadata
   cat metadata/databases/default/tables/

2. Map Hasura Tables to FraiseQL Types

   Each Hasura table becomes a FraiseQL @fraiseql.type. Relationships defined in Hasura YAML become typed fields on the class.

   Hasura (YAML)

   metadata/databases/default/tables/user.yaml

   table:
     name: user
     schema: public
   select_permissions:
     - role: user
       permission:
         columns: [id, email, name]
         filter:
           id:
             _eq: X-Hasura-User-Id
   relationships:
     - name: posts
       type: array
       using:
         foreign_key_constraint_on:
           column: user_id
           table:
             name: post
             schema: public

   FraiseQL (Python)

   @fraiseql.type
   class User:
       id: ID
       email: str
       name: str
       posts: list['Post']  # Relationship via SQL view JOIN
   
   @fraiseql.query(requires_scope="read:User")
   def user(id: ID) -> User:
       """Get user (enforces RLS filter via SQL view)."""
       return fraiseql.config(sql_source="v_user")

   FraiseQL (TypeScript)

   import { Type, Query, ID } from 'fraiseql';
   
   @Type()
   class User {
       id!: ID;
       email!: string;
       name!: string;
       posts!: Post[];
   }
   
   @Query({ sqlSource: 'v_user', requiresScope: 'read:User' })
   function user(id: ID): Promise<User> {
       return Promise.resolve({} as User);
   }

   FraiseQL (Go)

   import "github.com/fraiseql/fraiseql-go"
   
   type User struct {
       ID    fraiseql.ID `fraiseql:"id"`
       Email string      `fraiseql:"email"`
       Name  string      `fraiseql:"name"`
       Posts []Post      `fraiseql:"posts"`
   }
   
   func init() {
       fraiseql.Query("user", fraiseql.QueryConfig{
           SQLSource:     "v_user",
           RequiresScope: "read:User",
       }, func(args fraiseql.Args) (User, error) { return User{}, nil })
   }

3. Replicate Permissions via SQL Views

   Hasura row-level permissions become WHERE clauses in your PostgreSQL views. The FraiseQL Rust binary passes the authenticated user’s context as a PostgreSQL session variable.

   Hasura (YAML permissions)

   select_permissions:
     - role: user
       permission:
         columns: [id, name, email]
         filter:
           id:
             _eq: X-Hasura-User-Id

   FraiseQL (Python)

   @fraiseql.query(requires_scope="read:User")
   def my_profile() -> User:
       """User can only see their own profile."""
       return fraiseql.config(sql_source="v_user_filtered")

   -- v_user_filtered enforces row-level access in SQL
   CREATE VIEW v_user_filtered AS
   SELECT
       u.id,
       jsonb_build_object(
           'id',         u.id::text,
           'identifier', u.identifier,
           'email',      u.email,
           'name',       u.name
       ) AS data
   FROM tb_user u
   WHERE u.id = current_setting('app.current_user_id')::uuid;

   FraiseQL (TypeScript)

   import { Query, RequiresScope, ID } from 'fraiseql';
   
   @Query({ sqlSource: 'v_user_filtered' })
   @RequiresScope('read:User')
   function myProfile(): Promise<User> {
       return Promise.resolve({} as User);
   }

   -- v_user_filtered enforces row-level access in SQL
   CREATE VIEW v_user_filtered AS
   SELECT
       u.id,
       jsonb_build_object(
           'id',         u.id::text,
           'identifier', u.identifier,
           'email',      u.email,
           'name',       u.name
       ) AS data
   FROM tb_user u
   WHERE u.id = current_setting('app.current_user_id')::uuid;

   FraiseQL (Go)

   fraiseql.Query("myProfile", fraiseql.QueryConfig{
       SQLSource:     "v_user_filtered",
       RequiresScope: "read:User",
   }, func(args fraiseql.Args) (User, error) { return User{}, nil })

   -- v_user_filtered enforces row-level access in SQL
   CREATE VIEW v_user_filtered AS
   SELECT
       u.id,
       jsonb_build_object(
           'id',         u.id::text,
           'identifier', u.identifier,
           'email',      u.email,
           'name',       u.name
       ) AS data
   FROM tb_user u
   WHERE u.id = current_setting('app.current_user_id')::uuid;

   The FraiseQL Rust binary sets app.current_user_id (and other claims) as PostgreSQL session variables from the JWT at request time. See Authentication for full JWT and session variable configuration.

   Verify your permission migration works correctly by testing with both an admin token and a viewer token:

   # Admin role: full access — should return all users
   curl -X POST http://localhost:8080/graphql \
     -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ users { id name email } }"}' | jq '.data.users | length'
   # Expect: total user count (e.g. 42)
   
   # Viewer role: filtered access — should return only the viewer's own profile
   curl -X POST http://localhost:8080/graphql \
     -H "Authorization: Bearer $VIEWER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ myProfile { id name email } }"}' | jq '.data.myProfile'
   # Expect: single user object matching the viewer's own account
   
   # Viewer role: cross-user access — should be filtered out by the SQL view
   curl -X POST http://localhost:8080/graphql \
     -H "Authorization: Bearer $VIEWER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ user(id: \"other-user-id\") { id name } }"}' | jq '.data.user'
   # Expect: null (filtered by SQL view WHERE clause — not an authorization error)

4. Migrate Custom Actions to PostgreSQL Functions

   Hasura Actions are webhook-based — they call an external HTTP endpoint. FraiseQL replaces these with PostgreSQL functions (fn_*) or observer hooks that trigger side effects.

   Hasura (Actions webhook)

   actions:
     - name: sendEmail
       definition:
         kind: action
         arguments:
           - name: email
             type: String!
           - name: message
             type: String!
         output_type: ActionOutput
         webhook_url: https://myapp.com/send-email
         timeout: 30

   FraiseQL (Python)

   @fraiseql.input
   class SendEmailInput:
       email: str
       message: str
   
   @fraiseql.mutation(sql_source="fn_send_email", operation="CUSTOM")
   def send_email(input: SendEmailInput) -> User:
       """Queue email via PostgreSQL function."""
       pass

   -- Business logic lives in the database
   CREATE FUNCTION fn_send_email(p_email TEXT, p_message TEXT)
   RETURNS mutation_response AS $$
   DECLARE
       v_result mutation_response;
   BEGIN
       -- Insert into outbox for async processing
       INSERT INTO tb_email_outbox (recipient, body) VALUES (p_email, p_message);
   
       v_result.status  := 'success';
       v_result.message := 'Email queued';
       RETURN v_result;
   EXCEPTION WHEN OTHERS THEN
       v_result.status  := 'error';
       v_result.message := 'Failed to queue email.';
       RETURN v_result;
   END;
   $$ LANGUAGE plpgsql;

   FraiseQL (TypeScript)

   import { Input, Mutation } from 'fraiseql';
   
   @Input()
   class SendEmailInput {
       email!: string;
       message!: string;
   }
   
   @Mutation({ sqlSource: 'fn_send_email', operation: 'CUSTOM' })
   function sendEmail(input: SendEmailInput): Promise<User> {
       return Promise.resolve({} as User);
   }

   -- Business logic lives in the database
   CREATE FUNCTION fn_send_email(p_email TEXT, p_message TEXT)
   RETURNS mutation_response AS $$
   DECLARE
       v_result mutation_response;
   BEGIN
       -- Insert into outbox for async processing
       INSERT INTO tb_email_outbox (recipient, body) VALUES (p_email, p_message);
   
       v_result.status  := 'success';
       v_result.message := 'Email queued';
       RETURN v_result;
   EXCEPTION WHEN OTHERS THEN
       v_result.status  := 'error';
       v_result.message := 'Failed to queue email.';
       RETURN v_result;
   END;
   $$ LANGUAGE plpgsql;

   FraiseQL (Go)

   import "github.com/fraiseql/fraiseql-go"
   
   type SendEmailInput struct {
       Email   string `fraiseql:"email"`
       Message string `fraiseql:"message"`
   }
   
   func init() {
       fraiseql.Mutation("sendEmail", fraiseql.MutationConfig{
           SQLSource: "fn_send_email",
           Operation: "CUSTOM",
       }, func(input SendEmailInput) (interface{}, error) {
           return nil, nil
       })
   }

   -- Business logic lives in the database
   CREATE FUNCTION fn_send_email(p_email TEXT, p_message TEXT)
   RETURNS mutation_response AS $$
   DECLARE
       v_result mutation_response;
   BEGIN
       -- Insert into outbox for async processing
       INSERT INTO tb_email_outbox (recipient, body) VALUES (p_email, p_message);
   
       v_result.status  := 'success';
       v_result.message := 'Email queued';
       RETURN v_result;
   EXCEPTION WHEN OTHERS THEN
       v_result.status  := 'error';
       v_result.message := 'Failed to queue email.';
       RETURN v_result;
   END;
   $$ LANGUAGE plpgsql;

5. Migrate Subscriptions to NATS

   Hasura (Event-based)

   subscription OnUserCreated {
     user(event: insert) {
       id
       name
       email
     }
   }

   FraiseQL (NATS-backed)

   @fraiseql.subscription(entity_type="User", topic="created")
   def user_created() -> User:
       """Subscribe to new users."""
       pass

6. Update Client Queries

   FraiseQL uses a slightly different filter syntax from Hasura. Update your client queries accordingly.

   Hasura filtering

   query {
     user(where: {
       email: { _eq: "alice@example.com" }
       posts: { title: { _ilike: "hello%" } }
     }) {
       id
       email
     }
   }

   FraiseQL filtering

   query {
     user(
       email_eq: "alice@example.com"
       posts_title_contains: "hello"
     ) {
       id
       email
     }
   }

   Ordering and pagination syntax is compatible:

   Hasura ordering

   query {
     users(order_by: { created_at: desc }) {
       id
       name
     }
   }

   FraiseQL ordering

   query {
     users(orderBy: "created_at DESC") {
       id
       name
     }
   }

   Pagination is identical in both:

   query {
     users(limit: 10, offset: 20) {
       id
       name
     }
   }

7. Performance Test and Decommission

   Once all client queries are migrated and validated, decommission Hasura. FraiseQL’s pre-compiled SQL views typically deliver 3-5x better performance than Hasura’s auto-generated queries. See Performance Benchmarks for methodology.

Performance Improvements

Hasura auto-generates SQL from the GraphQL query at runtime. This is flexible but can produce suboptimal queries, especially for nested relationships.

FraiseQL uses hand-written SQL views that you optimize yourself. The Rust binary executes pre-compiled queries — no runtime SQL generation.

Hasura query (10 users with posts):
  users: 1 query
  user[0].posts: 1 query (N+1!)
  user[1].posts: 1 query
  ... (8 more)
  Total: 11 queries

FraiseQL query (10 users with posts):
  users: 1 query (v_user)
  posts (batched): 1 query (v_post WHERE user_id IN (...))
  Total: 2 queries

Cost Comparison

Caution

Pricing changes frequently. The figures below are illustrative. Always check the official pricing pages before making a decision: Hasura Cloud pricing and your chosen hosting provider’s current rates for FraiseQL self-hosting.

	Hasura Cloud	FraiseQL (Self-hosted)
GraphQL engine	Paid tier required for production features	Open source (Apache 2.0)
Server hosting	Included in cloud plan	Your own server or cloud VM
Database	Extra (managed database add-on)	Existing or separate managed DB

FraiseQL is self-hosted, so your total cost depends on your infrastructure. For many teams, running a single Rust binary alongside an existing PostgreSQL instance results in significantly lower costs than a managed GraphQL cloud service, but your mileage will vary.

Migration Checklist

• Export Hasura metadata and config
• Document all tables, relationships, and permissions
• Map tables to FraiseQL types
• Write SQL views (v_*) replicating Hasura’s select permissions
• Write PostgreSQL functions (fn_*) replacing Hasura actions
• Define FraiseQL decorator types and queries
• Migrate subscriptions to NATS
• Update client query syntax
• Performance test
• Decommission Hasura

Prisma Migration

Migrating from Prisma ORM.

Read guide

Apollo Migration

Migrating from Apollo Server.

Read guide

REST Migration

Migrating from REST APIs.

Read guide

Getting Started

Learn FraiseQL fundamentals from scratch.

Read guide

Migration Verification

1. Export and compare schemas:

   # Export Hasura metadata
   hasura metadata export
   
   # Compile FraiseQL schema
   fraiseql compile --output schema.fraiseql.json
   
   # Compare type counts
   cat metadata/databases/default/tables/*.yaml | grep "^table:" | wc -l
   cat schema.fraiseql.json | jq '.types | length'

2. Test query parity:

   # Hasura query
   curl -X POST http://localhost:8080/v1/graphql \
     -H "Content-Type: application/json" \
     -H "X-Hasura-Admin-Secret: secret" \
     -d '{"query": "{ users { id name } }"}' \
     > hasura_result.json
   
   # FraiseQL query
   curl -X POST http://localhost:8080/graphql \
     -H "Content-Type: application/json" \
     -d '{"query": "{ users { id name } }"}' \
     > fraiseql_result.json
   
   # Compare field structure
   diff <(jq '.data.users[0] | keys' hasura_result.json) \
        <(jq '.data.users[0] | keys' fraiseql_result.json)

3. Verify RLS equivalence:

   # Test with user token
   curl -X POST http://localhost:8080/graphql \
     -H "Authorization: Bearer $USER_TOKEN" \
     -d '{"query": "{ users { id email } }"}'
   
   # Verify user only sees their own data
   # (same behavior as Hasura with permissions)

4. Test event triggers → observers:

   # Create a record
   curl -X POST http://localhost:8080/graphql \
     -d '{"query": "mutation { createUser(...) { id } }"}'
   
   # Check webhook was called (in FraiseQL observer)
   tail -f /var/log/fraiseql/observers.log

5. Performance comparison:

   # Benchmark Hasura
   ab -n 1000 -c 10 -p query.json \
     -H "X-Hasura-Admin-Secret: secret" \
     http://localhost:8080/v1/graphql
   
   # Benchmark FraiseQL
   ab -n 1000 -c 10 -p query.json \
     http://localhost:8080/graphql

Common Migration Issues

Issue: Permissions not working

Symptoms: Users can see all data instead of just their own.

Solution:

1. Verify the SQL view applies the correct WHERE filter. In FraiseQL, row-level access is enforced in the view itself — there is no Python context object at runtime. The Rust binary sets a PostgreSQL session variable before executing the query:

   -- Correct: row-level filter is in the SQL view
   CREATE VIEW v_user_filtered AS
   SELECT
       u.id,
       jsonb_build_object('id', u.id::text, 'email', u.email, 'name', u.name) AS data
   FROM tb_user u
   WHERE u.id = current_setting('app.current_user_id')::uuid;

2. Check that the JWT claim is being injected correctly via fraiseql.toml:

[security.pkce] issuer_url = “https://auth.example.com” client_id = “my-app” redirect_uri = “https://app.example.com/callback”

3. Verify the session variable is set before queries run by checking the FraiseQL server logs at debug level:
```bash
RUST_LOG=debug fraiseql run

Issue: Event triggers not firing

Symptoms: Observers don’t execute when data changes.

Solution:

Observers in FraiseQL are configured in fraiseql.toml, not via Python decorators. The fraiseql Python package has no observer export — observers are a TOML-level and runtime concern.

1. Check that the [observers] section is present in fraiseql.toml:

   [observers]
   backend  = "nats"
   nats_url = "nats://localhost:4222"

2. Verify the observer logs at startup:

   fraiseql run 2>&1 | grep "observer"

3. Test NATS connectivity:

   nats pub test "hello"

Issue: Schema too permissive

Symptoms: Hasura had field-level permissions, FraiseQL exposes everything.

Solution:

To hide sensitive fields, simply omit them from the @fraiseql.type class and from the SQL view’s jsonb_build_object. fraiseql.field() accepts requires_scope, on_deny, deprecated, and description — there is no exclude parameter.

1. To restrict access to a field to authorized users only, use requires_scope:

   from typing import Annotated
   import fraiseql
   
   @fraiseql.type
   class User:
       id: ID
       name: str
       # Requires a specific scope — rejects unauthorized requests by default
       email: Annotated[str, fraiseql.field(requires_scope="read:User.email")]

2. To create separate views for different roles, each view must still return (id, data):

   -- Public view: omits email from the JSONB data
   CREATE VIEW v_user_public AS
   SELECT
       u.id,
       jsonb_build_object('id', u.id::text, 'name', u.name) AS data
   FROM tb_user u;
   
   -- Admin view: includes all fields
   CREATE VIEW v_user_admin AS
   SELECT
       u.id,
       jsonb_build_object(
           'id',         u.id::text,
           'identifier', u.identifier,
           'name',       u.name,
           'email',      u.email,
           'created_at', u.created_at
       ) AS data
   FROM tb_user u;

Issue: Relationships not resolving

Symptoms: Nested queries return null or empty arrays.

Solution:

1. Check SQL view has JOIN using integer FKs (not UUID):

   -- View should JOIN via the pk_/fk_ integer pair
   SELECT ... FROM tb_user u
   LEFT JOIN tb_post p ON p.fk_user = u.pk_user
   GROUP BY u.pk_user, u.id

2. Verify foreign keys exist:

   SELECT conname, conrelid::regclass, confrelid::regclass
   FROM pg_constraint WHERE contype = 'f';

3. Test the view directly:

   SELECT data FROM v_user WHERE id = '123';
   -- Should include nested posts

Issue: Performance regression

Symptoms: FraiseQL is slower than Hasura.

Solution:

1. Check for missing indexes (Hasura auto-creates, FraiseQL doesn’t):

   -- List all indexes
   SELECT indexname, tablename FROM pg_indexes
   WHERE tablename LIKE 'tb_%' ORDER BY tablename;

2. Create necessary indexes:

   CREATE INDEX idx_tb_user_email   ON tb_user(email);
   CREATE INDEX idx_tb_post_fk_user ON tb_post(fk_user);

3. Analyze query plans:

   EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
   SELECT data FROM v_user WHERE email = 'test@test.com';