> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fjall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# RDS Free Tier

> Run cost-free PostgreSQL on the AWS Free Tier with Fjall using RdsInstance settings that stay within the 12-month window.

## Overview

There is no separate free-tier class. Use the `RdsInstance` construct with free-tier-eligible settings to run a PostgreSQL database at no cost during your first 12 months on AWS.

## Resource Class

```typescript theme={null}
import { RdsInstance } from "@fjall/components-infrastructure/lib/resources/aws/database/rdsInstance";
```

## Basic Usage

```typescript theme={null}
const database = new RdsInstance(this, "DevDatabase", {
  vpc: myVpc,
  databaseName: "development",
  instanceType: "t4g.micro",
  allocatedStorage: 20,
  multiAz: false,
  proxy: false,
  readReplica: false,
  databaseInsights: false,
});
```

## Free Tier Settings

Configure `RdsInstance` with these settings to stay within the AWS Free Tier.

| Setting            | Value         | Reason                              |
| ------------------ | ------------- | ----------------------------------- |
| `instanceType`     | `"t4g.micro"` | Free-tier-eligible instance         |
| `allocatedStorage` | `20`          | 20 GB included in free tier         |
| `multiAz`          | `false`       | Multi-AZ doubles the cost           |
| `proxy`            | `false`       | RDS Proxy has its own charges       |
| `readReplica`      | `false`       | Read replicas are billed separately |
| `databaseInsights` | `false`       | Reduces monitoring overhead         |

## AWS Free Tier Limits

* **750 hours** per month of db.t4g.micro usage
* **20 GB** of General Purpose (GP3) storage
* **20 GB** of backup storage
* **Single-AZ** deployment only
* **12-month** eligibility period

## Configuration Options

All `RdsInstance` properties are available. The key properties for free-tier usage are listed below.

### Core Properties

| Property       | Type     | Description        | Default          |
| -------------- | -------- | ------------------ | ---------------- |
| `vpc`          | `IVpc`   | VPC for deployment | Required         |
| `databaseName` | `string` | Database name      | ID without "Rds" |
| `instanceType` | `string` | Instance type      | `"t4g.large"`    |
| `port`         | `number` | Database port      | `35255`          |

### Storage

| Property              | Type     | Description             | Default |
| --------------------- | -------- | ----------------------- | ------- |
| `allocatedStorage`    | `number` | Storage in GB           | -       |
| `maxAllocatedStorage` | `number` | Max autoscaling storage | `500`   |

### Backup and Maintenance

| Property                     | Type       | Description        | Default                 |
| ---------------------------- | ---------- | ------------------ | ----------------------- |
| `backupRetention`            | `Duration` | Backup retention   | 14 days                 |
| `preferredMaintenanceWindow` | `string`   | Maintenance window | `"Sat:12:30-Sat:20:30"` |

### Optional Features (Disable for Free Tier)

| Property           | Type                              | Description            | Default |
| ------------------ | --------------------------------- | ---------------------- | ------- |
| `multiAz`          | `boolean`                         | Multi-AZ deployment    | `true`  |
| `proxy`            | `ProxyConfig \| false`            | RDS Proxy              | -       |
| `readReplica`      | `ReadReplicaConfig \| false`      | Read replica           | -       |
| `databaseInsights` | `DatabaseInsightsConfig \| false` | Performance monitoring | Enabled |

## Security Features

RdsInstance includes these security features by default, even in free-tier configuration:

* Storage encryption with KMS
* GP3 storage type
* SSL/TLS connections via parameter group
* Automated credential generation
* Secret rotation (enabled by default)
* Deletion protection

```typescript theme={null}
const database = new RdsInstance(this, "SecureFreeDB", {
  vpc: vpc,
  databaseName: "secure",
  instanceType: "t4g.micro",
  allocatedStorage: 20,
  multiAz: false,
  proxy: false,
  readReplica: false,
  databaseInsights: false,
});
```

## Network Security

