After deploying your Sim IDX app, the framework automatically provisions a dedicated PostgreSQL database to store your indexed on-chain data. The deployment output provides you with a read-only connection string to access this database directly. You can use this during development to verify your schema, inspect live data, and create queries while building your API.
The database connection string provided after deployment is intended for development and debugging. Your deployed APIs will connect to a separate, production-ready database instance with the same schema.

​
Connect to Your Database

Use the database connection string provided in your app’s deployment to connect with any standard PostgreSQL client. 
postgres://username:password@host/database?sslmode=require
For example, using psql: 
# Connect using the full connection string
psql "your_connection_string_here"
You can also use clients like DBeaver, Postico, or Beekeeper Studio for a more visual way to explore your data and schema.

​
Understand the Schema

The structure of your database is directly determined by the event definitions in your Main.sol contract.
  • Views: Each event in your listener creates a corresponding queryable view in the database. The view name is the lowercase snake_case version of the event name.
  • Columns: The parameters of the event become the columns of the view, and each column name is converted to lowercase snake_case.
  • Tables: The underlying tables that store the data have random character suffixes (e.g., pool_created_X3rbm4nC) and should not be queried directly.
An event defined as event PoolCreated(address pool, address token0, address token1) will result in a queryable view named pool_created with the columns pool, token0, and token1. When you inspect your database, you will see both the clean views you should query and the internal tables with random suffixes. Always query the views (lowercase snake_case names).

​
Inspect Indexes

If you have defined indexes in your listener, you can verify their existence directly from your database client. To confirm your indexes were created successfully, you can list them using psql. To list all indexes in the database, use the \di command. This shows the index name, type, and the table it belongs to. To see the indexes for a specific table, use the \d "view_name" command. This describes the view and lists the indexes on its underlying table. 
# List all indexes in the database
\di

# Describe the view and see its specific indexes
\d "position_owner_changes"

​
Common Database Operations

Here are some common psql commands you can use to inspect your database:
Operationpsql CommandDescription
List Views\dvShows all queryable views in the public schema.
Describe View\d "view_name"Displays the columns, types, and structure for a specific view, including indexes on the underlying table.
List Indexes\diShows all indexes in the database.
View Sample DataSELECT * FROM "view_name" LIMIT 10;Retrieves the first 10 rows from a view.
Count RowsSELECT COUNT(*) FROM "view_name";Counts the total number of records indexed in a view.

​
Limitations

Currently, Sim IDX only supports creating new rows in the database, not updates to existing rows. This means that once data is indexed and stored, it cannot be modified through the framework. We are exploring options to support updates in future versions.