Getting started

Xata is a PostgreSQL platform that provides instant Copy-on-Write branching, data masking, and separation of storage from compute. It's designed for modern teams running PostgreSQL at scale, with features like zero-downtime schema changes, realistic staging environments, and cloud-agnostic deployment options.

1. Sign up

Create your free Xata account at console.xata.io. You can sign up with GitHub, Google, or your email address.

Note: Xata is currently in private beta, please request access and wait for approval before proceeding.

2. Create a project

After signing in, create a new project. A project is the top-level container for all your branches and Postgres instances.

3. Create a branch

Within your project, create your first branch (e.g., main). A branch is a Postgres cluster—a collection of one or more Postgres instances, which can include a primary and optional replicas. When creating your main branch, you can choose the Postgres version, region, and instance size to fit your needs. This branch can serve as your production branch or a staging environment. You can branch off main at any time to create isolated development or test environments.

4. Add sample xata (data)

Navigate to the Queries section in your project and run the following SQL to create sample tables and data:

CREATE TABLE products(id SERIAL PRIMARY KEY,name TEXT,price NUMERIC(7,2));
CREATE TABLE orders(id SERIAL PRIMARY KEY,created_at TIMESTAMPTZ DEFAULT now());
CREATE TABLE order_items(order_id INT REFERENCES orders(id),product_id INT REFERENCES products(id),qty INT,PRIMARY KEY(order_id,product_id));
INSERT INTO products(name,price) SELECT LEFT(md5(i::text),8),(random()*90+10)::numeric(7,2) FROM generate_series(1,10)i;
WITH o AS (INSERT INTO orders DEFAULT VALUES RETURNING id) INSERT INTO order_items(order_id,product_id,qty) SELECT o.id,pid,(1+floor(random()*3))::int FROM o,(SELECT id pid FROM products ORDER BY random() LIMIT 5)p;

5. Install the CLI

To use advanced features like schema history, migrations, cloning and database management you need to install the Xata CLI:

curl -fsSL https://xata.io/install.sh | bash

Authenticate the CLI by running:

xata auth login

Initialize the project by running:

xata init

6. Enable schema history

Go to the Branches section and select your branch (e.g., main). Here you can view your schema and enable schema history for zero-downtime migrations.

To enable schema history, run:

xata roll init

7. Create a development branch with the CLI

Create a new branch from main:

xata branch create --name dev --parent-branch `xata branch get id`

This command will automatically checkout the new branch for you.

8. Modify your schema from the terminal

You can make schema changes directly in the Xata query view, but here we'll show how to do it from your terminal using psql for a more hands-on workflow.

If you don't have psql installed:

macOS:

If you are using bash, replace ~/.zshrc with ~/.bash_profile in the above.

brew install libpq
echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Ubuntu:

sudo apt install postgresql-client-17

Windows: Download from PostgreSQL official site.

Connect to psql with your dev branch connection string

psql `xata branch url`

Add a new column to your products table:

ALTER TABLE products ADD COLUMN rating INT;

You can now use SQL to update or query the new column.

9. Check the schema diff in the branch details page

After making changes in a branch, use the Schema Diff feature in the dev branch details page to compare your branch with its parent.

10. Merge your changes back to main

Now that you've made changes in your dev branch, merge them back to main:

xata checkout main
xata roll migrate

This will apply your dev branch's schema changes to main.

11. Start from a clean slate

Now that you're all set up, let's get you reset and ready to start building.

Delete the dev branch:

xata branch delete dev

Finally, connect to your main branch using psql and run the following SQL to remove the sample tables and data:

DROP TABLE IF EXISTS order_items;
DROP TABLE IF EXISTS orders;
DROP TABLE IF EXISTS products;

This will leave your main branch clean for your next project or migration.

12. Next steps: choose your workflow

Now that your environment is clean, you're ready to dive deeper:

• Set up staging replica: Learn how to use Xata for staging environments, feature branches, and collaborative development.
• Migrate to Xata: Get set up for production by migrating your existing PostgreSQL database to Xata.
• Schema changes: Learn how to safely apply and roll back schema changes with zero downtime.

Need help? Reach out to the Xata team at info@xata.io or join our Discord community.