[draft] Exploring what a Railway provider looks like

alchemy-web/src/content/docs/guides/railway.mdx

@@ -0,0 +1,215 @@
+---
+title: Railway
+description: Deploy applications and databases to Railway using Alchemy.
+sidebar:
+  order: 22
+---
+
+import { Steps, Tabs, TabItem } from "@astrojs/starlight/components";
+
+This guide walks you through deploying an application with a PostgreSQL database to Railway using Alchemy.
+
+<Steps>
+
+0. Install and setup Alchemy
+
+	<Tabs syncKey="pkgManager">
+	<TabItem label="bun">
+
+	```bash
+	bun add alchemy
+	```
+
+	</TabItem>
+	<TabItem label="npm">
+
+	```bash
+	npm install alchemy
+	```
+
+	</TabItem>
+	<TabItem label="pnpm">
+
+	```bash
+	pnpm add alchemy
+	```
+
+	</TabItem>
+	<TabItem label="yarn">
+
+	```bash
+	yarn add alchemy
+	```
+
+	</TabItem>
+	</Tabs>
+
+	:::tip
+	If you're new to Alchemy, see the [Getting Started](/getting-started/) guide.
+	:::
+
+1. **Get Railway API Token**
+
+   Create an API token from your [Railway account settings](https://railway.com/account/tokens).
+
+2. **Configure environment variables**
+
+   Add the token to your `.env` file:
+
+   ```bash
+   RAILWAY_API_TOKEN=your_railway_api_token
+   ```
+
+3. **Create your infrastructure**
+
+   Create `alchemy.run.ts` with a Railway project, service, and database:
+
+   ```ts title="alchemy.run.ts"
+   import alchemy from "alchemy";
+   import {
+     Project,
+     Service,
+     PostgresDatabase,
+     Domain,
+     Variable,
+   } from "alchemy/railway";
+
+   const app = await alchemy("my-railway-app");
+
+   // Create a Railway project
+   const project = await Project("my-project", {
+     name: "My App",
+     description: "My application on Railway",
+   });
+
+   // Deploy a PostgreSQL database
+   const db = await PostgresDatabase("db", {
+     project,
+     name: "postgres",
+   });
+
+   // Deploy the API service from Docker image
+   const api = await Service("api", {
+     project,
+     name: "api",
+     source: {
+       image: "nginx:alpine", // Replace with your image
+     },
+   });
+
+   // Get the production environment
+   const productionEnv = project.environments[0];
+
+   // Add database URL to the service
+   if (productionEnv) {
+     await Variable("db-url", {
+       project,
+       environment: productionEnv.id,
+       service: api,
+       name: "DATABASE_URL",
+       value: db.connectionUrl,
+     });
+
+     // Create a public domain
+     const domain = await Domain("api-domain", {
+       service: api,
+       environment: productionEnv.id,
+     });
+
+     console.log(`API will be available at: https://${domain.domain}`);
+   }
+
+   await app.finalize();
+   ```
+
+4. **Deploy from GitHub (Alternative)**
+
+   To deploy from a GitHub repository instead of a Docker image:
+
+   ```diff lang="ts" title="alchemy.run.ts"
+   const api = await Service("api", {
+     project,
+     name: "api",
+   -  source: {
+   -    image: "nginx:alpine",
+   -  },
+   +  source: {
+   +    repo: "your-username/your-repo",
+   +    branch: "main",
+   +  },
+   +  buildCommand: "npm run build",
+   +  startCommand: "npm start",
+   });
+   ```
+
+5. **Deploy your application**
+
+   Use the Alchemy CLI to deploy:
+
+   <Tabs syncKey="pkgManager">
+     <TabItem label="bun">
+       ```sh
+       bun alchemy deploy
+       ```
+     </TabItem>
+     <TabItem label="npm">
+       ```sh
+       npx alchemy deploy
+       ```
+     </TabItem>
+     <TabItem label="pnpm">
+       ```sh
+       pnpm alchemy deploy
+       ```
+     </TabItem>
+     <TabItem label="yarn">
+       ```sh
+       yarn alchemy deploy
+       ```
+     </TabItem>
+   </Tabs>
+
+   This will create your Railway project, database, and service. The console will output your service URL.
+
+6. **Verify deployment**
+
+   Visit the [Railway dashboard](https://railway.com) to see your deployed resources. You can also test your service by visiting the domain URL output in the previous step.
+
+7. **(Optional) Tear down**
+
+   Use the Alchemy CLI to delete all resources:
+
+   <Tabs syncKey="pkgManager">
+     <TabItem label="bun">
+       ```sh
+       bun alchemy destroy
+       ```
+     </TabItem>
+     <TabItem label="npm">
+       ```sh
+       npx alchemy destroy
+       ```
+     </TabItem>
+     <TabItem label="pnpm">
+       ```sh
+       pnpm alchemy destroy
+       ```
+     </TabItem>
+     <TabItem label="yarn">
+       ```sh
+       yarn alchemy destroy
+       ```
+     </TabItem>
+   </Tabs>
+
+   :::caution
+   This will delete your database and all its data. Use `delete: false` on your database resource to preserve data.
+   :::
+
+</Steps>
+
+## Next Steps
+
+- [Railway Provider Documentation](/providers/railway/) - Full API reference
+- [Railway Official Docs](https://docs.railway.com) - Learn more about Railway features
+- [Railway Templates](https://railway.app/templates) - Pre-built templates for common stacks

alchemy-web/src/content/docs/providers/railway/database.md

@@ -0,0 +1,172 @@
+---
+title: Databases
+description: Learn how to deploy databases on Railway with Alchemy
+---
+
+Railway provides managed database services for PostgreSQL, MySQL, Redis, and MongoDB.
+
+## Authentication
+
+To use these resources, set `RAILWAY_API_TOKEN` in your `.env` file.
+
+## PostgreSQL
+
+### Basic Usage
+
+```ts
+import { Project, PostgresDatabase } from "alchemy/railway";
+
+const project = await Project("my-project", {
+  name: "My App",
+});
+
+const db = await PostgresDatabase("db", {
+  project,
+  name: "postgres",
+});
+
+// Use the connection URL
+console.log(db.connectionUrl);  // Secret
+console.log(db.host);           // hostname
+console.log(db.port);           // 5432
+console.log(db.database);       // database name
+console.log(db.user);           // username
+console.log(db.password);       // Secret
+```
+
+### With Service
+
+```ts
+import { Project, Service, PostgresDatabase, Variable } from "alchemy/railway";
+
+const project = await Project("my-project", {
+  name: "My App",
+});
+
+const db = await PostgresDatabase("db", { project });
+
+const api = await Service("api", {
+  project,
+  source: { repo: "myorg/api" },
+});
+
+// Connect the database to the service
+const productionEnv = project.environments[0];
+await Variable("db-url", {
+  project,
+  environment: productionEnv.id,
+  service: api,
+  name: "DATABASE_URL",
+  value: db.connectionUrl,
+});
+```
+
+## MySQL
+
+```ts
+import { Project, MysqlDatabase } from "alchemy/railway";
+
+const project = await Project("my-project", {
+  name: "My App",
+});
+
+const db = await MysqlDatabase("mysql", {
+  project,
+  name: "mysql-db",
+});
+
+console.log(db.connectionUrl);  // mysql://...
+console.log(db.host);
+console.log(db.port);           // 3306
+console.log(db.database);
+console.log(db.user);
+console.log(db.password);
+```
+
+## Redis
+
+```ts
+import { Project, RedisDatabase } from "alchemy/railway";
+
+const project = await Project("my-project", {
+  name: "My App",
+});
+
+const redis = await RedisDatabase("cache", {
+  project,
+  name: "redis-cache",
+});
+
+console.log(redis.connectionUrl);  // redis://...
+console.log(redis.host);
+console.log(redis.port);           // 6379
+console.log(redis.password);
+```
+
+## MongoDB
+
+```ts
+import { Project, MongoDatabase } from "alchemy/railway";
+
+const project = await Project("my-project", {
+  name: "My App",
+});
+
+const mongo = await MongoDatabase("mongo", {
+  project,
+  name: "mongodb",
+});
+
+console.log(mongo.connectionUrl);  // mongodb://...
+```
+
+## Properties (All Databases)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `project` | `string \| Project` | The project to create the database in |
+| `environment` | `string \| Environment` | Target environment (optional) |
+| `name` | `string` | Name of the database service |
+| `delete` | `boolean` | Whether to delete on destroy (default: true) |
+
+## Outputs
+
+### PostgreSQL / MySQL
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | The service ID |
+| `connectionUrl` | `Secret` | Full connection URL |
+| `host` | `string` | Database host |
+| `port` | `number` | Database port |
+| `database` | `string` | Database name |
+| `user` | `string` | Database user |
+| `password` | `Secret` | Database password |
+
+### Redis
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | The service ID |
+| `connectionUrl` | `Secret` | Full connection URL |
+| `host` | `string` | Redis host |
+| `port` | `number` | Redis port (6379) |
+| `password` | `Secret` | Redis password |
+
+### MongoDB
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | The service ID |
+| `connectionUrl` | `Secret` | Full connection URL |
+
+## Data Persistence
+
+By default, databases are deleted when removed from Alchemy. To preserve data:
+
+```ts
+const db = await PostgresDatabase("db", {
+  project,
+  delete: false,  // Database will not be deleted
+});
+```