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 (@observer decorator)
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

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(sql_source="v_user", requires_scope="read:User")
   def user(id: ID) -> User:
       """Get user (enforces RLS filter via SQL view)."""
       pass

   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(sql_source="v_user_filtered", requires_scope="read:User")
   def my_profile() -> User:
       """User can only see their own profile."""
       pass

   -- v_user_filtered enforces row-level access in SQL
   CREATE VIEW v_user_filtered AS
   SELECT * FROM tb_user
   WHERE 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 * FROM tb_user
   WHERE 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 * FROM tb_user
   WHERE id = current_setting('app.current_user_id')::uuid;

   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")
   def send_email(input: SendEmailInput) -> ActionOutput:
       """Send email via PostgreSQL function."""
       pass

   -- Business logic lives in the database
   CREATE FUNCTION fn_send_email(p_email TEXT, p_message TEXT)
   RETURNS TABLE(success BOOL, message TEXT) AS $$
   BEGIN
       -- Insert into outbox for async processing
       INSERT INTO tb_email_outbox (recipient, body) VALUES (p_email, p_message);
       RETURN QUERY SELECT true, 'Email queued'::TEXT;
   END;
   $$ LANGUAGE plpgsql;

   FraiseQL (TypeScript)

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

   -- Business logic lives in the database
   CREATE FUNCTION fn_send_email(p_email TEXT, p_message TEXT)
   RETURNS TABLE(success BOOL, message TEXT) AS $$
   BEGIN
       INSERT INTO tb_email_outbox (recipient, body) VALUES (p_email, p_message);
       RETURN QUERY SELECT true, 'Email queued'::TEXT;
   END;
   $$ LANGUAGE plpgsql;

   FraiseQL (Go)

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

   -- Business logic lives in the database
   CREATE FUNCTION fn_send_email(p_email TEXT, p_message TEXT)
   RETURNS TABLE(success BOOL, message TEXT) AS $$
   BEGIN
       INSERT INTO tb_email_outbox (recipient, body) VALUES (p_email, p_message);
       RETURN QUERY SELECT true, 'Email queued'::TEXT;
   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.

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 RLS is enabled on tables:

   SELECT relname, relrowsecurity FROM pg_class WHERE relname LIKE 'tb_%';

2. Check policy exists:

   SELECT * FROM pg_policies WHERE tablename = 'tb_user';

3. Ensure tenant_id is being set:

   # Check context in resolver
   print(ctx.tenant_id)  # Should not be None

Issue: Event triggers not firing

Symptoms: Observers don’t execute when data changes.

Solution:

1. Verify observer is registered:

   # Check logs during startup
   fraiseql run 2>&1 | grep "observer"

2. Check observer syntax:

   @fraiseql.observer(
       entity="User",  # Must match table name
       event="INSERT"
   )

3. Test NATS connection:

   docker-compose exec nats nats server info

Issue: Schema too permissive

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

Solution:

1. Use field-level decorators:

   @fraiseql.type
   class User:
       id: str
       email: str
       # Hide sensitive fields
       password_hash: Annotated[str, fraiseql.field(exclude=True)]

2. Or create separate views for different roles:

   CREATE VIEW v_user_public AS
   SELECT id, name FROM tb_user;
   
   CREATE VIEW v_user_admin AS
   SELECT id, name, email, created_at FROM tb_user;

Issue: Relationships not resolving

Symptoms: Nested queries return null or empty arrays.

Solution:

1. Check SQL view has JOIN:

   -- View should JOIN related tables
   SELECT ... FROM tb_user u
   LEFT JOIN tb_post p ON p.user_id = 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_user_email ON tb_user(email);
   CREATE INDEX idx_post_user_id ON tb_post(user_id);

3. Analyze query plans:

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