```typescript theme={null}
const database = new RdsInstance(this, "FreeDB", {
  vpc: vpc,
  databaseName: "app",
  instanceType: "t4g.micro",
  allocatedStorage: 20,
  multiAz: false,
  proxy: false,
  readReplica: false,
  databaseInsights: false,
});

// Allow access from application
app.connections.allowTo(database, Port.tcp(35255), "App to database");
```

## Methods

### Get Host Endpoint

```typescript theme={null}
const endpoint = database.getHostEndpoint();
// Returns: Direct instance endpoint
```

### Get Host Port

```typescript theme={null}
const port = database.getHostPort();
// Returns: "35255" (default, as string)
```

### Get Credentials

```typescript theme={null}
const credentials = database.getCredentials();
// Returns: Secret object with username/password
```

### Get Connections

```typescript theme={null}
const connections = database.connections;
// Use for network access control
```

## Complete Example

```typescript theme={null}
import { RdsInstance } from "@fjall/components-infrastructure/lib/resources/aws/database/rdsInstance";
import { Vpc, SubnetType, Port } from "aws-cdk-lib/aws-ec2";
import { Duration } from "aws-cdk-lib";
import { CfnOutput } from "aws-cdk-lib";

// Create VPC
const vpc = new Vpc(this, "DevVpc", {
  maxAzs: 2,
  natGateways: 0,
  subnetConfiguration: [
    {
      name: "public",
      subnetType: SubnetType.PUBLIC,
    },
    {
      name: "isolated",
      subnetType: SubnetType.PRIVATE_ISOLATED,
    },
  ],
});

// Create free-tier database
const database = new RdsInstance(this, "DevDatabase", {
  vpc: vpc,
  databaseName: "development",
  instanceType: "t4g.micro",
  allocatedStorage: 20,
  multiAz: false,
  proxy: false,
  readReplica: false,
  databaseInsights: false,
  backupRetention: Duration.days(7),
});

// Output connection details
new CfnOutput(this, "DatabaseEndpoint", {
  value: database.getHostEndpoint(),
  description: "Database endpoint",
});

new CfnOutput(this, "DatabasePort", {
  value: database.getHostPort(),
  description: "Database port",
});
```

## Upgrade Path

When you outgrow the free tier, update the `RdsInstance` configuration.

```typescript theme={null}
const database = new RdsInstance(this, "ProdDB", {
  vpc: vpc,
  databaseName: "production",
  instanceType: "t4g.large", // Upgrade size
  multiAz: true, // Add high availability
  proxy: {
    // Add connection pooling
    requireTLS: true,
  },
  readReplica: {
    // Add read scaling
    instanceType: "t4g.large",
  },
});
```

## Staying Within Free Tier

1. **Single database** per AWS account
2. **20 GB total storage** (including backups)
3. **Set `multiAz: false`** to avoid doubling costs
4. **Set `proxy: false`** to avoid proxy charges
5. **Set `readReplica: false`** to avoid replica charges
6. **Reduce backup retention** to 7 days to save storage
7. **Delete after 12 months** before charges apply

## Cost After Free Tier Expires

| Resource           | Monthly Cost |
| ------------------ | ------------ |
| t4g.micro instance | \~\$12       |
| 20 GB GP3 storage  | \~\$2        |
| Backup storage     | \~\$2        |
| **Total**          | **\~\$16**   |

## Use Cases

**Good for:**

* Development environments
* Proof of concepts
* Learning and experimentation
* Low-traffic applications
* CI/CD test databases

**Not suitable for:**

* Production workloads
* High availability requirements
* Applications needing consistent performance
* Databases larger than 20 GB

## Next Steps

<CardGroup cols={2}>
  <Card title="RDS Instance" icon="database" href="/resources/database/rds-instance">
    Configure a production-grade PostgreSQL instance
  </Card>

  <Card title="RDS Aurora" icon="layer-group" href="/resources/database/rds-aurora">
    Scale up to a managed Aurora cluster
  </Card>

  <Card title="Database Factory" icon="diagram-project" href="/patterns/database-factory">
    Create databases with the DatabaseFactory pattern
  </Card>

  <Card title="AWS Free Tier" icon="aws" href="https://aws.amazon.com/free/">
    Review the current AWS Free Tier limits
  </Card>
</CardGroup>