use appstruct_migrate::{
IntrospectedColumn, IntrospectedForeignKey, IntrospectedIndex, IntrospectedSchema,
IntrospectedTable,
};
use std::collections::{BTreeMap, BTreeSet};
use std::fmt::Write;
mod helpers;
#[cfg(test)]
mod tests;
mod types;
use helpers::{
field_name, is_now_default, is_sequence_default, render_capabilities, scalar_default,
singularize, type_name, unique_name, yaml_string,
};
use types::{SpecType, spec_type};
pub(super) struct Draft {
pub source: String,
pub entity_count: usize,
pub entity_tables: BTreeMap<String, String>,
pub warnings: Vec<String>,
}
struct RenderContext<'schema> {
entities: BTreeMap<&'schema str, String>,
relations: BTreeMap<(&'schema str, &'schema str), &'schema IntrospectedForeignKey>,
warnings: Vec<String>,
}
#[allow(dead_code)]
pub(super) fn render(schema: &IntrospectedSchema) -> Draft {
render_with_access(schema, &AccessMode::None)
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub(super) enum AccessMode {
None,
Public,
Authenticated,
Role(String),
Owner(String),
}
pub(super) fn render_with_access(schema: &IntrospectedSchema, access: &AccessMode) -> Draft {
let mut context = RenderContext::new(schema);
let access_note = if matches!(access, AccessMode::None) {
"# Access rules are intentionally omitted so imported resources fail closed.\n"
} else {
"# Access rules were selected during import; review them before including this draft.\n"
};
let mut source = format!(
"# Generated by `appstruct db pull`; review before adding this file to `includes`.\n\
{access_note}\
# AppStruct owns the `revision` column used for optimistic concurrency.\n\
domain: imported\n\nentities:\n"
);
for table in &schema.tables {
if let Some(entity) = context.entities.get(table.name.as_str()).cloned() {
context.render_table(&mut source, table, &entity, access);
}
}
if context.entities.is_empty() {
source.push_str(" {}\n");
}
Draft {
source,
entity_count: context.entities.len(),
entity_tables: context
.entities
.iter()
.map(|(table, entity)| (entity.clone(), (*table).to_owned()))
.collect(),
warnings: context.warnings,
}
}
impl<'schema> RenderContext<'schema> {
fn new(schema: &'schema IntrospectedSchema) -> Self {
let mut warnings = Vec::new();
let mut entities = BTreeMap::new();
let mut used = BTreeSet::new();
for table in &schema.tables {
if table.primary_key.len() != 1 {
warnings.push(format!(
"table `{}` was omitted because its primary key [{}] has {} columns; AppStruct requires one scalar key, so add a supported surrogate key before importing",
table.name,
table.primary_key.join(", "),
table.primary_key.len()
));
continue;
}
let key_name = &table.primary_key[0];
let Some(key) = table.columns.iter().find(|column| &column.name == key_name) else {
warnings.push(format!(
"table `{}` has an unreadable primary key",
table.name
));
continue;
};
if key.name == "revision" {
warnings.push(format!(
"table `{}` was omitted because `revision` is reserved for AppStruct concurrency control",
table.name
));
continue;
}
if !spec_type(key).supports_primary_key() {
warnings.push(format!(
"table `{}` was omitted because primary key `{}` uses unsupported type `{}`",
table.name, key.name, key.data_type
));
continue;
}
let base = type_name(&singularize(&table.name));
let entity = unique_name(&base, &mut used);
entities.insert(table.name.as_str(), entity);
}
let relations = usable_relations(schema, &entities, &mut warnings);
Self {
entities,
relations,
warnings,
}
}
fn render_table(
&mut self,
output: &mut String,
table: &IntrospectedTable,
entity: &str,
access: &AccessMode,
) {
let _ = writeln!(output, " {entity}:");
let _ = writeln!(output, " label: {}", yaml_string(entity));
let _ = writeln!(output, " table: {}", yaml_string(&table.name));
output.push_str(" fields:\n");
let mut used_fields = BTreeSet::new();
let mut field_names = BTreeMap::new();
for column in &table.columns {
if column.name == "revision" {
continue;
}
let relation = self
.relations
.get(&(table.name.as_str(), column.name.as_str()))
.copied();
if let Some(field) =
self.render_column(output, table, column, relation, &mut used_fields)
{
field_names.insert(column.name.as_str(), field);
}
}
let mut indexes = String::new();
for unique in &table.unique_constraints {
if unique.len() > 1 {
self.render_index(
&mut indexes,
&table.name,
&IntrospectedIndex {
name: format!("{}_{}_unique", table.name, unique.join("_")),
columns: unique.clone(),
unique: true,
method: "btree".to_owned(),
operator_class: None,
predicate: None,
},
&field_names,
);
}
}
for index in &table.indexes {
self.render_index(&mut indexes, &table.name, index, &field_names);
}
if !indexes.is_empty() {
output.push_str(" indexes:\n");
output.push_str(&indexes);
}
match access {
AccessMode::None => {}
AccessMode::Public => output.push_str(
" access:\n list: { public: true }\n read: { public: true }\n create: { public: true }\n update: { public: true }\n delete: { public: true }\n",
),
AccessMode::Authenticated => output.push_str(
" access:\n list: { authenticated: true }\n read: { authenticated: true }\n create: { authenticated: true }\n update: { authenticated: true }\n delete: { authenticated: true }\n",
),
AccessMode::Role(role) => render_access_rule(output, "role", role),
AccessMode::Owner(owner) => render_access_rule(output, "owner", owner),
}
output.push('\n');
}
fn render_index(
&mut self,
output: &mut String,
table: &str,
index: &IntrospectedIndex,
field_names: &BTreeMap<&str, String>,
) {
let supported = matches!(
(index.method.as_str(), index.operator_class.as_deref()),
("btree", None) | ("gin", Some("gin_trgm_ops" | "jsonb_ops" | "jsonb_path_ops"))
);
if !supported {
self.warnings.push(format!(
"index `{}` uses unsupported method/operator classes and needs review",
index.name
));
return;
}
let Some(fields) = index
.columns
.iter()
.map(|column| field_names.get(column.as_str()).cloned())
.collect::<Option<Vec<_>>>()
else {
self.warnings.push(format!(
"index `{}` on table `{table}` references an expression or unknown column and needs review",
index.name
));
return;
};
let name = index
.name
.strip_prefix("idx_")
.unwrap_or(index.name.as_str());
let _ = writeln!(output, " - name: {}", yaml_string(name));
let rendered_fields = fields
.iter()
.map(|field| yaml_string(field))
.collect::<Vec<_>>()
.join(", ");
let _ = writeln!(output, " fields: [{rendered_fields}]");
if index.method != "btree" {
let _ = writeln!(output, " method: {}", index.method);
}
if let Some(class) = &index.operator_class {
let _ = writeln!(output, " operator_class: {class}");
}
if index.unique {
output.push_str(" unique: true\n");
}
if let Some(predicate) = &index.predicate {
let _ = writeln!(output, " where: {}", yaml_string(predicate));
}
}
fn render_column(
&mut self,
output: &mut String,
table: &IntrospectedTable,
column: &IntrospectedColumn,
relation: Option<&IntrospectedForeignKey>,
used_fields: &mut BTreeSet<String>,
) -> Option<String> {
let kind = spec_type(column);
if column.generated {
self.warnings.push(format!(
"column `{}.{}` is generated by PostgreSQL and was omitted from the writable App Spec draft",
table.name, column.name
));
return None;
}
if let SpecType::Unsupported(database_type) = &kind
&& relation.is_none()
{
self.warnings.push(format!(
"column `{}.{}` uses unsupported PostgreSQL type `{database_type}` and was omitted instead of being mapped to an incompatible JSON field",
table.name, column.name
));
return None;
}
let base = relation.map_or_else(
|| field_name(&column.name),
|_| field_name(column.name.strip_suffix("_id").unwrap_or(&column.name)),
);
let field = unique_name(&base, used_fields);
if let (Some(domain_schema), Some(domain_name)) =
(&column.domain_schema, &column.domain_name)
{
self.warnings.push(format!(
"column `{}.{}` uses domain `{}.{}` and was imported as its `{}` base type; review domain constraints",
table.name, column.name, domain_schema, domain_name, column.data_type
));
}
let _ = writeln!(output, " {field}:");
if let Some(key) = relation {
output.push_str(" type: relation\n");
if let Some(target) = self.entities.get(key.target_table.as_str()) {
let _ = writeln!(output, " target: {target}");
}
let _ = writeln!(output, " column: {}", yaml_string(&column.name));
if key.on_delete != "no_action" {
let _ = writeln!(output, " on_delete: {}", key.on_delete);
}
} else {
let _ = writeln!(output, " type: {}", kind.name());
if field != column.name {
let _ = writeln!(output, " column: {}", yaml_string(&column.name));
}
if let SpecType::Enum(values) = &kind {
let rendered = values
.iter()
.map(|value| yaml_string(value))
.collect::<Vec<_>>();
let _ = writeln!(output, " values: [{}]", rendered.join(", "));
self.warnings.push(format!(
"column `{}.{}` uses a native PostgreSQL enum; review the migration because AppStruct stores enums as text checks",
table.name, column.name
));
}
self.render_default(output, table, column, &kind);
}
let primary_key = table.primary_key.as_slice() == std::slice::from_ref(&column.name);
if primary_key {
output.push_str(" primary_key: true\n");
}
let required = !column.nullable
&& (relation.is_some()
|| (!primary_key && column.default.is_none() && !column.identity));
if required {
output.push_str(" required: true\n");
}
if table
.unique_constraints
.iter()
.any(|columns| columns.as_slice() == std::slice::from_ref(&column.name))
{
output.push_str(" unique: true\n");
}
if let Some(length) = column.max_length.filter(|length| *length > 0)
&& matches!(kind, SpecType::String)
{
let _ = writeln!(output, " max_length: {length}");
}
render_capabilities(output, &kind, relation.is_some());
Some(field)
}
fn render_default(
&mut self,
output: &mut String,
table: &IntrospectedTable,
column: &IntrospectedColumn,
kind: &SpecType,
) {
if column.identity || is_sequence_default(column.default.as_deref()) {
if matches!(kind, SpecType::Integer | SpecType::Bigint) {
output.push_str(" generated: auto_increment\n");
}
return;
}
let Some(value) = column.default.as_deref() else {
return;
};
if is_now_default(value) && matches!(kind, SpecType::Date | SpecType::Datetime) {
output.push_str(" generated: now\n");
} else if let Some(value) = scalar_default(value, kind) {
let _ = writeln!(output, " default: {}", yaml_string(&value));
} else {
self.warnings.push(format!(
"default for `{}.{}` could not be represented and was omitted",
table.name, column.name
));
}
}
}
fn render_access_rule(output: &mut String, kind: &str, value: &str) {
output.push_str(" access:\n");
for operation in ["list", "read", "create", "update", "delete"] {
let _ = writeln!(
output,
" {operation}: {{ {kind}: {} }}",
yaml_string(value)
);
}
}
fn usable_relations<'schema>(
schema: &'schema IntrospectedSchema,
entities: &BTreeMap<&'schema str, String>,
warnings: &mut Vec<String>,
) -> BTreeMap<(&'schema str, &'schema str), &'schema IntrospectedForeignKey> {
let tables = schema
.tables
.iter()
.map(|table| (table.name.as_str(), table))
.collect::<BTreeMap<_, _>>();
let mut relations = BTreeMap::new();
for key in &schema.foreign_keys {
let valid = key.source_columns.len() == 1
&& key.target_columns.len() == 1
&& key.target_schema == schema.name
&& entities.contains_key(key.source_table.as_str())
&& entities.contains_key(key.target_table.as_str())
&& tables.get(key.target_table.as_str()).is_some_and(|table| {
table.primary_key == key.target_columns && key.on_delete != "set_default"
});
if valid {
let relation_key = (key.source_table.as_str(), key.source_columns[0].as_str());
if relations.insert(relation_key, key).is_some() {
warnings.push(format!(
"column `{}.{}` has multiple foreign keys and needs review",
key.source_table, key.source_columns[0]
));
}
} else {
warnings.push(format!(
"foreign key `{}` was kept as scalar field(s), not a relation: {}",
key.name,
unusable_relation_reason(schema, entities, &tables, key)
));
}
}
relations
}
fn unusable_relation_reason(
schema: &IntrospectedSchema,
entities: &BTreeMap<&str, String>,
tables: &BTreeMap<&str, &IntrospectedTable>,
key: &IntrospectedForeignKey,
) -> String {
if key.source_columns.len() != 1 || key.target_columns.len() != 1 {
return format!(
"composite mapping [{}] -> [{}] is not supported; keep the imported scalar fields and model the association in application code",
key.source_columns.join(", "),
key.target_columns.join(", ")
);
}
if key.target_schema != schema.name {
return format!(
"target `{}.{}` is outside imported schema `{}`; import that schema separately and model the association in application code",
key.target_schema, key.target_table, schema.name
);
}
if !entities.contains_key(key.source_table.as_str()) {
return format!("source table `{}` was omitted", key.source_table);
}
if !entities.contains_key(key.target_table.as_str()) {
return format!("target table `{}` was omitted", key.target_table);
}
if key.on_delete == "set_default" {
return "ON DELETE SET DEFAULT is not supported".to_owned();
}
if tables
.get(key.target_table.as_str())
.is_some_and(|table| table.primary_key != key.target_columns)
{
return format!(
"target column `{}` is not the target entity primary key",
key.target_columns[0]
);
}
"the database relation does not match the generated entity contract".to_owned()
}